Implementation of the FastCheckpointer which only holds a subset of checkpoints in memory at any given time, and sends checkpoints outside this window to/from SimDB as needed using an LRU cache. More...

#include <DatabaseCheckpointer.hpp>

Inheritance diagram for sparta::serialization::checkpoint::DatabaseCheckpointer:

[legend]

Collaboration diagram for sparta::serialization::checkpoint::DatabaseCheckpointer:

[legend]

Public Types
using	checkpoint_type = DatabaseCheckpoint

using	checkpoint_ptr = std::shared_ptr<checkpoint_type>

using	checkpoint_ptrs = std::vector<checkpoint_ptr>

using	window_id_t = uint64_t

Public Types inherited from sparta::serialization::checkpoint::Checkpointer
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
	DatabaseCheckpointer (simdb::DatabaseManager db_mgr, const std::vector< sparta::TreeNode > &roots, sparta::Scheduler *sched=nullptr)
	DatabaseCheckpointer constructor.

void	createPipeline (simdb::pipeline::PipelineManager *pipeline_mgr) override
	Instantiate the async processing pipeline to save/load checkpoints.

void	preTeardown () override
	Flush all cached windows down the pipeline before threads are shut down.

uint32_t	getSnapshotThreshold () const
	Returns the next-shapshot threshold.

void	setSnapshotThreshold (uint32_t thresh)
	Sets the snapshot threshold.

void	setMaxCachedWindows (uint32_t max_windows)
	Sets the max number of cached windows (LRU).

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

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

void	deleteCheckpoint (chkpt_id_t) override final
	Explicit checkpoint deletion is NOT supported by this checkpointer.

void	loadCheckpoint (chkpt_id_t id) override
	Loads state from a specific checkpoint by ID.

std::vector< chkpt_id_t >	getCheckpointsAt (tick_t t) override
	Gets all checkpoints taken at tick t.

std::vector< chkpt_id_t >	getCheckpoints () override
	Gets all checkpoint IDs sorted by tick (or equivalently checkpoint ID).

uint32_t	getNumCheckpoints () const noexcept override
	Gets the current number of checkpoints with valid IDs.

uint32_t	getNumSnapshots () const noexcept
	Gets the current number of snapshots with valid IDs.

uint32_t	getNumDeltas () const noexcept
	Gets the current number of delta checkpoints with valid IDs.

std::deque< chkpt_id_t >	getCheckpointChain (chkpt_id_t id) override
	Debugging utility which gets a deque of checkpoints representing a chain starting at the checkpoint head and ending at the checkpoint specified by id.

std::shared_ptr< DatabaseCheckpoint >	findCheckpoint (chkpt_id_t id, bool must_exist=false)
	Finds a checkpoint by its ID.

std::shared_ptr< DatabaseCheckpoint >	findLatestCheckpointAtOrBefore (tick_t tick, chkpt_id_t from)
	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.

bool	hasCheckpoint (chkpt_id_t id) noexcept override
	Tests whether this checkpoint manager has a checkpoint with the given id in the cache or in the database.

void	dumpRestoreChain (std::ostream &o, chkpt_id_t id)
	Dumps the restore chain for this checkpoint.

std::stack< chkpt_id_t >	getHistoryChain (chkpt_id_t id)
	Returns a stack of checkpoints from this checkpoint as far back as possible until no previous link is found.

std::stack< chkpt_id_t >	getRestoreChain (chkpt_id_t id)
	Returns a stack of checkpoints that must be restored from top-to-bottom to fully restore the state associated with this checkpoint.

std::vector< chkpt_id_t >	getNextIDs (chkpt_id_t id) override
	Returns IDs of the checkpoints immediately following the given checkpoint.

uint32_t	getDistanceToPrevSnapshot (chkpt_id_t id) noexcept
	Determines how many checkpoints away the closest, earlier snapshot is.

bool	isSnapshot (chkpt_id_t id) noexcept
	Check if the given checkpoint is a snapshot (not a delta).

std::string	stringize () const override
	Returns a string describing this object.

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

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

void	dumpAnnotatedData (std::ostream &o) override
	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.

void	traceValue (std::ostream &o, chkpt_id_t id, const ArchData *container, uint32_t offset, uint32_t size) override
	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 the given value in the selected checkpoint.

bool	isCheckpointCached (chkpt_id_t id) const noexcept
	Check if the given checkpoint is currently cached in memory.

