Memory-mapped file arena allocator. More...

#include <ah-map-arena.H>

Public Types
using	iterator = char *
	Iterator type for traversing allocated memory.

using	const_iterator = const char *
	Const iterator type.

using	size_type = size_t
	Size type for memory sizes.

Public Member Functions
void	init (const std::string &file_path_name, void *addr=nullptr)
	Initialize the arena with a backing file.

void	init_and_erase (const std::string &file_path_name)
	Initialize and erase any existing data.

	MapArena (const std::string &file_path_name)
	Construct an arena with a backing file.

	MapArena () noexcept=default
	Default constructor - creates an uninitialized arena.

	MapArena (const MapArena &)=delete
	Deleted copy constructor (arena cannot be copied).

MapArena &	operator= (const MapArena &)=delete
	Deleted copy assignment (arena cannot be copied).

	MapArena (MapArena &&other) noexcept
	Move constructor.

MapArena &	operator= (MapArena &&other) noexcept
	Move assignment operator.

	~MapArena ()
	Destructor - unmaps memory and closes file.

iterator	begin () noexcept
	Get iterator to the beginning of allocated memory.

const_iterator	begin () const noexcept
	Get const iterator to the beginning.

iterator	end () noexcept
	Get iterator past the last allocated byte.

const_iterator	end () const noexcept
	Get const iterator past the last allocated byte.

char *	base () const noexcept
	Get the base address of the mapped region.

size_type	avail () const noexcept
	Get the available memory in the current mapping.

char *	reserve (const size_type sz)
	Reserve memory for allocation.

void	commit (const size_type sz) noexcept
	Commit a previous reservation.

void	sync () noexcept
	Ensure data is persisted to disk.

size_type	size () const noexcept
	Get the total committed (allocated) size.

size_type	capacity () const noexcept
	Get the current capacity (mapped region size).

bool	empty () const noexcept
	Check if the arena is empty.

bool	is_initialized () const noexcept
	Check if the arena has been initialized.

void *	mapped_addr () const noexcept
	Get the mapped memory address.

int	file_descriptor () const noexcept
	Get the file descriptor.

Static Public Attributes
static constexpr size_t	initial_rgn_size = 4 * 1024
	Initial region size in bytes (4 KB).

Private Member Functions
bool	remap (const size_t sz)
	Remap the memory region to accommodate more allocations.

Private Attributes
char *	rgn_ptr = nullptr
	Pointer to the mapped memory region.

size_t	end_ = 0
	Allocation offset from rgn_ptr.

size_t	rgn_size = initial_rgn_size
	Current mapped region size.

int	fd = -1
	File descriptor for the backing file.

Friends
std::ostream &	operator<< (std::ostream &o, const MapArena &s)
	Output operator for debugging.

Detailed Description

Memory-mapped file arena allocator.

MapArena provides a persistent arena allocator backed by a memory-mapped file. It allows efficient allocation of memory chunks that are automatically persisted to disk, enabling crash recovery and data persistence across program restarts.

Features

Persistence: Data is automatically persisted to the underlying file
Crash recovery: If the file exists on construction, previous state is recovered
Dynamic growth: Arena automatically grows via mremap when needed
Zero-copy access: Memory is directly mapped, no copying needed
Shared memory: Can be used for inter-process communication (MAP_SHARED)

Memory Model

The arena uses a simple bump allocator model:

reserve(sz) returns a pointer to sz bytes of memory
commit(sz) marks sz bytes as allocated, advancing the allocation pointer
Memory is never individually freed; the entire arena must be reset

Example Usage

// Create or recover an arena
MapArena arena("/tmp/my_arena.dat");
 
// Allocate memory
char* ptr = arena.reserve(100);
if (ptr) {
  memcpy(ptr, "Hello, World!", 14);
  arena.commit(14);  // Only commit what was actually used
}
 
// Ensure persistence
arena.sync();
 
// Access allocated data
for (auto it = arena.begin(); it != arena.end(); ++it)
  std::cout << *it;

Thread Safety

This class is NOT thread-safe. External synchronization is required for concurrent access from multiple threads.

Important Notes

Pointers returned by reserve() may become invalid after subsequent reserve() calls that trigger a remap
The file format stores the allocation end offset at the beginning
Initial region size is 4KB, doubling as needed

Warning: Calling commit() multiple times without intervening reserve() or committing more than was reserved leads to undefined behavior.

