Containment Domains C++ API  0.1
Containment Domains C++ API v0.1
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Groups Pages
Classes | Enumerations | Functions
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

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_ptrpointer to data to be preserved; __currently must be in same address space as calling task, but will extend to PGAS fat pointers later
[in]lenLength of preserved data (Bytes)
[in]preserve_maskAllowed types of preservation (e.g., kCopy | kRegen), default only via copy
[in]my_nameOptional C-string representing the name of this preserved data for later preserve-via-reference
[in]ref_nameOptional 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_offsetexplicit offset
regen_objectwithin 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_usageThis 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_eventenqueue this call onto the cd_event
[in]data_ptrpointer to data to be preserved; __currently must be in same address space as calling task, but will extend to PGAS fat pointers later
[in]lenLength of preserved data (Bytes)
[in]preserve_maskAllowed types of preservation (e.g., kCopy | kRegen), default only via copy
[in]my_nameOptional C-string representing the name of this preserved data for later preserve-via-reference
[in]ref_nameOptional 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_offsetexplicit offset
regen_objectwithin the named region at the other CD [in] optional user-specified function for regenerating values instead of restoring by copying
[in]data_usageThis flag is used to optimize consecutive Complete/Begin calls where there is significant overlap in preserved state that is unmodified (see Complete()).