Public Member Functions inherited from sparta::serialization::checkpoint::Checkpointer
	Checkpointer (TreeNode &root, sparta::Scheduler *sched=nullptr)
	Checkpointer Constructor.

	Checkpointer (const std::vector< TreeNode * > &roots, sparta::Scheduler *sched=nullptr)
	Checkpointer Constructor.

virtual	~Checkpointer ()
	Destructor.

const std::vector< TreeNode * > &	getRoots () const noexcept
	Returns the root(s) associated with this checkpointer.

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

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.

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).

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.

const CheckpointBase *	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.

void	dumpTree (std::ostream &o)
	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 chkpt_id_t chkpt, uint32_t indent, uint32_t pos, std::deque< uint32_t > &continues)
	Recursively dumps one branch (and sub-branches) to an ostream with a line for each branch.

Static Public Member Functions
static void	defineSchema (simdb::Schema &schema)
	Define the SimDB schema for this checkpointer.

Static Public Attributes
static constexpr auto	NAME = "db-checkpointer"

Additional Inherited Members
Protected Member Functions inherited from sparta::serialization::checkpoint::Checkpointer
const std::vector< ArchData * > &	getArchDatas () const
	Returns ArchDatas enumerated by this Checkpointer for iteration when saving or loading checkpoint data.

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

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

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

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

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

Protected Attributes inherited from sparta::serialization::checkpoint::Checkpointer
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

Implementation of the FastCheckpointer which only holds a subset of checkpoints in memory at any given time, and sends checkpoints outside this window to/from SimDB as needed using an LRU cache.

Definition at line 22 of file DatabaseCheckpointer.hpp.

Member Typedef Documentation

◆ checkpoint_ptr

using sparta::serialization::checkpoint::DatabaseCheckpointer::checkpoint_ptr = std::shared_ptr<checkpoint_type>

Definition at line 28 of file DatabaseCheckpointer.hpp.

◆ checkpoint_ptrs

using sparta::serialization::checkpoint::DatabaseCheckpointer::checkpoint_ptrs = std::vector<checkpoint_ptr>

Definition at line 29 of file DatabaseCheckpointer.hpp.

◆ checkpoint_type

using sparta::serialization::checkpoint::DatabaseCheckpointer::checkpoint_type = DatabaseCheckpoint

Definition at line 27 of file DatabaseCheckpointer.hpp.

◆ window_id_t

using sparta::serialization::checkpoint::DatabaseCheckpointer::window_id_t = uint64_t

Definition at line 30 of file DatabaseCheckpointer.hpp.

Constructor & Destructor Documentation

◆ DatabaseCheckpointer()

sparta::serialization::checkpoint::DatabaseCheckpointer::DatabaseCheckpointer	(	simdb::DatabaseManager *	db_mgr,
		const std::vector< sparta::TreeNode * > &	roots,
		sparta::Scheduler *	sched = nullptr )

DatabaseCheckpointer constructor.

Parameters

db_mgr	SimDB instance to use as a backing store for all checkpoints.
roots	TreeNodes at which checkpoints will be taken. These cannot be changed later. These do not necessarily need to be RootTreeNodes. Before the first checkpoint is taken, these nodes must be finalized (see sparta::TreeNode::isFinalized). At the point of construction, the nodes do not need to be finalized.
sched	Scheduler to read and restart on checkpoint restore (if not nullptr)

Member Function Documentation

◆ deleteCheckpoint()

void sparta::serialization::checkpoint::DatabaseCheckpointer::deleteCheckpoint ( chkpt_id_t )

finaloverridevirtual

Explicit checkpoint deletion is NOT supported by this checkpointer.

Exceptions

CheckpointError if called

Implements sparta::serialization::checkpoint::Checkpointer.

◆ dumpAnnotatedData()

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

overridevirtual

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

Implements sparta::serialization::checkpoint::Checkpointer.

◆ dumpData()

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

overridevirtual

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

Parameters

o	ostream to dump to

Implements sparta::serialization::checkpoint::Checkpointer.

◆ dumpList()

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

overridevirtual

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

Parameters

o	ostream to dump to

Implements sparta::serialization::checkpoint::Checkpointer.

◆ dumpRestoreChain()

void sparta::serialization::checkpoint::DatabaseCheckpointer::dumpRestoreChain	(	std::ostream &	o,
		chkpt_id_t	id )

Dumps the restore chain for this checkpoint.