See also: reserve() For allocating memory; commit() For finalizing allocations; sync() For ensuring persistence

Definition at line 127 of file ah-map-arena.H.

Member Typedef Documentation

◆ const_iterator

using Aleph::MapArena::const_iterator = const char *

Const iterator type.

Definition at line 177 of file ah-map-arena.H.

◆ iterator

using Aleph::MapArena::iterator = char *

Iterator type for traversing allocated memory.

Definition at line 174 of file ah-map-arena.H.

◆ size_type

using Aleph::MapArena::size_type = size_t

Size type for memory sizes.

Definition at line 180 of file ah-map-arena.H.

Constructor & Destructor Documentation

◆ MapArena() [1/4]

Aleph::MapArena::MapArena ( const std::string & file_path_name )

inlineexplicit

Construct an arena with a backing file.

Creates or opens the specified file and maps it to memory. If the file already exists, it is assumed to be a recovery scenario and the stored state is recovered.

Parameters

[in] file_path_name Path to the backing file.

Exceptions

std::runtime_error If initialization fails.

Definition at line 252 of file ah-map-arena.H.

References Aleph::init, and Aleph::maps().

◆ MapArena() [2/4]

Aleph::MapArena::MapArena ( )

defaultnoexcept

Default constructor - creates an uninitialized arena.

The arena must be initialized with init() before use.

◆ MapArena() [3/4]

Aleph::MapArena::MapArena ( const MapArena & )

delete

Deleted copy constructor (arena cannot be copied).

◆ MapArena() [4/4]

Aleph::MapArena::MapArena ( MapArena && other )

inlinenoexcept

Move constructor.

Transfers ownership of the mapped memory from another arena.

Parameters

[in,out] other Arena to move from (left in uninitialized state).

Definition at line 275 of file ah-map-arena.H.

References initial_rgn_size, and Aleph::maps().

◆ ~MapArena()

Aleph::MapArena::~MapArena ( )

inline

Destructor - unmaps memory and closes file.

Definition at line 317 of file ah-map-arena.H.

References fd, Aleph::maps(), rgn_ptr, and rgn_size.

Member Function Documentation

◆ avail()

size_type Aleph::MapArena::avail ( ) const

inlinenoexcept

Get the available memory in the current mapping.

Returns how many bytes can be allocated without triggering a remap.

Returns: Available bytes in the current mapping.

Definition at line 364 of file ah-map-arena.H.

References end_, and rgn_size.

Referenced by print_arena_status(), remap(), reserve(), and TEST_F().

◆ base()

char * Aleph::MapArena::base ( ) const

inlinenoexcept

Get the base address of the mapped region.

Equivalent to begin(). Returns the first address of reserved memory, or the first available address if nothing has been reserved.

Returns: Pointer to the base of the mapped region.

Definition at line 356 of file ah-map-arena.H.

References rgn_ptr.

Referenced by TEST_F(), and TEST_F().

◆ begin() [1/2]

const_iterator Aleph::MapArena::begin ( ) const

inlinenoexcept

Get const iterator to the beginning.

Returns: Const pointer to the first byte.

Definition at line 335 of file ah-map-arena.H.

References rgn_ptr.

◆ begin() [2/2]

iterator Aleph::MapArena::begin ( )

inlinenoexcept

Get iterator to the beginning of allocated memory.

Returns: Pointer to the first byte of the mapped region.

Definition at line 329 of file ah-map-arena.H.

References rgn_ptr.

Referenced by demo_arena_growth(), demo_basic_operations(), demo_log_buffer(), demo_structured_data(), TEST_F(), TEST_F(), and TEST_F().

◆ capacity()

size_type Aleph::MapArena::capacity ( ) const

inlinenoexcept

Get the current capacity (mapped region size).

Returns: Total size of the mapped region in bytes.

Definition at line 431 of file ah-map-arena.H.

References rgn_size.

Referenced by demo_arena_growth(), demo_memory_stats(), print_arena_status(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), and TEST_F().

◆ commit()

void Aleph::MapArena::commit ( const size_type sz )

inlinenoexcept

Commit a previous reservation.

Finalizes an allocation by advancing the end pointer. After commit(), the next reserve() will return addresses beyond the committed bytes.

Parameters

[in] sz Number of bytes to commit (must be <= reserved amount).

Precondition: reserve() must have been called with size >= sz.

Warning: Calling commit() without a matching reserve(), or with sz greater than what was reserved, leads to undefined behavior.

