path: root/src/core/serializer.h

/*  This file is part of the OpenLB library
 *
 *  Copyright (C) 2016 Mathias J. Krause, Benjamin Förster
 *  E-mail contact: info@openlb.net
 *  The most recent release of OpenLB can be downloaded at
 *  <http://www.openlb.net/>
 *
 *  This program is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU General Public License
 *  as published by the Free Software Foundation; either version 2
 *  of the License, or (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public
 *  License along with this program; if not, write to the Free
 *  Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 *  Boston, MA  02110-1301, USA.
*/


#ifndef SERIALIZER_H
#define SERIALIZER_H

#include <iostream>
#include <vector>
#include <map>
#include <utility>

namespace olb {

class Serializable;

/// Class for writing, reading, sending and receiving `Serializable` objects.
/**
 * __For detailed information on the serialization concept, see the `Serializable` documentation.__
 */
class Serializer {

private:
  /// Object to be (de-)serialized
  Serializable& _serializable;
  /// Counter for the current block number being processed
  std::size_t _iBlock;
  /// Total memory size in bits (computed by `computeSizes()`)
  std::size_t _size;
  /// Default file name for IO
  std::string _fileName;

public:
  /// Constructor
  /**
   * If `serializable` is omitted, it has to be provided in the save method.
   */
  Serializer(Serializable& serializable, std::string fileName = "");

  /// Resets the `_iBlock` counter
  void resetCounter();

  /// Returns the total memory size in bits
  std::size_t getSize() const;

  /// Returns pointer to the memory of the current block and increments `iBlock`
  bool* getNextBlock(std::size_t& sizeBlock, const bool loadingMode);

  /// Loads a file and pushes the data into the serialized class. Always in parallel, i.e. one file per rank.
  /**
   * \todo implement similar methods for sending and receiving data through MPI
   */
  bool load(std::string fileName = "", const bool enforceUint=false);

  /// Save `_serializable` into file `filename`. Always in parallel, i.e. one file per rank.
  bool save(std::string fileName = "", const bool enforceUint=false);

