src/checkpoint/checkpoint_api.h file

Namespaces

namespace checkpoint

Classes

struct checkpoint::SerializedInfo
Return of serialize that contains the buffer and size serialized.

Typedefs

using BufferCallbackType = std::function<char*(std::size_t size)>
Callback for user to allocate bytes during serialization.
using SerializedReturnType = std::unique_ptr<SerializedInfo>
Convenience typedef for std::unique_ptr<SerializedInfo>

Functions

template<typename T, typename... UserTraits>
auto serialize(T& target, BufferCallbackType fn = nullptr) -> SerializedReturnType
Serialize T into a byte buffer.
template<typename T, typename... UserTraits>
auto deserialize(char* buf, char* object_buf) -> T*
De-serialize and reify T from a byte buffer and corresponding size.
template<typename T, typename... UserTraits>
auto deserialize(char* buf) -> std::unique_ptr<T>
De-serialize and reify T from a byte buffer and corresponding size.
template<typename T, typename... UserTraits>
void deserializeInPlace(char* buf, T* t)
De-serialize and reify T from a byte buffer and corresponding size in-place on the user-provided t.
template<typename T, typename... UserTraits>
auto deserialize(SerializedReturnType&& in) -> std::unique_ptr<T>
Convenience function for de-serializing and reify T directly from in the return value from serialize.
template<typename T, typename... UserTraits>
auto getSize(T& target) -> std::size_t
Get the number of bytes that target requires for serialization.
template<typename T, typename... UserTraits>
auto getMemoryFootprint(T& target, std::size_t size_offset = 0) -> std::size_t
Get memory footprint of target.
template<typename T, typename... UserTraits>
void serializeToFile(T& target, std::string const& file)
Serialize T to file with filename file.
template<typename T, typename... UserTraits>
auto deserializeFromFile(std::string const& file) -> std::unique_ptr<T>
De-serialize and reify T from a file.
template<typename T, typename... UserTraits>
void deserializeInPlaceFromFile(std::string const& file, T* buf)
De-serialize and reify T from a file in place on an existing pointer to T.
template<typename T, typename... UserTraits, typename StreamT>
void serializeToStream(T& target, StreamT& stream)
Serialize T to a stream.
template<typename T, typename... UserTraits, typename StreamT>
auto deserializeFromStream(StreamT& stream) -> std::unique_ptr<T>
De-serialize and reify T from a stream.
template<typename T, typename... UserTraits, typename StreamT>
void deserializeInPlaceFromStream(StreamT& stream, T* buf)
De-serialize and reify T from a stream in place on an existing pointer to T.

Function documentation

template<typename T, typename... UserTraits>
SerializedReturnType serialize(T& target, BufferCallbackType fn = nullptr)

Serialize T into a byte buffer.

Parameters
target in the T to serialize
fn in (optional) callback to supply buffer for to allow user allocation of the produced byte buffer. The callback will be passed the number of bytes required and return a char* to a buffer of at least that many bytes.
Returns a std::unique_ptr to a SerializedInfo containing the buffer with serialized data and the size of the buffer

Serializes an object recursively by invoking the serialize functions/methods recursively.

template<typename T, typename... UserTraits>
T* deserialize(char* buf, char* object_buf)

De-serialize and reify T from a byte buffer and corresponding size.

Parameters
buf in the buffer containing the bytes to reify T
object_buf in (optional) buffer containing bytes allocated with sufficient size for T. If this buffer != null, the caller is responsible for deallocating the buffer. If it is not passed, the system will allocate a buffer that must be de-allocated with delete
Returns a pointer to the newly reified T based on bytes in buf

De-serializes an object recursively by first invoking the reconstruction strategy and then serialize functions/methods recursively to rebuild the state of the object as serialized. During reconstruction, based on trait detection, T will either be default constructed on user_buf (or a system allocated buffer) or reconstructed based on a user-defined reconstruct method. If user_buf is not passed, the returned object point must be deallocated with delete

template<typename T, typename... UserTraits>
std::unique_ptr<T> deserialize(char* buf)

De-serialize and reify T from a byte buffer and corresponding size.

