Checkpointer interface. Defines an ID-based checkpointing API for tree of related checkpoints which could be stored as ordered deltas internally. More...

#include <Checkpointer.hpp>

Inheritance diagram for sparta::serialization::checkpoint::Checkpointer:

[legend]

Collaboration diagram for sparta::serialization::checkpoint::Checkpointer:

[legend]

Public Types
Local Types
typedef Checkpoint::tick_t	tick_t
	tick_t Tick type to which checkpoints will refer

typedef Checkpoint::chkpt_id_t	chkpt_id_t
	tick_t Tick type to which checkpoints will refer

Public Member Functions
Construction & Initialization
	Checkpointer (TreeNode &root, sparta::Scheduler *sched=nullptr)
	Checkpointer Constructor.

virtual	~Checkpointer ()
	Destructor.

Attributes
const TreeNode &	getRoot () const noexcept
	Returns the root associated with this checkpointer.

TreeNode &	getRoot () noexcept
	Non-const variant of getRoot.

const Scheduler *	getScheduler () const noexcept
	Returns the sheduler associated with this checkpointer.

uint64_t	getTotalMemoryUse () const noexcept
	Computes and returns the memory usage by this checkpointer at this moment including any framework overhead.

uint64_t	getContentMemoryUse () const noexcept
	Computes and returns the memory usage by this checkpointer at this moment purely for the checkpoint state being held.

uint64_t	getTotalCheckpointsCreated () const noexcept
	Returns the total number of checkpoints which have been created by this checkpointer. This is unrelated to the current number of checkpoints in existance. Includes the head checkpoint if created.

Checkpointing Actions & Queries
void	createHead ()
	Creates a head without taking an identified checkpoint. Cannot already have a head.

chkpt_id_t	createCheckpoint (bool force_snapshot=false)
	Creates a checkpoint at the given scheduler's current tick with a new checkpoint ID some point after the current checkpoint (see getCurrentID). If the current checkpoint already has other next checkpoints, the new checkpoint will be an alternate branch of the current checkpoint. This snapshot may be stored as a full snapshot if the checkpointer requires it, or if the snapshot threshold is exceeded, or if the force_snapshot argument is true Current tick will be read from scheduler (if not null) and must be >= the head checkpoint's tick. The current tick must also be >= the current checkpoints tick (See getCurrenTick).

virtual void	deleteCheckpoint (chkpt_id_t id)=0
	Deletes a checkpoint by ID.

virtual void	loadCheckpoint (chkpt_id_t id)=0
	Loads state from a specific checkpoint by ID.

void	forgetCurrent ()
	Forgets the current checkpoint and current checkpoint (resetting to the head checkpoint) so that checkpoints can be taken at a different time without assuming simulation state continutiy with this checkpointers. This is ONLY to be used by a simulator IFF another checkpointer restores state at another cycle or the simulator resets but this checkpointer's tree is still expected to exist.

virtual std::vector< chkpt_id_t >	getCheckpointsAt (tick_t t) const =0
	Gets all checkpoints taken at tick t on any timeline.

virtual std::vector< chkpt_id_t >	getCheckpoints () const =0
	Gets all known checkpoint IDs available on any timeline sorted by tick (or equivalently checkpoint ID).

virtual uint32_t	getNumCheckpoints () const noexcept=0
	Gets the current number of checkpoints having valid IDs which a client of this interface can refer to.

virtual std::deque< chkpt_id_t >	getCheckpointChain (chkpt_id_t id) const =0
	Debugging utility which gets a deque of checkpoints representing a chain starting at the checkpoint head and ending at the checkpoint specified by id. Ths results can contain Checkpoint::UNIDENTIFIED_CHECKPOINT to represent temporary deleted checkpoints in the chain.

virtual Checkpoint *	findLatestCheckpointAtOrBefore (tick_t tick, chkpt_id_t from)=0
	Finds the latest checkpoint at or before the given tick starting at the from checkpoint and working backward. If no checkpoints before or at tick are found, returns nullptr.

Checkpoint *	findCheckpoint (chkpt_id_t id) noexcept
	Finds a checkpoint by its ID.

virtual bool	hasCheckpoint (chkpt_id_t id) const noexcept
	Tests whether this checkpoint manager has a checkpoint with the given id.