Definition at line 403 of file ah-map-arena.H.

References end_.

Referenced by demo_arena_growth(), demo_basic_operations(), demo_log_buffer(), demo_memory_stats(), demo_structured_data(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), and TEST_F().

◆ empty()

bool Aleph::MapArena::empty ( ) const

inlinenoexcept

Check if the arena is empty.

Returns: true if no memory has been committed, false otherwise.

Definition at line 440 of file ah-map-arena.H.

References end_.

Referenced by print_arena_status(), TEST_F(), TEST_F(), and TEST_F().

◆ end() [1/2]

const_iterator Aleph::MapArena::end ( ) const

inlinenoexcept

Get const iterator past the last allocated byte.

Returns: Const pointer past the last committed byte.

Definition at line 347 of file ah-map-arena.H.

References end_, and rgn_ptr.

◆ end() [2/2]

iterator Aleph::MapArena::end ( )

inlinenoexcept

Get iterator past the last allocated byte.

Returns: Pointer past the last committed byte.

Definition at line 341 of file ah-map-arena.H.

References end_, and rgn_ptr.

Referenced by demo_basic_operations(), demo_log_buffer(), TEST_F(), and TEST_F().

◆ file_descriptor()

int Aleph::MapArena::file_descriptor ( ) const

inlinenoexcept

Get the file descriptor.

Returns: File descriptor of the backing file, or -1 if not initialized.

Definition at line 467 of file ah-map-arena.H.

References fd.

Referenced by TEST_F(), TEST_F(), and TEST_F().

◆ init()

void Aleph::MapArena::init	(	const std::string &	file_path_name,
		void *	addr = `nullptr`
	)

inline

Initialize the arena with a backing file.

Opens or creates the specified file and maps it to memory. If the file already exists, recovers the previous allocation state.

Parameters

[in]	file_path_name	Path to the backing file.
[in]	addr	Optional hint address for mmap (usually nullptr).

Exceptions

std::runtime_error If file operations or mmap fails.

Definition at line 192 of file ah-map-arena.H.

References ah_runtime_error_unless, end_, fd, Aleph::maps(), rgn_ptr, and rgn_size.

Referenced by TEST_F(), and TEST_F().

◆ init_and_erase()

void Aleph::MapArena::init_and_erase ( const std::string & file_path_name )

inline

Initialize and erase any existing data.

Removes the file if it exists, then initializes a fresh arena.

Parameters

[in] file_path_name Path to the backing file.

Exceptions

std::runtime_error If initialization fails.

Definition at line 236 of file ah-map-arena.H.

References Aleph::init, and Aleph::maps().

Referenced by TEST_F().

◆ is_initialized()

bool Aleph::MapArena::is_initialized ( ) const

inlinenoexcept

Check if the arena has been initialized.

Returns: true if init() or constructor with filename was called.

Definition at line 449 of file ah-map-arena.H.

References rgn_ptr.

Referenced by TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), and TEST_F().

◆ mapped_addr()

void * Aleph::MapArena::mapped_addr ( ) const

inlinenoexcept

Get the mapped memory address.

Returns: Pointer to the mapped region, or nullptr if not initialized.

Definition at line 458 of file ah-map-arena.H.

References rgn_ptr.

Referenced by TEST_F(), TEST_F(), TEST_F(), and TEST_F().

◆ operator=() [1/2]

MapArena & Aleph::MapArena::operator= ( const MapArena & )

delete

Deleted copy assignment (arena cannot be copied).

◆ operator=() [2/2]

MapArena & Aleph::MapArena::operator= ( MapArena && other )

inlinenoexcept

Move assignment operator.

Parameters

[in,out] other Arena to move from.

Returns: Reference to this arena.

Definition at line 290 of file ah-map-arena.H.

References end_, fd, initial_rgn_size, Aleph::maps(), rgn_ptr, and rgn_size.

◆ remap()

bool Aleph::MapArena::remap ( const size_t sz )

inlineprivate

Remap the memory region to accommodate more allocations.

Doubles the region size repeatedly until it can hold sz additional bytes.

Parameters

[in] sz Required additional size in bytes.

Returns: true if remap succeeded, false otherwise.

Definition at line 148 of file ah-map-arena.H.

References ah_runtime_error_unless, avail(), end_, fd, Aleph::maps(), rgn_ptr, and rgn_size.

Referenced by reserve().

