checkpoint

The contents of this module can be included with the header hpx/modules/checkpoint.hpp. These headers may be used by user-code but are not guaranteed stable (neither header location nor contents). You are using these at your own risk. If you wish to use non-public functionality from a module we strongly suggest only including the module header hpx/modules/checkpoint.hpp, not the particular header in which the functionality you would like to use is defined. See Public API for a list of names that are part of the public HPX API.

This header defines the save_checkpoint and restore_checkpoint functions. These functions are designed to help HPX application developer’s checkpoint their applications. Save_checkpoint serializes one or more objects and saves them as a byte stream. Restore_checkpoint converts the byte stream back into instances of the objects.

namespace hpx
namespace util

Functions

std::ostream &operator<<(std::ostream &ost, checkpoint const &ckp)

Operator<< Overload

This overload is the main way to write data from a checkpoint to an object such as a file. Inside the function, the size of the checkpoint will be written to the stream before the checkpoint’s data. The operator>> overload uses this to read the correct number of bytes. Be mindful of this additional write and read when you use different facilities to write out or read in data to a checkpoint!

Parameters

  • ost: Output stream to write to.

  • ckp: Checkpoint to copy from.

Return

Operator<< returns the ostream object.

std::istream &operator>>(std::istream &ist, checkpoint &ckp)

Operator>> Overload

This overload is the main way to read in data from an object such as a file to a checkpoint. It is important to note that inside the function, the first variable to be read is the size of the checkpoint. This size variable is written to the stream before the checkpoint’s data in the operator<< overload. Be mindful of this additional read and write when you use different facilities to read in or write out data from a checkpoint!

Parameters

  • ist: Input stream to write from.

  • ckp: Checkpoint to write to.

Return

Operator>> returns the ostream object.

template<typename T, typename ...Ts, typename U = typename std::enable_if<!hpx::traits::is_launch_policy<T>::value && !std::is_same<typename std::decay<T>::type, checkpoint>::value>::type>
hpx::future<checkpoint> save_checkpoint(T &&t, Ts&&... ts)

Save_checkpoint

Save_checkpoint takes any number of objects which a user may wish to store and returns a future to a checkpoint object. This function can also store a component either by passing a shared_ptr to the component or by passing a component’s client instance to save_checkpoint. Additionally the function can take a policy as a first object which changes its behavior depending on the policy passed to it. Most notably, if a sync policy is used save_checkpoint will simply return a checkpoint object.

Template Parameters

  • T: Containers passed to save_checkpoint to be serialized and placed into a checkpoint object.

  • Ts: More containers passed to save_checkpoint to be serialized and placed into a checkpoint object.

  • U: This parameter is used to make sure that T is not a launch policy or a checkpoint. This forces the compiler to choose the correct overload.

Parameters

  • t: A container to restore.

  • ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.

Return

Save_checkpoint returns a future to a checkpoint with one exception: if you pass hpx::launch::sync as the first argument. In this case save_checkpoint will simply return a checkpoint.

template<typename T, typename ...Ts>
hpx::future<checkpoint> save_checkpoint(checkpoint &&c, T &&t, Ts&&... ts)

Save_checkpoint - Take a pre-initialized checkpoint

Save_checkpoint takes any number of objects which a user may wish to store and returns a future to a checkpoint object. This function can also store a component either by passing a shared_ptr to the component or by passing a component’s client instance to save_checkpoint. Additionally the function can take a policy as a first object which changes its behavior depending on the policy passed to it. Most notably, if a sync policy is used save_checkpoint will simply return a checkpoint object.

Template Parameters

  • T: Containers passed to save_checkpoint to be serialized and placed into a checkpoint object.

  • Ts: More containers passed to save_checkpoint to be serialized and placed into a checkpoint object.

Parameters

  • c: Takes a pre-initialized checkpoint to copy data into.

  • t: A container to restore.

  • ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.

Return