const Checkpoint *	getHead () const noexcept
	Returns the head checkpoint which is equivalent to the earliest checkpoint taken.

chkpt_id_t	getHeadID () const noexcept
	Returns the checkpoint ID of the head checkpoint (if it exists) which is equivalent to the earliest checkpoint taken.

chkpt_id_t	getCurrentID () const
	Returns the current checkpoint ID. This is mainly a debugging utility as the current ID changes when adding, deleting, and loading checkpoints based on whether the checkpoints take were deltas or snapshots. A correct integration of the checkpointer by a simulator should not depend on this method for behavior decisions.

tick_t	getCurrentTick () const
	Gets the tick number of the current checkpoint (see getCurrentID). This is the tick number of the latest checkpoint either saved or written through this checkpointer. The next checkpoint taken will be on the same chain as a checkpoint taken at this tick.

Printing Methods
virtual std::string	stringize () const
	Returns a string describing this object.

void	dumpList (std::ostream &o) const
	Dumps this checkpointer's flat list of checkpoints to an ostream with a newline following each checkpoint.

void	dumpData (std::ostream &o) const
	Dumps this checkpointer's data to an ostream with a newline following each checkpoint.

void	dumpAnnotatedData (std::ostream &o) const
	Dumps this checkpointer's data to an ostream with annotations between each ArchData and a newline following each checkpoint description and each checkpoint data dump.

virtual void	traceValue (std::ostream &o, chkpt_id_t id, const ArchData *container, uint32_t offset, uint32_t size)=0
	Debugging utility which dumps values in some bytes across a chain of checkpoints. The intent is to show the values loaded when attempting to restore needed to restore the given value in the selected checkpoint.

void	dumpTree (std::ostream &o) const
	Dumps this checkpointer's tree to an ostream with a line for each branch. Printout timescale is not relevant. Multi-line printouts for deep branches will be difficult to read.

void	dumpBranch (std::ostream &o, const Checkpoint *chkpt, uint32_t indent, uint32_t pos, std::deque< uint32_t > &continues) const
	Recursively dumps one branch (and sub-branches) to an ostream with a line for each branch.

Protected Member Functions
virtual Checkpoint *	findCheckpoint_ (chkpt_id_t id) noexcept=0
	Attempts to find a checkpoint within this checkpointer by ID.

virtual const Checkpoint *	findCheckpoint_ (chkpt_id_t id) const noexcept=0
	const variant of findCheckpoint_

virtual void	createHead_ ()=0
	Create a head node.

virtual chkpt_id_t	createCheckpoint_ (bool force_snapshot=false)=0
	Create a checkpoint.

virtual void	dumpCheckpointNode_ (const Checkpoint *chkpt, std::ostream &o) const

const std::vector< ArchData * > &	getArchDatas () const
	Returns ArchDatas enumerated by this Checkpointer for iteration when saving or loading checkpoint data.

Checkpoint *	getHead_ () noexcept
	Non-const variant of getHead_.

const Checkpoint *	getHead_ () const noexcept
	Gets the head checkpoint. Returns nullptr if none created yet.

void	setHead_ (Checkpoint *head)
	Sets the head checkpointer pointer to head for the first time.

Checkpoint *	getCurrent_ () const noexcept
	Gets the current checkpointer pointer. Returns nullptr if there is no current checkpoint object.

void	setCurrent_ (Checkpoint *current)
	Sets the current checkpoint pointer.

Protected Attributes
std::map< chkpt_id_t, std::unique_ptr< Checkpoint > >	chkpts_
	All checkpoints sorted by ascending tick number (or equivalently ascending checkpoint ID since both are monotonically increasing)

Scheduler *const	sched_
	Scheduler whose tick count will be set and read. Cannnot be updated after first checkpoint without bad side effects. Keeping this const for simplicity.

Detailed Description

Checkpointer interface. Defines an ID-based checkpointing API for tree of related checkpoints which could be stored as ordered deltas internally.

Internal storage and structure are to be defined by implementations of this interface

A checkpoint tree may look something like the following, where each checkpoint is shown here by its simulation tick number (not ID)