See also: getRestoreChain()

Parameters

o	ostream to which chain data will be dumped
id	ID of starting checkpoint

◆ findCheckpoint()

std::shared_ptr< DatabaseCheckpoint > sparta::serialization::checkpoint::DatabaseCheckpointer::findCheckpoint	(	chkpt_id_t	id,
		bool	must_exist = false )

Finds a checkpoint by its ID.

Parameters

id	ID of checkpoint to find.
must_exist	Whether to enforce that the checkpoint be found.

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

Exceptions

CheckpointError if must_exist is true and id does not refer to a valid checkpoint.

◆ findLatestCheckpointAtOrBefore()

std::shared_ptr< DatabaseCheckpoint > sparta::serialization::checkpoint::DatabaseCheckpointer::findLatestCheckpointAtOrBefore	(	tick_t	tick,
		chkpt_id_t	from )

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.

◆ getCheckpointChain()

std::deque< chkpt_id_t > sparta::serialization::checkpoint::DatabaseCheckpointer::getCheckpointChain ( chkpt_id_t id )

overridevirtual

Debugging utility which gets a deque of checkpoints representing a chain starting at the checkpoint head and ending at the checkpoint specified by id.

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: The results never contain Checkpoint::UNIDENTIFIED_CHECKPOINT

Implements sparta::serialization::checkpoint::Checkpointer.

◆ getCheckpoints()

std::vector< chkpt_id_t > sparta::serialization::checkpoint::DatabaseCheckpointer::getCheckpoints ( )

overridevirtual

Gets all checkpoint IDs sorted by tick (or equivalently checkpoint ID).

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

Note: Walks all checkpoints in cache and on disk. This should not be called in the critical path.

Implements sparta::serialization::checkpoint::Checkpointer.

◆ getCheckpointsAt()

std::vector< chkpt_id_t > sparta::serialization::checkpoint::DatabaseCheckpointer::getCheckpointsAt ( tick_t t )

overridevirtual

Gets all checkpoints taken at tick t.

Parameters

t	Tick number at which checkpoints should found.

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

Note: Walks all checkpoints in cache and on disk. This should not be called in the critical path.

Implements sparta::serialization::checkpoint::Checkpointer.

◆ getContentMemoryUse()

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

overridevirtualnoexcept

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

Note: This only includes memory used by checkpoints currently in the cache, not checkpoints stored in the database.

Implements sparta::serialization::checkpoint::Checkpointer.

◆ getDistanceToPrevSnapshot()

uint32_t sparta::serialization::checkpoint::DatabaseCheckpointer::getDistanceToPrevSnapshot ( chkpt_id_t id )

noexcept

Determines how many checkpoints away the closest, earlier snapshot is.

Returns: distance to closest snapshot. If this node is a snapshot, returns 0; if immediate getPrev() is a snapshot, returns 1; and so on.

◆ getHistoryChain()

std::stack< chkpt_id_t > sparta::serialization::checkpoint::DatabaseCheckpointer::getHistoryChain ( chkpt_id_t id )

Returns a stack of checkpoints from this checkpoint as far back as possible until no previous link is found.

Note: Since this checkpointer enforces a linear chain of checkpoints with no gaps, this always reaches the head checkpoint.

◆ getNextIDs()

std::vector< chkpt_id_t > sparta::serialization::checkpoint::DatabaseCheckpointer::getNextIDs ( chkpt_id_t id )

overridevirtual

Returns IDs of the checkpoints immediately following the given checkpoint.

Note: Since this checkpointer does not support checkpoint gaps, this will always be a vector of size 0 or 1.

Implements sparta::serialization::checkpoint::Checkpointer.

◆ getNumCheckpoints()

uint32_t sparta::serialization::checkpoint::DatabaseCheckpointer::getNumCheckpoints ( ) const

overridevirtualnoexcept

Gets the current number of checkpoints with valid IDs.

Implements sparta::serialization::checkpoint::Checkpointer.

◆ getSnapshotThreshold()

uint32_t sparta::serialization::checkpoint::DatabaseCheckpointer::getSnapshotThreshold ( ) const

Returns the next-shapshot threshold.

This represents the distance between two checkpoints required for the checkpointer to automatically place a snapshot checkpoint instead of a delta. A threshold of 0 or 1 results in all checkpoints being snapshots. A value of 10 results in every 10th checkpoint being a snapshot.