Save_checkpoint returns a future to a checkpoint with one exception: if you pass hpx::launch::sync as the first argument. In this case save_checkpoint will simply return a checkpoint.

template<typename T, typename ...Ts, typename U = typename std::enable_if<!std::is_same<typename std::decay<T>::type, checkpoint>::value>::type>
hpx::future<checkpoint> save_checkpoint(hpx::launch p, T &&t, Ts&&... ts)

Save_checkpoint - Policy overload

Save_checkpoint takes any number of objects which a user may wish to store and returns a future to a checkpoint object. This function can also store a component either by passing a shared_ptr to the component or by passing a component’s client instance to save_checkpoint. Additionally the function can take a policy as a first object which changes its behavior depending on the policy passed to it. Most notably, if a sync policy is used save_checkpoint will simply return a checkpoint object.

Template Parameters

  • T: Containers passed to save_checkpoint to be serialized and placed into a checkpoint object.

  • Ts: More containers passed to save_checkpoint to be serialized and placed into a checkpoint object.

Parameters

  • p: Takes an HPX launch policy. Allows the user to change the way the function is launched i.e. async, sync, etc.

  • t: A container to restore.

  • ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.

Return

Save_checkpoint returns a future to a checkpoint with one exception: if you pass hpx::launch::sync as the first argument. In this case save_checkpoint will simply return a checkpoint.

template<typename T, typename ...Ts>
hpx::future<checkpoint> save_checkpoint(hpx::launch p, checkpoint &&c, T &&t, Ts&&... ts)

Save_checkpoint - Policy overload & pre-initialized checkpoint

Save_checkpoint takes any number of objects which a user may wish to store and returns a future to a checkpoint object. This function can also store a component either by passing a shared_ptr to the component or by passing a component’s client instance to save_checkpoint. Additionally the function can take a policy as a first object which changes its behavior depending on the policy passed to it. Most notably, if a sync policy is used save_checkpoint will simply return a checkpoint object.

Template Parameters

  • T: Containers passed to save_checkpoint to be serialized and placed into a checkpoint object.

  • Ts: More containers passed to save_checkpoint to be serialized and placed into a checkpoint object.

Parameters

  • p: Takes an HPX launch policy. Allows the user to change the way the function is launched i.e. async, sync, etc.

  • c: Takes a pre-initialized checkpoint to copy data into.

  • t: A container to restore.

  • ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.

Return

Save_checkpoint returns a future to a checkpoint with one exception: if you pass hpx::launch::sync as the first argument. In this case save_checkpoint will simply return a checkpoint.

template<typename T, typename ...Ts, typename U = typename std::enable_if<!std::is_same<typename std::decay<T>::type, checkpoint>::value>::type>
checkpoint save_checkpoint(hpx::launch::sync_policy sync_p, T &&t, Ts&&... ts)

Save_checkpoint - Sync_policy overload

Save_checkpoint takes any number of objects which a user may wish to store and returns a future to a checkpoint object. This function can also store a component either by passing a shared_ptr to the component or by passing a component’s client instance to save_checkpoint. Additionally the function can take a policy as a first object which changes its behavior depending on the policy passed to it. Most notably, if a sync policy is used save_checkpoint will simply return a checkpoint object.

Template Parameters

  • T: Containers passed to save_checkpoint to be serialized and placed into a checkpoint object.

  • Ts: More containers passed to save_checkpoint to be serialized and placed into a checkpoint object.

  • U: This parameter is used to make sure that T is not a checkpoint. This forces the compiler to choose the correct overload.

Parameters

  • sync_p: hpx::launch::sync_policy

  • t: A container to restore.

  • ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.

Return

Save_checkpoint which is passed hpx::launch::sync_policy will return a checkpoint which contains the serialized values checkpoint.

template<typename T, typename ...Ts>
checkpoint save_checkpoint(hpx::launch::sync_policy sync_p, checkpoint &&c, T &&t, Ts&&... ts)

Save_checkpoint - Sync_policy overload & pre-init. checkpoint

