Preservation/Restoration Types and Methods

Classes
class	cd::RegenObject
	Interface for specifying regeneration functions for preserve/restore. More...

Enumerations
enum	cd::PreserveMechanismT { cd::kCopy =0b001, cd::kRef =0b010, cd::kRegen =0b100 }
	Type for specifying preservation methods. More...

Functions
CDErrT	cd::CDHandle::Preserve (void *data_ptr, uint64_t len, uint_t preserve_mask=kCopy, const char *my_name=0, const char *ref_name=0, uint_64t ref_offset=0, const RegenObject *regen_object=0, PreserveUseT data_usage=kUnsure)
	Preserve data to be restored when recovering (typically reexecuting the CD from right after its Begin() call. More...
CDErrT	cd::CDHandle::Preserve (CDEvent &cd_event, void *data_ptr, uint64_t len, uint_t preserve_mask=kCopy, const char *my_name=0, const char *ref_name=0, uint_64t ref_offset=0, const RegenObject *regen_object=0, PreserveUseT data_usage=kUnsure)
	Non-blocking preserve data to be restored when recovering (typically reexecuting the CD from right after its Begin() call. More...

Detailed Description

The Preservation/Restoration Types and Methods module contains all preservation/restoration related types and methods.

Enumeration Type Documentation

enum cd::PreserveMechanismT

Type for specifying preservation methods.

See http://lph.ece.utexas.edu/public/CDs for a detailed description.

The intent is for this to be used as a mask for specifying multiple legal preservation methods so that the autotuner can choose the appropriate one.

See also

RegenObject, CDHandle::Preserve()

Enumerator
kCopy	Prevervation via copy copies the data to be preserved into another storage/mem location
kRef	Preservation via reference indicates that restoration can occur by restoring data that is already preserved in another CD. Restriction: in the current version of the API only the parent can be used as a reference.
kRegen	Preservation via regenaration is done by calling a user-provided function to regenerate the data during restoration instead of copying it from preserved storage.

Function Documentation

CDErrT cd::CDHandle::Preserve	(	void *	data_ptr,
		uint64_t	len,
		uint_t	preserve_mask = kCopy,
		const char *	my_name = 0,
		const char *	ref_name = 0,
		uint_64t	ref_offset = 0,
		const RegenObject *	regen_object = 0,
		PreserveUseT	data_usage = kUnsure
	)

Preserve data to be restored when recovering (typically reexecuting the CD from right after its Begin() call.

Preserves application data so that it can be restored for correct CD recovery (typically reexecution).

Preserve() preserves data on the first execution of the CD (kExec) but acts to restore data when a CD is reexecuted (kReexec). Success is defined as successfully preserving or restoring len bytes of contiguous data starting at address data_ptr.

In many cases there is more than one way to preserve data and the best way to do depends on machine-specific characteristics. It is therefore possible to call Preserve() with a set of possible correct and legal preservation methods and have an autotuner select the best one. This is done by setting the appropriate bits in the preserve_mask parameter based on the constants defined by PreserveMethodT.

Returns

kOK on success and kError otherwise.

See also

Complete()

Parameters

[in]	data_ptr	pointer to data to be preserved; __currently must be in same address space as calling task, but will extend to PGAS fat pointers later
[in]	len	Length of preserved data (Bytes)
[in]	preserve_mask	Allowed types of preservation (e.g., kCopy | kRegen), default only via copy
[in]	my_name	Optional C-string representing the name of this preserved data for later preserve-via-reference
[in]	ref_name	Optional C-string representing a user-specified name that was set by a previous preserve call at the parent.; Do we also need an offset into parent preservation?
[in]	ref_offset	explicit offset
	regen_object	within the named region at the other CD (for restoration via reference) [in] optional user-specified function for regenerating values instead of restoring by copying
[in]	data_usage	This flag is used to optimize consecutive Complete/Begin calls where there is significant overlap in preserved state that is unmodified (see Complete()).

CDErrT cd::CDHandle::Preserve	(	CDEvent &	cd_event,
		void *	data_ptr,
		uint64_t	len,
		uint_t	preserve_mask = kCopy,
		const char *	my_name = 0,
		const char *	ref_name = 0,
		uint_64t	ref_offset = 0,
		const RegenObject *	regen_object = 0,
		PreserveUseT	data_usage = kUnsure
	)

Non-blocking preserve data to be restored when recovering (typically reexecuting the CD from right after its Begin() call.

Preserves application data so that it can be restored for correct CD recovery (typically reexecution).

Preserve() preserves data on the first execution of the CD (kExec) but acts to restore data when a CD is reexecuted (kReexec). Success is defined as successfully preserving or restoring len bytes of contiguous data starting at address data_ptr.

In many cases there is more than one way to preserve data and the best way to do depends on machine-specific characteristics. It is therefore possible to call Preserve() with a set of possible correct and legal preservation methods and have an autotuner select the best one. This is done by setting the appropriate bits in the preserve_mask parameter based on the constants defined by PreserveMethodT.

The CDEvent object will be initialized to wait on this particular call if it is empty. If the CDEvent already contains an event, then this new event is chained to it – in this way, the user can use a single CDEvent::Wait() call to wait on a sequence of non-blocking calls.

Returns

kOK on success and kError otherwise.

See also

Complete()

Parameters

[in,out]	cd_event	enqueue this call onto the cd_event
[in]	data_ptr	pointer to data to be preserved; __currently must be in same address space as calling task, but will extend to PGAS fat pointers later
[in]	len	Length of preserved data (Bytes)
[in]	preserve_mask	Allowed types of preservation (e.g., kCopy | kRegen), default only via copy
[in]	my_name	Optional C-string representing the name of this preserved data for later preserve-via-reference
[in]	ref_name	Optional C-string representing a user-specified name that was set by a previous preserve call at the parent.; Do we also need an offset into parent preservation?
[in]	ref_offset	explicit offset
	regen_object	within the named region at the other CD [in] optional user-specified function for regenerating values instead of restoring by copying
[in]	data_usage	This flag is used to optimize consecutive Complete/Begin calls where there is significant overlap in preserved state that is unmodified (see Complete()).