  /// computes `_size` based on the individual definition of `getBlock()`
  void computeSize(const bool enforceRecompute=false);

private:
  /// Set `fileName` to `_fileName` if empty and set it to `"Serializable"` if both equal ""
  void validateFileName(std::string &fileName);
  /// Returns full file name for `_fileName`
  const std::string getFullFileName(const std::string& fileName);
};


/// Base class for serializable objects of _constant size_. For _dynamic size_ use `BufferSerializable`.
/**
 * All serializable classes have to implement their individual `getBlock()` method.
 * An individual `getNblock()` method must also be provided. An individual `getSerializableSize()` method should
 * also be provided for efficiency reasons.
 *
 * The `sumNblock` and `sumSerializableSize` operator structs can be used for accumulation of `getNblock()` methods
 * (and `getSerializableSize()` respectively), e.g. with an array or a `std::vector<Serializable>`.
 *
 * All `Serializable` subclasses with _dynamic size_ (unknown at compile time, e.g. holding `std::vector` or `std::map`
 * members) have to inherit from `BufferSerializable`. _Note: If the dynamic size is computable through __constant__
 * values (see `BlockLattice2D`), the `Serializable` does not need to be a `BufferSerializable`.
 *
 * ### The Basic Serialization Concept ###
 *
 * Any serializable class inherits from either `Serializable` or `BufferSerializable` (if it contains _dynamic-sized_
 * member variables) and has to implement its individual `getBlock()` method.
 *
 * `getBlock()` is called by the `Serializer` repeatedly with an increasing counter `iBlock`. `getBlock()` returns a
 * `(bool*)` address to the _i-th_ data block and fills `sizeBlock` with the corresponding size. As long as `getBlock()`
 * does not return a `nullptr`, `iBlock` is increased and `getBlock()` is called again by `Serializer`.
 *
 * It is _strongly recommended_ (and __obligatory__ for the correct usage of `register` methods) to define
 * `std::size_t currentBlock = 0;` within `getBlock()`. `currentBlock` will be increased by the `register` methods by
 * the number of blocks they occupy.
 *
 * For user's convenience the `Serializable` class provides `register` methods for _data of constant size_:
 * Method                               | Suitable for
 * ------------------------------------ | --------------------------
 * `registerVar()`                      | Primitive data types and arrays of those (e.g. `int`, `double`, `std::string`, ...)
 * `registerSerializableOfConstSize()`  | Constant-sized `Serializable` object
 * `registerSerializablesOfConstSize()` | Array of constant-sized `Serializable` objects
 *
 * - In `registerVar()`, `currentBlock` is counted up by 1 - `arrays` are treated as one block of size
 * `sizeof(DataType) * arrayLength`.
 * - In `registerSerializableOfConstSize()`, `currentBlock` is increased by
 * `getNblock()` of the given `Serializable`.
 * - In `registerSerializablesOfConstSize()`, `currentBlock` is increased by
 * `arrayLength * data.getNblock()` of the given `Serializable`.
 *
 *
 * __Note:__ Dynamic-sized objects need to inherit from `BufferSerializable`, which uses buffers and provides
 * additional `register` methods for:
 *
 * Method                                          | Suitable for
 * ----------------------------------------------- | --------------------------
 * `registerSerializable()`                        | Dynamic-sized `Serializable` object (for constant-sized `Serializable`
 *                                                 | use `registerSerializableOfConstSize()`
 * `registerStdVectorOfVars()`                     | `std::vector<DataType>` (for primitive `DataType`, e.g. `int`,
 *                                                 | `double`, ...)
 * `registerStdVectorOfSerializablesOfConstSize()` | `std::vector<DataType>` (for `Serializable`s of constant size)
 * `registerStdVectorOfSerializables()`            | `std::vector<DataType>` (for `Serializable`s of dynamic size)
 * `registerMap()`                                 | `std::map<DataTypeKey, DataTypeValue>` (for primitive types)
 *
 */
class Serializable {
public:
  /// Returns the address of the i-th block and its size.
  /**
   * \param iBlock      Index of the block to be returned
   * \param sizeBlock   Reference to the size of the returned block
   * \return            Pointer to the current block
   *
   * Each `getBlock()` method should look like this:
   *
   *     std::size_t currentBlock = 0;
   *     bool* dataPtr = nullptr;
   *
   *     // ... register methods...
   *
   *     return dataPtr;
   */
  virtual bool* getBlock(const std::size_t iBlock, std::size_t& sizeBlock,
                         const bool loadingMode = false) = 0;

  /// Returns the number of blocks.
  /**
   * All `Serializable` classes have to implement this method.
   */
  virtual std::size_t getNblock() const = 0;

  /// Returns the binary size of the data to be saved
  /**
   * _This method must be overloaded by all child classes._
   */
  virtual std::size_t getSerializableSize() const = 0;

  /// Save `Serializable` into file `fileName`
  bool save(std::string fileName = "", const bool enforceUint=false);

  /// Load `Serializable` from file `fileName`
  bool load(std::string fileName = "", const bool enforceUint=false);

  /// Sum functor for `getNblock()` of `std::vector<Serializable>` (for `std::accumulate`)
  /**
   * _Usage_: If you have `std::vector<Serializable> v`, then use accumulate as follows:
   *
   *     std::accumulate(v.begin(), v.end(), size_t(0), Serializable::sumNblock());
   */
  struct sumNblock : public std::binary_function<size_t, Serializable, size_t> {
    std::size_t operator()(std::size_t sum, const Serializable& s)
    {
      return sum + s.getNblock();
    }
  };