Save_checkpoint takes any number of objects which a user may wish to store and returns a future to a checkpoint object. This function can also store a component either by passing a shared_ptr to the component or by passing a component’s client instance to save_checkpoint. Additionally the function can take a policy as a first object which changes its behavior depending on the policy passed to it. Most notably, if a sync policy is used save_checkpoint will simply return a checkpoint object.

Template Parameters

  • T: Containers passed to save_checkpoint to be serialized and placed into a checkpoint object.

  • Ts: More containers passed to save_checkpoint to be serialized and placed into a checkpoint object.

Parameters

  • sync_p: hpx::launch::sync_policy

  • c: Takes a pre-initialized checkpoint to copy data into.

  • t: A container to restore.

  • ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.

Return

Save_checkpoint which is passed hpx::launch::sync_policy will return a checkpoint which contains the serialized values checkpoint.

template<typename T, typename ...Ts, typename U = typename std::enable_if<!hpx::traits::is_launch_policy<T>::value && !std::is_same<typename std::decay<T>::type, checkpoint>::value>::type>
hpx::future<checkpoint> prepare_checkpoint(T const &t, Ts const&... ts)

prepare_checkpoint

prepare_checkpoint takes the containers which have to be filled from the byte stream by a subsequent restore_checkpoint invocation. prepare_checkpoint will calculate the necessary buffer size and will return an appropriately sized checkpoint object.

Return

prepare_checkpoint returns a properly resized checkpoint object that can be used for a subsequent restore_checkpoint operation.

Template Parameters

  • T: A container to restore.

  • Ts: Other containers to restore. Containers must be in the same order that they were inserted into the checkpoint.

Parameters

  • t: A container to restore.

  • ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.

template<typename T, typename ...Ts>
hpx::future<checkpoint> prepare_checkpoint(checkpoint &&c, T const &t, Ts const&... ts)

prepare_checkpoint

prepare_checkpoint takes the containers which have to be filled from the byte stream by a subsequent restore_checkpoint invocation. prepare_checkpoint will calculate the necessary buffer size and will return an appropriately sized checkpoint object.

Return

prepare_checkpoint returns a properly resized checkpoint object that can be used for a subsequent restore_checkpoint operation.

Template Parameters

  • T: A container to restore.

  • Ts: Other containers to restore. Containers must be in the same order that they were inserted into the checkpoint.

Parameters

  • c: Takes a pre-initialized checkpoint to prepare

  • t: A container to restore.

  • ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.

template<typename T, typename ...Ts, typename U = typename std::enable_if<!std::is_same<T, checkpoint>::value>::type>
hpx::future<checkpoint> prepare_checkpoint(hpx::launch p, T const &t, Ts const&... ts)

prepare_checkpoint

prepare_checkpoint takes the containers which have to be filled from the byte stream by a subsequent restore_checkpoint invocation. prepare_checkpoint will calculate the necessary buffer size and will return an appropriately sized checkpoint object.

Return

prepare_checkpoint returns a properly resized checkpoint object that can be used for a subsequent restore_checkpoint operation.

Template Parameters

  • T: A container to restore.

  • Ts: Other containers to restore. Containers must be in the same order that they were inserted into the checkpoint.

Parameters

  • p: Takes an HPX launch policy. Allows the user to change the way the function is launched i.e. async, sync, etc.

  • t: A container to restore.

  • ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.

template<typename T, typename ...Ts>
hpx::future<checkpoint> prepare_checkpoint(hpx::launch p, checkpoint &&c, T const &t, Ts const&... ts)

prepare_checkpoint

prepare_checkpoint takes the containers which have to be filled from the byte stream by a subsequent restore_checkpoint invocation. prepare_checkpoint will calculate the necessary buffer size and will return an appropriately sized checkpoint object.

Return

prepare_checkpoint returns a properly resized checkpoint object that can be used for a subsequent restore_checkpoint operation.