Parameters
buf in the buffer containing the bytes to reify T
Returns a unique pointer to the newly reified T based on bytes in buf

De-serializes an object recursively by first invoking the reconstruction strategy and then serialize functions/methods recursively to rebuild the state of the object as serialized. During reconstruction, based on trait detection, T will either be default constructed or reconstructed based on a user-defined reconstruct method.

template<typename T, typename... UserTraits>
void deserializeInPlace(char* buf, T* t)

De-serialize and reify T from a byte buffer and corresponding size in-place on the user-provided t.

Parameters
buf in the buffer containing the bytes to reify T
t in a valid pointer to a T that has been user-allocated and constructed

Note: the other form of deserialize will either reconstruct to default construct T in-place. This overload will not allocate or construct T

template<typename T, typename... UserTraits>
std::unique_ptr<T> deserialize(SerializedReturnType&& in)

Convenience function for de-serializing and reify T directly from in the return value from serialize.

Parameters
in in the buffer and size combo returned from serialize
Returns a unique pointer to T that must be deallocated

template<typename T, typename... UserTraits>
std::size_t getSize(T& target)

Get the number of bytes that target requires for serialization.

Parameters
target in reference to T to size
Returns number of bytes for the target

template<typename T, typename... UserTraits>
std::size_t getMemoryFootprint(T& target, std::size_t size_offset = 0)

Get memory footprint of target.

Parameters
target in reference to T to measure footprint
size_offset in add an arbitrary size_offset to the footprint
Returns memory footprint of the target

Calculates memory footprint for both serializable and non-serializable objects. Uses serialize functions/methods recursively when they are available. For non-serializable objects, simplified footprinting is performed by just applying 'sizeof' operator (note: this means that complex objects will not be traversed).

template<typename T, typename... UserTraits>
void serializeToFile(T& target, std::string const& file)

Serialize T to file with filename file.

Parameters
target in the T to serialize
file in name of the file to create

Byte-serializes T to file, truncating file if it already exists. If any error occurs while opening/closing/mapping the file, std::runtime_error will be thrown with an appropriate error message containing the corresponding errno.

template<typename T, typename... UserTraits>
std::unique_ptr<T> deserializeFromFile(std::string const& file)

De-serialize and reify T from a file.

Parameters
file in the filename to read with bytes for T
Returns unique pointer to the new object T

De-serializes an object recursively by first invoking the reconstruction strategy and then serialize functions/methods recursively to rebuild the state of the object as serialized. During reconstruction, based on trait detection, T will either be default constructed or reconstructed based on a user-defined reconstruct method.

template<typename T, typename... UserTraits>
void deserializeInPlaceFromFile(std::string const& file, T* buf)

De-serialize and reify T from a file in place on an existing pointer to T.

Parameters
file in the filename to read with bytes for T
buf

De-serializes an object recursively by invoking the serialize functions/methods recursively to rebuild the state of the object as serialized.

template<typename T, typename... UserTraits, typename StreamT>
void serializeToStream(T& target, StreamT& stream)

Serialize T to a stream.

Parameters
target in the T to serialize
stream in to serialize into, with tellp and write functions.

Byte-serializes T to stream. Handling of any errors during writing to the stream will be handled by the stream itself, e.g. any exceptions or status bits to check will depend on stream type.

template<typename T, typename... UserTraits, typename StreamT>
std::unique_ptr<T> deserializeFromStream(StreamT& stream)

De-serialize and reify T from a stream.

Parameters
stream in the stream to read with bytes for T, with tellg and read functions
Returns unique pointer to the new object T

De-serializes an object recursively by first invoking the reconstruction strategy and then serialize functions/methods recursively to rebuild the state of the object as serialized. During reconstruction, based on trait detection, T will either be default constructed or reconstructed based on a user-defined reconstruct method.

template<typename T, typename... UserTraits, typename StreamT>
void deserializeInPlaceFromStream(StreamT& stream, T* buf)

De-serialize and reify T from a stream in place on an existing pointer to T.

Parameters
stream in the stream to read with bytes for T, with tellg and read functions
buf

De-serializes an object recursively by invoking the serialize functions/methods recursively to rebuild the state of the object as serialized.