sol3::core::SizeDelimitedLogWriter Class Reference

#include <sol3/core/size_delimited_log_writer.h>

Inheritance diagram for sol3::core::SizeDelimitedLogWriter:

Public Member Functions
	SizeDelimitedLogWriter (cpp::fs::path log_path)
	~SizeDelimitedLogWriter ()
void	open (cpp::fs::path log_path)
	Opens or replaces the current log file for writing. More...
void	close ()
	Closes the log file and clears the path. More...
bool	isOpen () const
cpp::fs::path const &	logPath () const
void	writeSizePrefixed (flatbuffers::span< uint8_t const > frame)
void	commit (size_t message_count)
void	rollback ()
	Roll back to currentOffset(), discarding uncommitted writes. More...
void	writeNonSizePrefixedUnaligned (flatbuffers::span< uint8_t const > data)
void	rewriteSizePrefixed (size_t offset, flatbuffers::span< uint8_t const > frame)
size_t	currentOffset () const
	Returns the current write position in the file (always 8-byte aligned). More...
void	write (char const *data, size_t size) override
Public Member Functions inherited from sol3::core::IStreamWriter
virtual	~IStreamWriter ()=default

Detailed Description

Writes size-prefixed frames to a stream with 8-byte alignment.

Layout: | uint32_t size (LE) | payload bytes (N) | padding (0..7) |

Wire format:

• Each frame starts with a 4-byte little-endian uint32_t size prefix.
• The size equals the payload length in bytes.
• Payload bytes follow immediately after the prefix.
• Padding bytes (zeros) are appended so the next frame starts on an 8-byte boundary, but the padding is not included in the size prefix.

Alignment rationale:

• FlatBuffers expects 8-byte alignment for some tables; keeping frames aligned allows mmap reads directly into FlatBuffer roots without realignment or copying.
• FlatBuffers written with SizePrefixed convention will maintain alignment
• Payloads that don't already have a size prefix and don't care about alignment are also supported.

Constructor & Destructor Documentation

SizeDelimitedLogWriter()

sol3::core::SizeDelimitedLogWriter::SizeDelimitedLogWriter ( cpp::fs::path  log_path )

explicit

Constructs a writer and opens the log file.

Preconditions:

• log_path must be non-empty.

Postconditions:

• The log file is open for read/write and truncated to zero length.

~SizeDelimitedLogWriter()

sol3::core::SizeDelimitedLogWriter::~SizeDelimitedLogWriter

(

)

Member Function Documentation

close()

void sol3::core::SizeDelimitedLogWriter::close

(

)

Closes the log file and clears the path.

commit()

void sol3::core::SizeDelimitedLogWriter::commit

(

size_t

message_count

)

Validates and commits N size-prefixed messages written to the stream. Ensures each message is padded to an 8-byte boundary.

currentOffset()

size_t sol3::core::SizeDelimitedLogWriter::currentOffset

(

)

const

Returns the current write position in the file (always 8-byte aligned).

isOpen()

bool sol3::core::SizeDelimitedLogWriter::isOpen

(

)

const

logPath()

cpp::fs::path const& sol3::core::SizeDelimitedLogWriter::logPath ( ) const

inline

open()

void sol3::core::SizeDelimitedLogWriter::open

(

cpp::fs::path

log_path

)

Opens or replaces the current log file for writing.

rewriteSizePrefixed()

void sol3::core::SizeDelimitedLogWriter::rewriteSizePrefixed	(	size_t	offset,
		flatbuffers::span< uint8_t const >	frame
	)

Rewrites a size-prefixed, aligned frame in place at the given offset.

Preconditions:

• offset must point to the start of an existing frame prefix.
• frame is size-prefixed and the prefix value matches the payload size.
• frame.size() == sizeof(uint32_t) + payload size.
• The stored prefix at offset matches the new prefix value.

Postconditions:

• The frame payload bytes at the given offset are replaced in place.
• The stored prefix remains unchanged.

rollback()

void sol3::core::SizeDelimitedLogWriter::rollback

(

)

Roll back to currentOffset(), discarding uncommitted writes.

write()

void sol3::core::SizeDelimitedLogWriter::write ( char const *  data, size_t  size  )

overridevirtual

Append raw bytes to the current uncommitted position. Call commit() to finalize bytes; uncommitted data is discarded. It is valid to call write() multiple times before committing.

Implements sol3::core::IStreamWriter.

writeNonSizePrefixedUnaligned()

void sol3::core::SizeDelimitedLogWriter::writeNonSizePrefixedUnaligned

(

flatbuffers::span< uint8_t const >

data

)

Writes a non-prefixed payload and appends alignment padding bytes. NOTE: this does not preserve the alignment of the data, as it requires adding a 4 byte prefix and will shift the data by 4 bytes.

Preconditions:

• The stream must be open.
• data size must fit in uint32_t.

Postconditions:

• The size prefix is computed as data.size() and written as a 4-byte little-endian uint32_t at the pre-call currentOffset().
• The data bytes are written next, followed by zero alignment padding bytes so the next frame starts on an 8-byte boundary.
• Data readers must tolerate alignment padding bytes appended after the payload.

writeSizePrefixed()

void sol3::core::SizeDelimitedLogWriter::writeSizePrefixed

(

flatbuffers::span< uint8_t const >

frame

)

Writes a size-prefixed frame and appends alignment padding bytes.

Preconditions:

• The stream must be open.
• frame is size-prefixed and the prefix value matches the payload size.
• frame.size() == sizeof(uint32_t) + payload size.

Postconditions:

• The frame is written starting at the pre-call currentOffset().
• Zero alignment padding bytes are appended so the next frame starts on an 8-byte boundary.

---

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

• /workspaces/astro/sol3-sdk/cpp/sol3/core/size_delimited_log_writer.h