Note: Unlike FastCheckpointer, this threshold is always enforced and snapshots cannot be created using createCheckpoint(force_snapshot=true).; This value is a performance/space tradeoff knob.

◆ getTotalMemoryUse()

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

overridevirtualnoexcept

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.; This only includes memory used by checkpoints currently in the cache, not checkpoints stored in the database.

Implements sparta::serialization::checkpoint::Checkpointer.

◆ hasCheckpoint()

bool sparta::serialization::checkpoint::DatabaseCheckpointer::hasCheckpoint ( chkpt_id_t id )

overridevirtualnoexcept

Tests whether this checkpoint manager has a checkpoint with the given id in the cache or in the database.

Returns: True if id refers to a checkpoint held by this checkpointer and false if not.

Implements sparta::serialization::checkpoint::Checkpointer.

◆ isCheckpointCached()

bool sparta::serialization::checkpoint::DatabaseCheckpointer::isCheckpointCached ( chkpt_id_t id ) const

noexcept

Check if the given checkpoint is currently cached in memory.

Note: Used for testing and debugging only.; Even though this might return true, if you wait a bit and call again with the same ID, it might return false since the checkpoint might have been evicted from the LRU cache.

◆ isSnapshot()

bool sparta::serialization::checkpoint::DatabaseCheckpointer::isSnapshot ( chkpt_id_t id )

noexcept

Check if the given checkpoint is a snapshot (not a delta).

Returns: Returns false if not a snapshot or the id is not a checkpoint.

◆ loadCheckpoint()

void sparta::serialization::checkpoint::DatabaseCheckpointer::loadCheckpoint ( chkpt_id_t id )

overridevirtual

Loads state from a specific checkpoint by ID.

Note: This implicitly deletes all future checkpoints since this checkpointer does not allow more than one branch.

Exceptions

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

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; Next checkpoint created will have ID = <id>+1 since gaps are not allowed; Sets scheduler current tick to the checkpoint's tick using Scheduler::restartAt

Implements sparta::serialization::checkpoint::Checkpointer.

◆ setMaxCachedWindows()

void sparta::serialization::checkpoint::DatabaseCheckpointer::setMaxCachedWindows ( uint32_t max_windows )

Sets the max number of cached windows (LRU).

Note: This must be called before any checkpoints are taken, and cannot be changed later.

◆ setSnapshotThreshold()

void sparta::serialization::checkpoint::DatabaseCheckpointer::setSnapshotThreshold ( uint32_t thresh )

Sets the snapshot threshold.

Note: This must be called before any checkpoints are taken, and cannot be changed later.

◆ stringize()

std::string sparta::serialization::checkpoint::DatabaseCheckpointer::stringize ( ) const

overridevirtual

Returns a string describing this object.

Reimplemented from sparta::serialization::checkpoint::Checkpointer.

◆ traceValue()

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

overridevirtual

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 the given value in the selected checkpoint.

Parameters

o	ostream where 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.

Note: NOT CURRENTLY IMPLEMENTED

Exceptions

CheckpointError

Implements sparta::serialization::checkpoint::Checkpointer.

Member Data Documentation

◆ NAME

auto sparta::serialization::checkpoint::DatabaseCheckpointer::NAME = "db-checkpointer"

staticconstexpr

Definition at line 25 of file DatabaseCheckpointer.hpp.

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

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

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ checkpoint_ptr

◆ checkpoint_ptrs

◆ checkpoint_type

◆ window_id_t

Constructor & Destructor Documentation

◆ DatabaseCheckpointer()

Member Function Documentation

◆ deleteCheckpoint()

◆ dumpAnnotatedData()

◆ dumpData()

◆ dumpList()

◆ dumpRestoreChain()

◆ findCheckpoint()

◆ findLatestCheckpointAtOrBefore()

◆ getCheckpointChain()

◆ getCheckpoints()

◆ getCheckpointsAt()

◆ getContentMemoryUse()

◆ getDistanceToPrevSnapshot()

◆ getHistoryChain()

◆ getNextIDs()

◆ getNumCheckpoints()

◆ getSnapshotThreshold()

◆ getTotalMemoryUse()

◆ hasCheckpoint()

◆ isCheckpointCached()

◆ isSnapshot()

◆ loadCheckpoint()

◆ setMaxCachedWindows()

◆ setSnapshotThreshold()

◆ stringize()

◆ traceValue()

Member Data Documentation

◆ NAME