Template Parameters

  • T: A container to restore.

  • Ts: Other containers to restore. Containers must be in the same order that they were inserted into the checkpoint.

Parameters

  • p: Takes an HPX launch policy. Allows the user to change the way the function is launched i.e. async, sync, etc.

  • c: Takes a pre-initialized checkpoint to prepare

  • t: A container to restore.

  • ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.

template<typename T, typename ...Ts>
void restore_checkpoint(checkpoint const &c, T &t, Ts&... ts)

Restore_checkpoint

Restore_checkpoint takes a checkpoint object as a first argument and the containers which will be filled from the byte stream (in the same order as they were placed in save_checkpoint). Restore_checkpoint can resurrect a stored component in two ways: by passing in a instance of a component’s shared_ptr or by passing in an instance of the component’s client.

Return

Restore_checkpoint returns void.

Template Parameters

  • T: A container to restore.

  • Ts: Other containers to restore. Containers must be in the same order that they were inserted into the checkpoint.

Parameters

  • c: The checkpoint to restore.

  • t: A container to restore.

  • ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.

class checkpoint
#include <checkpoint.hpp>

Checkpoint Object

Checkpoint is the container object which is produced by save_checkpoint and is consumed by a restore_checkpoint. A checkpoint may be moved into the save_checkpoint object to write the byte stream to the pre-created checkpoint object.

Checkpoints are able to store all containers which are able to be serialized including components.

Public Types

using const_iterator = std::vector::const_iterator

Public Functions

checkpoint()
~checkpoint()
checkpoint(checkpoint const &c)
checkpoint(checkpoint &&c)
checkpoint(std::vector<char> const &vec)
checkpoint(std::vector<char> &&vec)
checkpoint &operator=(checkpoint const &c)
checkpoint &operator=(checkpoint &&c)
const_iterator begin() const
const_iterator end() const
std::size_t size() const
char *data()
char const *data() const

Private Functions

template<typename Archive>
void serialize(Archive &arch, const unsigned int)

Private Members

std::vector<char> data_

Friends

friend hpx::util::hpx::serialization::access
std::ostream &operator<<(std::ostream &ost, checkpoint const &ckp)

Operator<< Overload

This overload is the main way to write data from a checkpoint to an object such as a file. Inside the function, the size of the checkpoint will be written to the stream before the checkpoint’s data. The operator>> overload uses this to read the correct number of bytes. Be mindful of this additional write and read when you use different facilities to write out or read in data to a checkpoint!

Parameters

  • ost: Output stream to write to.

  • ckp: Checkpoint to copy from.

Return

Operator<< returns the ostream object.

std::istream &operator>>(std::istream &ist, checkpoint &ckp)

Operator>> Overload

This overload is the main way to read in data from an object such as a file to a checkpoint. It is important to note that inside the function, the first variable to be read is the size of the checkpoint. This size variable is written to the stream before the checkpoint’s data in the operator<< overload. Be mindful of this additional read and write when you use different facilities to read in or write out data from a checkpoint!

Parameters

  • ist: Input stream to write from.

  • ckp: Checkpoint to write to.

Return

Operator>> returns the ostream object.

template<typename T, typename ...Ts>
void restore_checkpoint(checkpoint const &c, T &t, Ts&... ts)

Restore_checkpoint

Restore_checkpoint takes a checkpoint object as a first argument and the containers which will be filled from the byte stream (in the same order as they were placed in save_checkpoint). Restore_checkpoint can resurrect a stored component in two ways: by passing in a instance of a component’s shared_ptr or by passing in an instance of the component’s client.

Return

Restore_checkpoint returns void.

Template Parameters

  • T: A container to restore.

  • Ts: Other containers to restore. Containers must be in the same order that they were inserted into the checkpoint.

Parameters

  • c: The checkpoint to restore.

  • t: A container to restore.

  • ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.

bool operator==(checkpoint const &lhs, checkpoint const &rhs)
bool operator!=(checkpoint const &lhs, checkpoint const &rhs)