* t=0 (head) --> t=100 +-> t=300
*                      |
*                      `-> t=320 --> t=400 +-> t=500
*                      |                   `-> t=430
*                      `-> t=300
*

The procedure for using a Checkpointer is generally:

Create SPARTA Tree
Construct Checkpointer
Finalize SPARTA Tree
Initialize simulation
Checkpointer::createHead

Then:

<run simulation>
Checkpointer::createCheckpoint
<run simulation>
Checkpointer::loadCheckpoint
repeat in any order necessary

Definition at line 56 of file Checkpointer.hpp.

Member Typedef Documentation

◆ chkpt_id_t

typedef Checkpoint::chkpt_id_t sparta::serialization::checkpoint::Checkpointer::chkpt_id_t

tick_t Tick type to which checkpoints will refer

Definition at line 68 of file Checkpointer.hpp.

◆ tick_t

typedef Checkpoint::tick_t sparta::serialization::checkpoint::Checkpointer::tick_t

tick_t Tick type to which checkpoints will refer

Definition at line 65 of file Checkpointer.hpp.

Constructor & Destructor Documentation

◆ Checkpointer()

sparta::serialization::checkpoint::Checkpointer::Checkpointer	(	TreeNode &	root,
		sparta::Scheduler *	sched = `nullptr`
	)

inline

Checkpointer Constructor.

Parameters

root	TreeNode at which checkpoints will be taken. This cannot be changed later. This does not necessarily need to be a RootTreeNode. Before the first checkpoint is taken, this node must be finalized (see sparta::TreeNode::isFinalized). At this point, the node does not need to be finalized
sched	Relevant scheduler. If nullptr (default), the checkpointer will not touch attempt to roll back the scheduler on checkpoint restores

Definition at line 88 of file Checkpointer.hpp.

◆ ~Checkpointer()

virtual sparta::serialization::checkpoint::Checkpointer::~Checkpointer ( )

inlinevirtual

Destructor.

Definition at line 99 of file Checkpointer.hpp.

Member Function Documentation

◆ createCheckpoint()

chkpt_id_t sparta::serialization::checkpoint::Checkpointer::createCheckpoint ( bool force_snapshot = false )

inline

Creates a checkpoint at the given scheduler's current tick with a new checkpoint ID some point after the current checkpoint (see getCurrentID). If the current checkpoint already has other next checkpoints, the new checkpoint will be an alternate branch of the current checkpoint. This snapshot may be stored as a full snapshot if the checkpointer requires it, or if the snapshot threshold is exceeded, or if the force_snapshot argument is true Current tick will be read from scheduler (if not null) and must be >= the head checkpoint's tick. The current tick must also be >= the current checkpoints tick (See getCurrenTick).

Parameters

force_snapshot Forces the newly-created checkpoint to be a full snapshot instead of allowing the checkpointer to decide based on getSnapshotThreshold. A snapshot takes more time and space to store, but this can be a performance optimization if this checkpoint will be re-loaded very frequently

Precondition: Root must be finalized at this time.

Postcondition: If no head exists, one will be created. See getHead; Sets the newly created checkpoint as the current. See getCurrentID

Exceptions

CheckpointError if a head checkpoint exists and the current tick is less than the head checkpoint's tick, or if the root TreeNode is not finalized. Also throws if the number of checkpoint IDs has been exhausted (i.e. all values of a chkpt_id_t have been used as IDs). This is unlikely and has a special exception message.

Definition at line 249 of file Checkpointer.hpp.

Here is the call graph for this function:

◆ createCheckpoint_()

virtual chkpt_id_t sparta::serialization::checkpoint::Checkpointer::createCheckpoint_ ( bool force_snapshot = false )

protectedpure virtual

Create a checkpoint.

Precondition: Guaranteed to have a valid head at this time (getHead() != nullptr)

Postcondition: Must create a checkpoint

Returns: Must return a checkpoint ID not currently in use

Note: invoked by createHead

Here is the call graph for this function:

◆ createHead()

void sparta::serialization::checkpoint::Checkpointer::createHead ( )

inline

Creates a head without taking an identified checkpoint. Cannot already have a head.

Precondition: Must not have called createHead or createCheckpoint before this.; Root must be finalized at this time.

Postcondition: Head will be created at given tick and getHead will return this head.; Head will become the current checkpoint. See getCurrent

Exceptions

CheckpointError if root is not yet finalized or a head already exists for this checkpointer

Postcondition: Tick number from scheduler is recorded at this time. Future checkpoints cannot be created at tick numbers lower than this. Equal tick numbers are allowed

Generally, this is called after all simulation state is initialized (e.g. resisters set) since it makes little sense to go back to a pre-initialized state.

Test for a head if necessary with getHead(). Typically, this should be called before running the simulation.

Definition at line 187 of file Checkpointer.hpp.

Here is the call graph for this function:

◆ createHead_()

virtual void sparta::serialization::checkpoint::Checkpointer::createHead_ ( )

protectedpure virtual

Create a head node.

Precondition: ArchDatas for tree root are already enumerated; Tree of getRoot() is already finalized; Guaranteed to have a null head at this time (getHead() == nullptr)

Postcondition: Must create a head checkpoint; Must invoke setHead_

Note: invoked by createHead

◆ deleteCheckpoint()

virtual void sparta::serialization::checkpoint::Checkpointer::deleteCheckpoint ( chkpt_id_t id )

pure virtual

Deletes a checkpoint by ID.

Parameters

id	ID of checkpoint to delete. Must not be Checkpoint::UNIDENTIFIED_CHECKPOINT and must not be equal to the ID of the head checkpoint.

Exceptions

CheckpointError if this manager has no checkpoint with given id. Test with hasCheckpoint first. If id == Checkpoint::UNIDENTIFIED_CHECKPOINT, always throws. Throws if id == getHeadID(). Head cannot be deleted

Internally, this deletion may be effective-only and actual data may still exist in an incaccessible form as part of the checkpoint tree implementation.

If the current checkpoint is deleted, current will be updated back along the current checkpoints previous checkpoint chain until a non deleted checkpoint is found. This will become the new current checkpoint

Implemented in sparta::serialization::checkpoint::FastCheckpointer.

◆ dumpAnnotatedData()

void sparta::serialization::checkpoint::Checkpointer::dumpAnnotatedData ( std::ostream & o ) const

inline

Dumps this checkpointer's data to an ostream with annotations between each ArchData and a newline following each checkpoint description and each checkpoint data dump.

Parameters

o	ostream to dump to

Definition at line 532 of file Checkpointer.hpp.

◆ dumpBranch()

void sparta::serialization::checkpoint::Checkpointer::dumpBranch	(	std::ostream &	o,
		const Checkpoint *	chkpt,
		uint32_t	indent,
		uint32_t	pos,
		std::deque< uint32_t > &	continues
	)		const

inline

Recursively dumps one branch (and sub-branches) to an ostream with a line for each branch.

Parameters

o	ostream to dump to
chkpt	Checkpoint to start printint at
indent	Number of spaces to indent before printing this branch
pos	Position on line.
continues	Vector of continue indent points where '\|' characters should be printed on lines whose indent amount is greater than each particular indent point. This creates the vertical lines expected in directory-like tree-view displays

Todo:: Move the constants somewhere static outside this function (especially the assert)

Definition at line 580 of file Checkpointer.hpp.

Here is the call graph for this function:

◆ dumpCheckpointNode_()

virtual void sparta::serialization::checkpoint::Checkpointer::dumpCheckpointNode_	(	const Checkpoint *	chkpt,
		std::ostream &	o
	)		const

inlineprotectedvirtual

Reimplemented in sparta::serialization::checkpoint::FastCheckpointer.

Definition at line 692 of file Checkpointer.hpp.

◆ dumpData()

void sparta::serialization::checkpoint::Checkpointer::dumpData ( std::ostream & o ) const

inline

Dumps this checkpointer's data to an ostream with a newline following each checkpoint.

Parameters

o	ostream to dump to

Definition at line 519 of file Checkpointer.hpp.

◆ dumpList()

void sparta::serialization::checkpoint::Checkpointer::dumpList ( std::ostream & o ) const

inline

Dumps this checkpointer's flat list of checkpoints to an ostream with a newline following each checkpoint.

Parameters

o	ostream to dump to

Definition at line 508 of file Checkpointer.hpp.

◆ dumpTree()

void sparta::serialization::checkpoint::Checkpointer::dumpTree ( std::ostream & o ) const

inline

Dumps this checkpointer's tree to an ostream with a line for each branch. Printout timescale is not relevant. Multi-line printouts for deep branches will be difficult to read.

Parameters

o	ostream to dump to

Definition at line 562 of file Checkpointer.hpp.

Here is the call graph for this function:

◆ findCheckpoint()

Checkpoint * sparta::serialization::checkpoint::Checkpointer::findCheckpoint ( chkpt_id_t id )

inlinenoexcept

Finds a checkpoint by its ID.

Parameters

id	ID of checkpoint to find. Guaranteed not to be flagged as deleted

Returns: Checkpoint with ID of id if found or nullptr if not found

Definition at line 390 of file Checkpointer.hpp.

Here is the call graph for this function:

◆ findCheckpoint_() [1/2]

virtual const Checkpoint * sparta::serialization::checkpoint::Checkpointer::findCheckpoint_ ( chkpt_id_t id ) const

protectedpure virtualnoexcept

const variant of findCheckpoint_

Implemented in sparta::serialization::checkpoint::FastCheckpointer.

◆ findCheckpoint_() [2/2]

virtual Checkpoint * sparta::serialization::checkpoint::Checkpointer::findCheckpoint_ ( chkpt_id_t id )

protectedpure virtualnoexcept

Attempts to find a checkpoint within this checkpointer by ID.

Parameters

id	Checkpoint ID to search for

Returns: Pointer to found checkpoint with matchind ID. If not found, returns nullptr.

Todo:: Faster lookup?

Implemented in sparta::serialization::checkpoint::FastCheckpointer.

◆ findLatestCheckpointAtOrBefore()

virtual Checkpoint * sparta::serialization::checkpoint::Checkpointer::findLatestCheckpointAtOrBefore	(	tick_t	tick,
		chkpt_id_t	from
	)

pure virtual

Finds the latest checkpoint at or before the given tick starting at the from checkpoint and working backward. If no checkpoints before or at tick are found, returns nullptr.

Parameters

tick	Tick to search for
from	Checkpoint at which to begin searching for a tick. Must be a valid checkpoint known by this checkpointer. See hasCheckpoint.

Returns: The latest checkpoint with a tick number less than or equal to the tick argument. Returns nullptr if no checkpoints before tick were found. It is possible for the checkpoint identified by from could be returned.

Warning: This is not a high-performance method. Generally, a client of this interface knows a paticular ID.

Exceptions

CheckpointError if from does not refer to a valid checkpoint.

Implemented in sparta::serialization::checkpoint::FastCheckpointer.

◆ forgetCurrent()

void sparta::serialization::checkpoint::Checkpointer::forgetCurrent ( )

inline

Forgets the current checkpoint and current checkpoint (resetting to the head checkpoint) so that checkpoints can be taken at a different time without assuming simulation state continutiy with this checkpointers. This is ONLY to be used by a simulator IFF another checkpointer restores state at another cycle or the simulator resets but this checkpointer's tree is still expected to exist.

Warning: Read the documentation for this method carefully. If it is being used in a simulator with only 1 checkpointer operating at a time, it is very likely that loadCheckpoint should be used instead of this.

Postcondition: getCurrentTick() and getCurrentID() will refer to the head.

Note: No checkpoints are deleted or created or reorganized in any way.; New checkpoints on this scheduler must still be created at a tick number >= this scheduler's head checkpoint tick.; has no effect if the head has no been created.

Definition at line 312 of file Checkpointer.hpp.

◆ getArchDatas()

const std::vector< ArchData * > & sparta::serialization::checkpoint::Checkpointer::getArchDatas ( ) const

inlineprotected

Returns ArchDatas enumerated by this Checkpointer for iteration when saving or loading checkpoint data.

Definition at line 700 of file Checkpointer.hpp.

◆ getCheckpointChain()

virtual std::deque< chkpt_id_t > sparta::serialization::checkpoint::Checkpointer::getCheckpointChain ( chkpt_id_t id ) const

pure virtual

Debugging utility which gets a deque of checkpoints representing a chain starting at the checkpoint head and ending at the checkpoint specified by id. Ths results can contain Checkpoint::UNIDENTIFIED_CHECKPOINT to represent temporary deleted checkpoints in the chain.

Parameters

id	ID of checkpoint that terminates the chain

Returns: dequeue of checkpoint IDs where the front is always the head and the back is always the checkpoint described by id. If there is no checkpoint head, returns an empty result

Exceptions

CheckpointError if id does not refer to a valid checkpoint.

Note: Makes a new vector of results. This should not be called in the critical path.

Implemented in sparta::serialization::checkpoint::FastCheckpointer.

◆ getCheckpoints()

virtual std::vector< chkpt_id_t > sparta::serialization::checkpoint::Checkpointer::getCheckpoints ( ) const

pure virtual

Gets all known checkpoint IDs available on any timeline sorted by tick (or equivalently checkpoint ID).

Returns: vector of valid checkpoint IDs (never Checkpoint::UNIDENTIFIED_CHECKPOINT)

Note: Makes a new vector of results. This should not be called in a performance-critical path.

Implemented in sparta::serialization::checkpoint::FastCheckpointer.

◆ getCheckpointsAt()

virtual std::vector< chkpt_id_t > sparta::serialization::checkpoint::Checkpointer::getCheckpointsAt ( tick_t t ) const

pure virtual

Gets all checkpoints taken at tick t on any timeline.

Parameters

t	Tick number at which checkpoints should found.

Returns: vector of valid checkpoint IDs (never Checkpoint::UNIDENTIFIED_CHECKPOINT)

Note: Makes a new vector of results. This should not be called in a performance-critical path.

Implemented in sparta::serialization::checkpoint::FastCheckpointer.

◆ getContentMemoryUse()

uint64_t sparta::serialization::checkpoint::Checkpointer::getContentMemoryUse ( ) const

inlinenoexcept

Computes and returns the memory usage by this checkpointer at this moment purely for the checkpoint state being held.

Definition at line 142 of file Checkpointer.hpp.

◆ getCurrent_()

Checkpoint * sparta::serialization::checkpoint::Checkpointer::getCurrent_ ( ) const

inlineprotectednoexcept

Gets the current checkpointer pointer. Returns nullptr if there is no current checkpoint object.

Definition at line 735 of file Checkpointer.hpp.

◆ getCurrentID()

chkpt_id_t sparta::serialization::checkpoint::Checkpointer::getCurrentID ( ) const

inline

Returns the current checkpoint ID. This is mainly a debugging utility as the current ID changes when adding, deleting, and loading checkpoints based on whether the checkpoints take were deltas or snapshots. A correct integration of the checkpointer by a simulator should not depend on this method for behavior decisions.

Returns: ID of current checkpoint. If there is no current checkpoint, or the current checkpoint is an internal-only checkpoint, returns Checkpoint::UNIDENTIFIED_CHECKPOINT. A return value of Checkpoint::UNIDENTIFIED_CHECKPOINT usually only happens before the head is created and when the current checkpoint is deleted.

The current checkpoint refers to the most recent checkpoint either loaded or created. This value is used to refer to the previous-checkpoint when creating a delta checkpoint.

Loading, creating, and deleting a checkpoint updates the current checkpoint.

If the previous current checkpoint was deleted, current is updated to refer back to the most recent previous checkpoint in the same previous-checkpoint chain of one which was deleted.

Definition at line 459 of file Checkpointer.hpp.

Here is the call graph for this function:

◆ getCurrentTick()

tick_t sparta::serialization::checkpoint::Checkpointer::getCurrentTick ( ) const

inline

Gets the tick number of the current checkpoint (see getCurrentID). This is the tick number of the latest checkpoint either saved or written through this checkpointer. The next checkpoint taken will be on the same chain as a checkpoint taken at this tick.

Note: The next call to createCheckpoint will require the scheduler current tick to be greater than or equal to the tick returned by this method

Returns: tick number of 'current' checkpoint. If there is no current checkpoint, returns 0

Definition at line 479 of file Checkpointer.hpp.

Here is the call graph for this function:

◆ getHead()

const Checkpoint * sparta::serialization::checkpoint::Checkpointer::getHead ( ) const

inlinenoexcept

Returns the head checkpoint which is equivalent to the earliest checkpoint taken.

Returns: Head checkpoint. nullptr if 0 checkpoints have been taken with this manager. Once the first checkpoint is taken or the head is explicitly created, will always be non-nullptr

The head checkpoint has an ID of Checkpoint::UNIDENTIFIED_CHECKPOINT and can never be deleted.

Definition at line 415 of file Checkpointer.hpp.

◆ getHead_() [1/2]

const Checkpoint * sparta::serialization::checkpoint::Checkpointer::getHead_ ( ) const

inlineprotectednoexcept

Gets the head checkpoint. Returns nullptr if none created yet.

Definition at line 714 of file Checkpointer.hpp.

◆ getHead_() [2/2]

Checkpoint * sparta::serialization::checkpoint::Checkpointer::getHead_ ( )

inlineprotectednoexcept

Non-const variant of getHead_.

Definition at line 707 of file Checkpointer.hpp.

◆ getHeadID()

chkpt_id_t sparta::serialization::checkpoint::Checkpointer::getHeadID ( ) const

inlinenoexcept

Returns the checkpoint ID of the head checkpoint (if it exists) which is equivalent to the earliest checkpoint taken.

Returns: Head checkpoint ID. Checkpoint::UNIDENTIFIED_CHECKPOINT if there is no head. Once the first checkpoint is taken or the head is explicitly created, will always be a valid checkpoint identifier.

The head checkpoint can never be deleted.

Definition at line 428 of file Checkpointer.hpp.

Here is the call graph for this function:

◆ getNumCheckpoints()

virtual uint32_t sparta::serialization::checkpoint::Checkpointer::getNumCheckpoints ( ) const

pure virtualnoexcept

Gets the current number of checkpoints having valid IDs which a client of this interface can refer to.

Ignores any internal temporary or deleted checkpoints without visible IDs

Implemented in sparta::serialization::checkpoint::FastCheckpointer.

◆ getRoot() [1/2]

const TreeNode & sparta::serialization::checkpoint::Checkpointer::getRoot ( ) const

inlinenoexcept

Returns the root associated with this checkpointer.

Definition at line 112 of file Checkpointer.hpp.

◆ getRoot() [2/2]

TreeNode & sparta::serialization::checkpoint::Checkpointer::getRoot ( )

inlinenoexcept

Non-const variant of getRoot.

Definition at line 117 of file Checkpointer.hpp.

◆ getScheduler()

const Scheduler * sparta::serialization::checkpoint::Checkpointer::getScheduler ( ) const

inlinenoexcept

Returns the sheduler associated with this checkpointer.

Definition at line 122 of file Checkpointer.hpp.

◆ getTotalCheckpointsCreated()

uint64_t sparta::serialization::checkpoint::Checkpointer::getTotalCheckpointsCreated ( ) const

inlinenoexcept

Returns the total number of checkpoints which have been created by this checkpointer. This is unrelated to the current number of checkpoints in existance. Includes the head checkpoint if created.

Definition at line 155 of file Checkpointer.hpp.

◆ getTotalMemoryUse()

uint64_t sparta::serialization::checkpoint::Checkpointer::getTotalMemoryUse ( ) const

inlinenoexcept

Computes and returns the memory usage by this checkpointer at this moment including any framework overhead.

Note: This is an approxiation and does not include some of minimal dynamic overhead from stl containers.

Definition at line 130 of file Checkpointer.hpp.

◆ hasCheckpoint()

virtual bool sparta::serialization::checkpoint::Checkpointer::hasCheckpoint ( chkpt_id_t id ) const

inlinevirtualnoexcept

Tests whether this checkpoint manager has a checkpoint with the given id.

Returns: True if id refers to a checkpoint held by this checkpointer and false if not. If id == Checkpoint::UNIDENTIFIED_CHECKPOINT, always returns false

Definition at line 401 of file Checkpointer.hpp.

Here is the call graph for this function:

◆ loadCheckpoint()

virtual void sparta::serialization::checkpoint::Checkpointer::loadCheckpoint ( chkpt_id_t id )

pure virtual

Loads state from a specific checkpoint by ID.

Note: Does not delete checkpoints. Checkpoints must be explicitly deleted by deleteCheckpoint

Exceptions

CheckpointError if id does not refer to checkpoint that exists or if checkpoint could not be load.

Warning: If checkpoint fails during loading for reasons other than an invalid ID, the simulation state could be corrupt

Postcondition: current checkpoint is now the checkpoint specified by id; Sets scheduler current tick to the checkpoint's tick using Scheduler::restartAt

Implemented in sparta::serialization::checkpoint::FastCheckpointer.

◆ setCurrent_()

void sparta::serialization::checkpoint::Checkpointer::setCurrent_ ( Checkpoint * current )

inlineprotected

Sets the current checkpoint pointer.

Parameters

current Pointer to set as current checkpoint. The next checkpoint created will follow the current checkpoint set here. Cannot be nullptr

Definition at line 745 of file Checkpointer.hpp.

◆ setHead_()

void sparta::serialization::checkpoint::Checkpointer::setHead_ ( Checkpoint * head )

inlineprotected

Sets the head checkpointer pointer to head for the first time.

Parameters

head	New head checkpoint pointer. Must not be nullptr

Precondition: Internal head pointer must be nullptr.

Note: This can only be done once

Definition at line 725 of file Checkpointer.hpp.

◆ stringize()

virtual std::string sparta::serialization::checkpoint::Checkpointer::stringize ( ) const

inlinevirtual

Returns a string describing this object.

Reimplemented in sparta::serialization::checkpoint::FastCheckpointer.

Definition at line 497 of file Checkpointer.hpp.

Here is the call graph for this function:

◆ traceValue()

virtual void sparta::serialization::checkpoint::Checkpointer::traceValue	(	std::ostream &	o,
		chkpt_id_t	id,
		const ArchData *	container,
		uint32_t	offset,
		uint32_t	size
	)

pure virtual

Debugging utility which dumps values in some bytes across a chain of checkpoints. The intent is to show the values loaded when attempting to restore needed to restore the given value in the selected checkpoint.

Parameters

o	ostream with each value and checkpoint ID will be printed
id	ID of checkpoint to "restore" value from
container	ArchData in which the data being traced lives
offset	Offset into container
size	Bytes to read at offset

Warning: This may change checkpoint data read/write state and should only be done between completed checkpoints saves/restores in order to not interfere.

Implemented in sparta::serialization::checkpoint::FastCheckpointer.

Member Data Documentation

◆ chkpts_

std::map<chkpt_id_t, std::unique_ptr<Checkpoint> > sparta::serialization::checkpoint::Checkpointer::chkpts_

protected

All checkpoints sorted by ascending tick number (or equivalently ascending checkpoint ID since both are monotonically increasing)

This map must still be explicitly torn down in reverse order by a subclass of Checkpointer

Definition at line 759 of file Checkpointer.hpp.

◆ sched_

Scheduler* const sparta::serialization::checkpoint::Checkpointer::sched_

protected

Scheduler whose tick count will be set and read. Cannnot be updated after first checkpoint without bad side effects. Keeping this const for simplicity.

Definition at line 766 of file Checkpointer.hpp.

The documentation for this class was generated from the following file:

/github/workspace/sparta/sparta/serialization/checkpoint/Checkpointer.hpp

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ chkpt_id_t

◆ tick_t

Constructor & Destructor Documentation

◆ Checkpointer()

◆ ~Checkpointer()

Member Function Documentation

◆ createCheckpoint()

◆ createCheckpoint_()

◆ createHead()

◆ createHead_()

◆ deleteCheckpoint()

◆ dumpAnnotatedData()

◆ dumpBranch()

◆ dumpCheckpointNode_()

◆ dumpData()

◆ dumpList()

◆ dumpTree()

◆ findCheckpoint()

◆ findCheckpoint_() [1/2]

◆ findCheckpoint_() [2/2]

◆ findLatestCheckpointAtOrBefore()

◆ forgetCurrent()

◆ getArchDatas()

◆ getCheckpointChain()

◆ getCheckpoints()

◆ getCheckpointsAt()

◆ getContentMemoryUse()

◆ getCurrent_()

◆ getCurrentID()

◆ getCurrentTick()

◆ getHead()

◆ getHead_() [1/2]

◆ getHead_() [2/2]

◆ getHeadID()

◆ getNumCheckpoints()

◆ getRoot() [1/2]

◆ getRoot() [2/2]

◆ getScheduler()

◆ getTotalCheckpointsCreated()

◆ getTotalMemoryUse()

◆ hasCheckpoint()

◆ loadCheckpoint()

◆ setCurrent_()

◆ setHead_()

◆ stringize()

◆ traceValue()

Member Data Documentation

◆ chkpts_

◆ sched_