◆ reserve()

char * Aleph::MapArena::reserve ( const size_type sz )

inline

Reserve memory for allocation.

Returns a pointer to sz bytes of memory. The memory is not yet committed; you must call commit() to finalize the allocation.

Parameters

[in] sz Number of bytes to reserve.

Returns: Pointer to the reserved memory, or nullptr if allocation fails.

Warning: This call may trigger mremap, which invalidates all previously returned pointers. Use with extreme caution!

Note: The reserved memory is guaranteed to be readable/writable up to sz bytes from the returned pointer.

Definition at line 383 of file ah-map-arena.H.

References avail(), end_, remap(), and rgn_ptr.

Referenced by demo_arena_growth(), demo_basic_operations(), demo_log_buffer(), demo_memory_stats(), demo_structured_data(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), and TEST_F().

◆ size()

size_type Aleph::MapArena::size ( ) const

inlinenoexcept

Get the total committed (allocated) size.

Returns: Number of bytes that have been committed.

Definition at line 422 of file ah-map-arena.H.

References end_.

Referenced by demo_arena_growth(), demo_memory_stats(), print_arena_status(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), TEST_F(), and TEST_F().

◆ sync()

void Aleph::MapArena::sync ( )

inlinenoexcept

Ensure data is persisted to disk.

Calls msync() to flush changes to the backing file. Uses MS_ASYNC for better performance (non-blocking).

Definition at line 413 of file ah-map-arena.H.

References Aleph::maps(), rgn_ptr, and rgn_size.

Referenced by demo_basic_operations(), TEST_F(), TEST_F(), and TEST_F().

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<<	(	std::ostream &	o,
		const MapArena &	s
	)

friend

Output operator for debugging.

Parameters

[in,out]	o	Output stream.
[in]	s	Arena to output.

Returns: Reference to the output stream.

Definition at line 478 of file ah-map-arena.H.

Member Data Documentation

◆ end_

size_t Aleph::MapArena::end_ = 0

private

Allocation offset from rgn_ptr.

Definition at line 137 of file ah-map-arena.H.

Referenced by avail(), commit(), empty(), end(), end(), init(), operator=(), remap(), reserve(), and size().

◆ fd

int Aleph::MapArena::fd = -1

private

File descriptor for the backing file.

Definition at line 139 of file ah-map-arena.H.

Referenced by ~MapArena(), file_descriptor(), init(), operator=(), and remap().

◆ initial_rgn_size

constexpr size_t Aleph::MapArena::initial_rgn_size = 4 * 1024

staticconstexpr

Initial region size in bytes (4 KB).

Definition at line 132 of file ah-map-arena.H.

Referenced by MapArena(), demo_arena_growth(), operator=(), TEST(), TEST_F(), TEST_F(), and TEST_F().

◆ rgn_ptr

char* Aleph::MapArena::rgn_ptr = nullptr

private

Pointer to the mapped memory region.

Definition at line 136 of file ah-map-arena.H.

Referenced by ~MapArena(), base(), begin(), begin(), end(), end(), init(), is_initialized(), mapped_addr(), operator=(), remap(), reserve(), and sync().

◆ rgn_size

size_t Aleph::MapArena::rgn_size = initial_rgn_size

private

Current mapped region size.

Definition at line 138 of file ah-map-arena.H.

Referenced by ~MapArena(), avail(), capacity(), init(), operator=(), remap(), and sync().

The documentation for this class was generated from the following file:

ah-map-arena.H

Public Types

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Friends

Detailed Description

Features

Memory Model

Example Usage

Thread Safety

Important Notes

Member Typedef Documentation

◆ const_iterator

◆ iterator

◆ size_type

Constructor & Destructor Documentation

◆ MapArena() [1/4]

◆ MapArena() [2/4]

◆ MapArena() [3/4]

◆ MapArena() [4/4]

◆ ~MapArena()

Member Function Documentation

◆ avail()

◆ base()

◆ begin() [1/2]

◆ begin() [2/2]

◆ capacity()

◆ commit()

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ file_descriptor()

◆ init()

◆ init_and_erase()

◆ is_initialized()

◆ mapped_addr()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ remap()

◆ reserve()

◆ size()

◆ sync()

Friends And Related Symbol Documentation

◆ operator<<

Member Data Documentation

◆ end_

◆ fd

◆ initial_rgn_size

◆ rgn_ptr

◆ rgn_size