map_arena_persistence_example.cc File Reference

Premium MapArena example: persistence, offsets, and restart. More...

#include <ah-map-arena.H>
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <filesystem>
#include <iostream>
#include <limits>
#include <stdexcept>
#include <string>
#include <vector>

Include dependency graph for map_arena_persistence_example.cc:

Go to the source code of this file.

Functions
int	main ()

Detailed Description

Premium MapArena example: persistence, offsets, and restart.

This example focuses on a typical Aleph::MapArena use case (defined in ah-map-arena.H): building a persistent, append-only log backed by a memory-mapped file that can be recovered after reopening the file.

What this example demonstrates

1. Initialization and on-disk layout:
   • We store a small header at the beginning of the file.
   • The header's first field is end (a size_t) holding the logical end offset (committed bytes).
2. Persisting the logical end pointer:
   • MapArena reads a size_t from the beginning of the file on open.
   • In this example, we update that value in the header after each append, so the state can be recovered after reopening.
3. Record format:
   • Each record is [uint32_t len][len bytes payload].
   • This makes it straightforward to iterate and rebuild the log.
4. Safety around mremap():
   • reserve() may trigger mremap() and move the region, invalidating previously returned pointers. Therefore, we use the pattern: reserve -> write -> commit -> (optional) sync, and we avoid keeping pointers for long periods.
   • For durable references, store offsets (integers) and rebuild a pointer as base + offset.

Build

This file is built as part of the examples (see Examples/CMakeLists.txt) when -DBUILD_EXAMPLES=ON.

Run

The example creates a temporary file in /tmp and simulates a "restart" by reopening the file multiple times within the same process.

See also

ah-map-arena.H

Definition in file map_arena_persistence_example.cc.

Function Documentation

main()

int main

(

)

Definition at line 236 of file map_arena_persistence_example.cc.

References Aleph::maps().