hpx/checkpoint/checkpoint.hpp#

See Public API for a list of names and headers 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

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

Returns

Operator<< returns the ostream object.

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

Returns

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.

Returns

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.

Returns

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.

Returns

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.

Returns

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.

Returns

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.

Returns

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.

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.

Returns

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

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.

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.

Returns

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

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.

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.

Returns

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

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.

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.

Returns

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

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.

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.

Returns

Restore_checkpoint returns void.

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<char>::const_iterator#

Public Functions

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

Private Functions

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

Private Members

std::vector<char> data_#

Friends

friend class hpx::serialization::access
friend 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.

Returns

Operator<< returns the ostream object.

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

Returns

Operator>> returns the ostream object.

template<typename T, typename ...Ts>
friend 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.

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.

Returns

Restore_checkpoint returns void.

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