  /// Sum functor for `getSerializableSize()` of `std::vector<Serializable>` (for `std::accumulate`)
  /**
   * _Usage_: If you have `std::vector<Serializable> v`, then use accumulate as follows:
   *
   *     std::accumulate(v.begin(), v.end(), size_t(0), Serializable::sumSerializableSize());
   */
  struct sumSerializableSize : public std::binary_function<size_t, Serializable, size_t> {
    std::size_t operator()(std::size_t sum, const Serializable& s)
    {
      return sum + s.getSerializableSize();
    }
  };

protected:
  /// Register _primitive data types_ (`int`, `double`, ...) or arrays of those
  /**
   * This method is suitable for all _primitive data types_ or arrays of those. The address of the data is returned
   * in combination with the size `sizeof(DataType) * arrayLength`.
   *
   * \param iBlock         `iBlock` from `getBlock()` - to determine if this is the current block.
   * \param sizeBlock      `sizeBlock` from `getBlock()` - will be filled if this is the current block.
   * \param currentBlock   _local_ variable of `getBlock()` - will always be counted up by the
   *                       number of blocks this method registers (_always 1 in this case_).
   * \param dataPtr        `dataPtr` from `getBlock()` - will be filled with pointer to the data at `iBlock` if this is
   *                       the current block.
   * \param data           Reference to the data to be registered by this method. Fills `dataPtr` with a
   *                       `(bool*)`-casted pointer to `data` if this is the current block.
   * \param arrayLength    Number of elements of `DataType` in `data`, if `data` is an array. _Defaults to 1 for
   *                       single values._
   * \tparam DataType      Type of `data`
   */
  template<typename DataType>
  void registerVar(const std::size_t iBlock, std::size_t &sizeBlock, std::size_t &currentBlock, bool *&dataPtr,
                   const DataType &data, const size_t arrayLength = 1) const
  {
    if (iBlock == currentBlock) {
      sizeBlock = sizeof(DataType) * arrayLength;
      dataPtr = (bool *) (&data);
    }
    currentBlock++;
  }


  /// Register `Serializable` object of _constant size_.
  /**
   * This method is suitable for all `Serializable` objects that are of __constant size__.
   *
   * _For information about the parameters of this method, see `registerVar()`._
   *
   * This method registers a `Serializable` by simply delegating the `getBlock()` call to the `Serializable`.
   *
   * Since those `Serializable` objects __must(!)__ have constant return value from `Serializable.getNblock()`,
   * the number of blocks is known both in reading and writing mode.
   */
  template<typename DataType>
  void registerSerializableOfConstSize(const std::size_t iBlock, std::size_t &sizeBlock, std::size_t &currentBlock,
                                       bool *&dataPtr, DataType &data, const bool loadingMode=false)
  {
    static_assert(std::is_base_of<Serializable, DataType>::value, "DataType must be a Serializable.");

    if (iBlock >= currentBlock && iBlock < currentBlock + data.getNblock()) {
      dataPtr = data.getBlock(iBlock - currentBlock, sizeBlock, loadingMode);
    }
    currentBlock += data.getNblock();
  }

  /// Register an array of `Serializable` objects of _constant size_.
  /**
   * This method is suitable for all `Serializable` objects that are of __constant size__.
   *
   * _For information about the parameters of this method, see `registerVar()`._
   *
   * This method registers an array of `Serializable`s by delegating the `getBlock()` call
   * to the corresponding `Serializable`.
   *
   * Since those `Serializable` objects __must(!)__ have constant return value from `Serializable.getNblock()`,
   * the number of blocks is known both in reading and writing mode.
   */
  template<typename DataType>
  void registerSerializablesOfConstSize(const std::size_t iBlock, std::size_t &sizeBlock, std::size_t &currentBlock,
                                        bool *&dataPtr, DataType* data, const size_t arrayLength,
                                        const bool loadingMode=false)
  {
    static_assert(std::is_base_of<Serializable, DataType>::value, "DataType must be a Serializable.");

    if ( arrayLength > 0 ) {
      if (iBlock >= currentBlock && iBlock < currentBlock + arrayLength *