MMappedVector.h

Go to the documentation of this file.

/**
 * @file MMappedVector.h
 * @brief Append-only vector template backed by a memory-mapped file.
 *
 * @c MMappedVector<T> provides a @c std::vector-like interface over a
 * memory-mapped file, enabling the provenance circuit data structures
 * (@c GateInformation, child UUID lists, extra string data) to survive
 * PostgreSQL restarts and be shared across processes.
 *
 * Design constraints:
 * - **Append-only**: elements are added with @c add(); existing elements
 *   can be updated in-place via @c operator[]() but cannot be removed.
 * - **Automatic growth**: when capacity is exhausted the backing file is
 *   grown by a factor of two and remapped.
 * - @c T must be a trivially copyable type so that it can be stored
 *   directly in the memory-mapped region.
 *
 * The implementation is in @c MMappedVector.hpp (included from this header).
 */
#ifndef MMAPPED_VECTOR_H
#define MMAPPED_VECTOR_H
 
#include <cstddef>
#include <cstdint>
#include <vector>
 
#include "MappedRegion.h"
 
extern "C" {
#include "provsql_utils.h"
}
 
/**
 * @brief Append-only, mmap-backed vector of elements of type @c T.
 *
 * @tparam T  The element type.  Must be trivially copyable.
 */
template <typename T>
class MMappedVector {
/**
 * @brief On-disk layout stored at the start of the backing file.
 *
 * @c d is a flexible array member holding the actual elements.
 */
struct data_t {
  uint64_t magic;      ///< File-type identifier
  uint16_t version;    ///< Format version of this file
  uint16_t elem_size;  ///< sizeof(T) at write time
  uint32_t flags;      ///< Bit 0: opened for writing and not closed since
  unsigned long nb_elements;  ///< Number of elements currently stored
  unsigned long capacity;     ///< Maximum elements before the next grow
  T d[];                      ///< Flexible array of elements
};
 
MappedRegion region;  ///< Backing storage (shared mmap, or heap buffer)
data_t *data;         ///< Typed view of @c region.base()
bool read_only_ = false;///< Mapped read-only: the header must not be written
bool unclean_ = false;///< The previous run left the dirty bit set
 
/** @brief Initial number of element slots allocated. */
static constexpr unsigned STARTING_CAPACITY=(1u << 16);
 
/** @brief Double the backing region and refresh @c data. */
void grow();
/**
 * @brief Unused overload kept for interface compatibility.
 * @param u  Ignored UUID parameter.
 * @param i  Ignored integer parameter.
 */
void set(pg_uuid_t u, unsigned long i);
 
public:
/**
 * @brief Open (or create) the mmap-backed vector.
 *
 * A file created here is stamped with @p version; an existing file is
 * accepted when its stamp is at most @p version, so a build that
 * understands version @em n keeps reading the files an older one wrote.
 * The caller reads the stamp back with @c version() to decide how to
 * interpret fields whose meaning changed.
 *
 * @param filename   Path to the backing file (created with
 *                   @c STARTING_CAPACITY slots if absent).
 * @param read_only  If @c true, map the file read-only.
 * @param magic      Expected magic value for format validation.
 * @param version    Highest format version this build writes and reads.
 */
MMappedVector(const char *filename, bool read_only, uint64_t magic,
              uint16_t version = 1);
/** @brief Sync and unmap the file. */
~MMappedVector();
 
/**
 * @brief Read-only element access by index.
 * @param k  Zero-based element index.
 * @return   Const reference to element @p k.
 */
const T &operator[](unsigned long k) const;
 
/**
 * @brief Read-write element access by index.
 * @param k  Zero-based element index.
 * @return   Reference to element @p k.
 */
T &operator[](unsigned long k);
 
/**
 * @brief Append an element to the end of the vector.
 *
 * Grows the backing file if the current capacity is exhausted.
 *
 * @param value  Element to append.
 */
void add(const T& value);
 
/**
 * @brief Return the number of elements currently stored.
 * @return Element count.
 */
inline unsigned long nbElements() const {
  return data->nb_elements;
}
 
/** @brief Return the format version stamped in the file's header. */
inline uint16_t version() const {
  return data->version;
}
 
/** @brief Stamp @p v into the header, declaring the file upgraded.
 *
 *  Only a pass that has rewritten every record to the new version's
 *  conventions may call this. */
inline void setVersion(uint16_t v) {
  data->version = v;
}
 
/** @brief Flush the backing region to its file (@c MappedRegion::sync()). */
void sync();
 
/** @brief Force the backing file to stable storage
 *  (@c MappedRegion::flush()). */
void flush();
 
/**
 * @brief Bit of @c data_t::flags set while the file is open for writing.
 *
 * Cleared on a clean close, so a file found with it still set was left
 * behind by a process that died (or by an immediate shutdown).  The
 * header layout is unchanged: the bit lives in what used to be reserved
 * padding, which older builds neither read nor write.
 */
static constexpr uint32_t FLAG_DIRTY = 1u;
 
/** @brief Whether this file still had @c FLAG_DIRTY set when it was
 *  opened, i.e. whoever wrote it last did not close it. */
inline bool uncleanShutdown() const {
  return unclean_;
}
};
 
 #endif /* MMAPPED_VECTOR_H */