persistence/persistent_shortcuts.hpp
Data Persistence Shortcut Functions

Introduction

There is a set of template functions defined in the persistence_shortcuts.hpp header that encapsulate the most common uses of persistence. The functions assume that you have built up your family of dump and restore functions so that an entire data structure can be dumped by simply calling a function called dump_class at the top level. Similarly the data structure can be restored by simply calling restore_class at the top level. In both cases the functions must take only two parameters - the context and the data.

The shortcut functions also support the use of an installer function as described in the section on Polymorphic types. This reduces the process of dumping to common targets to a one-line function call.

File-Based Persistence

Probably the most useful shortcut functions are the pair dump_to_file/restore_from_file:

template<typename T, class D>
void stlplus::dump_to_file(const T& source, const std::string& filename, D dump_fn, dump_context::installer installer)
  throw(stlplus::persistent_dump_failed);

template<typename T, class R>
void stlplus::restore_from_file(const std::string& filename, T& result, R restore_fn, restore_context::installer installer)
  throw(stlplus::persistent_restore_failed);

To dump a data structure to a file, simply call dump_to_file with the first argument being the source data structure to be dumped, the second argument being the name of the file to dump to, the third argument being the dump function with two parameters and the last argument being an installer function for registering any polymorphic types. The last argument can be null if there are no polymorphic types to register.

Similarly, to restore the same data structure, simply call restore_from_file with the name of the file as the first argument (conceptually, the first argument is the source and the second the destination), the data structure to be restored as the second and the restore function the third. Again the fourth argument is an installer function for restoring polymorphic types and may be null.

As an example of how to use these functions, see the examples page.

String-Based Persistence

Sometimes you want to create an in-memory dump of a data structure rather than dumping to a file. For example, this would be a starting point for a routine for transferring a data structure across the internet using data persistence as the mechanism. This is done by dumping to and restoring from a string:

template<typename T, class D>
void stlplus::dump_to_string(const T& source, std::string& result, D dump_fn, dump_context::installer installer)
  throw(stlplus::persistent_dump_failed);

template<typename T, class R>
void stlplus::restore_from_string(const std::string& source, T& result, R restore_fn, restore_context::installer installer)
  throw(stlplus::persistent_restore_failed);

This is very similar to the previous section's file-based persistence, except that the target of the dump is the string itself. Note that the std::string class is capable of storing binary data since it does not rely on null termination to work properly. A C char* could not be used in this way (but its obsolete anyway).

To dump a data structure to a string, simply call dump_to_string with the first argument being the source data structure to be dumped, the second argument being the string to dump to, the third being the dump funtion and the final argument being an installer function for registering any polymorphic types. The last argument can be null if there are no polymorphic types to register.

Similarly, to restore the same data structure, simply call restore_from_string with the string containing the dumped data as the first argument, the data structure to be restored as the second and the restore function the third. Again the fourth argument is an installer function for restoring polymorphic types and may be null.

IOStream-Based Persistence

The above two short-cuts are in fact specialisations of the most general short-cut functions that dump to and restore from any IOStream device. This more general form is useful if you want to use other I/O devices than the most common ones of files and in-memory strings.

The functions are:

template<typename T, class D>
void stlplus::dump_to_device(const T& source, std::ostream& result, D dump_fn, dump_context::installer installer)
  throw(stlplus::persistent_dump_failed);

template<typename T, class R>
void stlplus::restore_from_device(std::istream& source, T& result, R restore_fn, restore_context::installer installer)
  throw(stlplus::persistent_restore_failed);

To dump a data structure to an output device, simply call dump_to_device with the first argument being the source data structure to be dumped, the second argument being the IOStream device to dump to and the final argument being an installer function for registering any polymorphic types. The last argument can be null if there are no polymorphic types to register.

Similarly, to restore the same data structure, simply call restore_from_device with the IOStream device sourcing the dumped data as the first argument and the data structure to be restored as the second. Again the third argument is an installer function for restoring polymorphic types and may be null.