High-performance WAL writer using a ring of N memory-mapped segments. More...

#include <wal_mapped_segment.hpp>

Public Member Functions
	WalMmapWriter (const WalMmapWriter &)=delete

WalMmapWriter &	operator= (const WalMmapWriter &)=delete

	WalMmapWriter (WalMmapWriter &&o)

WalMmapWriter &	operator= (WalMmapWriter &&o)

	~WalMmapWriter ()

expected< int64_t >	append (const uint8_t *data, size_t size)
	Append a record to the WAL.

expected< int64_t >	append (const char *data, size_t size)
	Append a record from a char buffer.

expected< int64_t >	append (std::string_view sv)
	Append a record from a string_view.

expected< int64_t >	append (const std::vector< uint8_t > &v)
	Append a record from a byte vector.

expected< void >	flush (bool do_sync=false)
	Flush the active segment to storage.

expected< void >	close ()
	Close the writer: stop the background thread, flush and close all segments.

bool	is_open () const noexcept
	Check whether the writer is still open (not yet closed).

int64_t	next_seq () const noexcept
	Return the next sequence number that will be assigned.

const std::string &	dir () const noexcept
	Return the output directory path.

std::vector< std::string >	segment_paths () const
	Return paths of all current ring segments plus any older WAL files in the directory.

Static Public Member Functions
static expected< WalMmapWriter >	open (WalMmapOptions opts)
	Open a new WalMmapWriter in the given directory.

Detailed Description

High-performance WAL writer using a ring of N memory-mapped segments.

Achieves sub-microsecond append latency (~223 ns) by writing directly into mmap'd memory. A background thread pre-allocates and pre-faults standby segments so rotation is nearly free.

File format: Identical to WalWriter (WAL_FILE_MAGIC at byte 0, records at byte 16). WalReader works unchanged on WalMmapWriter segment files.

Thread safety: NOT thread-safe for concurrent appends. Single-writer model. flush() and close() must be called from the same thread as append().

Crash safety: CRC is written LAST with a release fence. WalReader stops at bad/missing CRC, recovering all complete records.

Note: Move-constructible. The background thread is stopped and restarted during move. Call segment_paths() BEFORE close() – paths are unavailable after the writer is closed.

See also: WalMmapOptions, MappedSegment, WalReader

Definition at line 450 of file wal_mapped_segment.hpp.

Constructor & Destructor Documentation

◆ WalMmapWriter() [1/2]

signet::forge::WalMmapWriter::WalMmapWriter ( const WalMmapWriter & )

delete

◆ WalMmapWriter() [2/2]

signet::forge::WalMmapWriter::WalMmapWriter ( WalMmapWriter && o )

inline

Definition at line 455 of file wal_mapped_segment.hpp.

◆ ~WalMmapWriter()

signet::forge::WalMmapWriter::~WalMmapWriter ( )

inline

Definition at line 508 of file wal_mapped_segment.hpp.

Member Function Documentation

◆ append() [1/4]

expected< int64_t > signet::forge::WalMmapWriter::append	(	const char *	data,
		size_t	size
	)

inline

Append a record from a char buffer.

Parameters

data	Pointer to the record payload.
size	Size of the payload in bytes.

Returns: The assigned sequence number, or an Error.

Definition at line 685 of file wal_mapped_segment.hpp.

◆ append() [2/4]

expected< int64_t > signet::forge::WalMmapWriter::append ( const std::vector< uint8_t > & v )

inline

Append a record from a byte vector.

Parameters

v	The record payload.

Returns: The assigned sequence number, or an Error.

Definition at line 699 of file wal_mapped_segment.hpp.

◆ append() [3/4]

expected< int64_t > signet::forge::WalMmapWriter::append	(	const uint8_t *	data,
		size_t	size
	)

inline

Append a record to the WAL.

Returns the assigned sequence number.

NOT thread-safe – single-writer model. Automatically rotates to the next segment when the active segment is full. Wakes the background thread when the active segment is 75% full.

Parameters

data	Pointer to the record payload.
size	Size of the payload in bytes (max 4 GB).

Returns: The sequence number assigned to this record, or an Error.

Definition at line 601 of file wal_mapped_segment.hpp.

◆ append() [4/4]

expected< int64_t > signet::forge::WalMmapWriter::append ( std::string_view sv )

inline

Append a record from a string_view.

Parameters

sv	The record payload.

Returns: The assigned sequence number, or an Error.

Definition at line 692 of file wal_mapped_segment.hpp.

◆ close()

expected< void > signet::forge::WalMmapWriter::close ( )

inline

Close the writer: stop the background thread, flush and close all segments.

Returns: Success (always succeeds after joining the background thread).

Definition at line 717 of file wal_mapped_segment.hpp.

◆ dir()

const std::string & signet::forge::WalMmapWriter::dir ( ) const

inlinenoexcept

Return the output directory path.

Definition at line 749 of file wal_mapped_segment.hpp.

◆ flush()

expected< void > signet::forge::WalMmapWriter::flush ( bool do_sync = false )

inline

Flush the active segment to storage.

Parameters

do_sync If true (or opts_.sync_on_flush), use synchronous flush; otherwise async.

Returns: Success, or an Error if already closed.

Definition at line 706 of file wal_mapped_segment.hpp.

◆ is_open()

bool signet::forge::WalMmapWriter::is_open ( ) const

inlinenoexcept

Check whether the writer is still open (not yet closed).

Definition at line 745 of file wal_mapped_segment.hpp.

◆ next_seq()

int64_t signet::forge::WalMmapWriter::next_seq ( ) const

inlinenoexcept

Return the next sequence number that will be assigned.

Definition at line 747 of file wal_mapped_segment.hpp.

◆ open()

static expected< WalMmapWriter > signet::forge::WalMmapWriter::open ( WalMmapOptions opts )

inlinestatic

Open a new WalMmapWriter in the given directory.

Creates the directory if it does not exist. Synchronously allocates and pre-faults the first segment; the background thread is started after the returned writer is moved into its final location.

Parameters

opts	Writer options (directory, segment size, ring count, etc.).

Returns: A ready-to-append writer, or an Error on validation/IO failure.

Definition at line 521 of file wal_mapped_segment.hpp.

◆ operator=() [1/2]

WalMmapWriter & signet::forge::WalMmapWriter::operator= ( const WalMmapWriter & )

delete

◆ operator=() [2/2]

WalMmapWriter & signet::forge::WalMmapWriter::operator= ( WalMmapWriter && o )

inline

Definition at line 480 of file wal_mapped_segment.hpp.

◆ segment_paths()

std::vector< std::string > signet::forge::WalMmapWriter::segment_paths ( ) const

inline

Return paths of all current ring segments plus any older WAL files in the directory.

Note: Call this BEFORE close() – paths become unavailable after segments are unmapped.

Returns: Sorted vector of segment file paths.

Definition at line 755 of file wal_mapped_segment.hpp.

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

include/signet/ai/wal_mapped_segment.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ WalMmapWriter() [1/2]

◆ WalMmapWriter() [2/2]

◆ ~WalMmapWriter()

Member Function Documentation

◆ append() [1/4]

◆ append() [2/4]

◆ append() [3/4]

◆ append() [4/4]

◆ close()

◆ dir()

◆ flush()

◆ is_open()

◆ next_seq()

◆ open()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ segment_paths()