EntropyEngine::Core::IO::FileHandle

EntropyEngine::Core::IO::FileHandle

Copyable handle to a file path routed through a backend. More…

#include <FileHandle.h>

Public Classes

	Name
struct	Metadata

Public Functions

	Name
FileOperationHandle	writeRange(uint64_t offset, std::span< const uint8_t > bytes) const Writes bytes starting at a specific offset.
FileOperationHandle	writeRange(uint64_t offset, std::span< const uint8_t > bytes, const WriteOptions & opts) const Writes bytes at offset with explicit WriteOptions (offset is applied to opts).
FileOperationHandle	writeLine(size_t lineNumber, std::string_view line) const Replaces a single line by index (0-based).
FileOperationHandle	writeLine(size_t lineNumber, std::string_view line, const WriteOptions & opts) const Replaces a single line with explicit WriteOptions (currently forwarded).
FileOperationHandle	writeAll(std::string_view text) const Writes the full text to the file (overwrites by default).
FileOperationHandle	writeAll(std::string_view text, const WriteOptions & opts) const Writes full text with explicit WriteOptions.
FileOperationHandle	writeAll(std::span< const uint8_t > bytes) const Writes raw bytes to the file (overwrites by default).
FileOperationHandle	writeAll(std::span< const uint8_t > bytes, const WriteOptions & opts) const Writes raw bytes with explicit WriteOptions.
FileOperationHandle	remove() const Deletes the file if it exists (idempotent).
FileOperationHandle	readRange(uint64_t offset, size_t length) const Reads a byte range from the file.
FileOperationHandle	readLineBinary(size_t lineNumber, uint8_t delimiter) const Reads a line using a custom byte delimiter (binary-safe).
FileOperationHandle	readLine(size_t lineNumber) const Reads a line by index (0-based), trimming line-ending.
FileOperationHandle	readAll() const Reads the entire file into memory.
std::unique_ptr< FileStream >	openWriteStream(bool append =false) const Opens an unbuffered write-only stream.
std::unique_ptr< FileStream >	openReadWriteStream() const Opens an unbuffered read-write stream.
std::unique_ptr< FileStream >	openReadStream() const Opens an unbuffered read-only stream.
std::unique_ptr< BufferedFileStream >	openBufferedStream(size_t bufferSize =65536) const Opens a buffered stream wrapper around an unbuffered stream.
const std::string &	normalizedKey() const Backend-aware normalized key for identity/locking.
const Metadata &	metadata() const Returns static metadata captured at handle construction.
FileOperationHandle	createEmpty() const Creates an empty file or truncates existing to zero.

Friends

	Name
class	VirtualFileSystem

Detailed Description

class EntropyEngine::Core::IO::FileHandle;

Copyable handle to a file path routed through a backend.

Construct via VirtualFileSystem::createFileHandle(). Operations are asynchronous; call wait() on the returned FileOperationHandle to block, or chain operations.

Design note: FileHandle is a dumb handle that delegates all I/O and policy decisions to the routed backend through the VirtualFileSystem. It avoids filesystem probing and contains no backend-specific logic; semantics are defined by the backend implementation.

WorkContractGroup group(2000);
VirtualFileSystem vfs(&group);
auto fh = vfs.createFileHandle("example.txt");
fh.writeAll("Hello\n").wait();
auto r = fh.readAll(); r.wait();
ENTROPY_LOG_INFO(r.contentsText());

Public Functions Documentation

function writeRange

FileOperationHandle writeRange(
    uint64_t offset,
    std::span< const uint8_t > bytes
) const

Writes bytes starting at a specific offset.

Parameters:

• offset Byte offset to begin writing
• bytes Data to write

Return: Handle for the asynchronous write

function writeRange

FileOperationHandle writeRange(
    uint64_t offset,
    std::span< const uint8_t > bytes,
    const WriteOptions & opts
) const

Writes bytes at offset with explicit WriteOptions (offset is applied to opts).

function writeLine

FileOperationHandle writeLine(
    size_t lineNumber,
    std::string_view line
) const

Replaces a single line by index (0-based).

Parameters:

• lineNumber Line to overwrite
• line New line content (without newline)

Return: Handle for the asynchronous write

Extends the file with blank lines if the index is beyond EOF. Line endings are preserved according to backend policy.

function writeLine

FileOperationHandle writeLine(
    size_t lineNumber,
    std::string_view line,
    const WriteOptions & opts
) const

Replaces a single line with explicit WriteOptions (currently forwarded).

function writeAll

FileOperationHandle writeAll(
    std::string_view text
) const

Writes the full text to the file (overwrites by default).

Parameters:

• text UTF-8 text to write

Return: Handle for the asynchronous write

Uses LF/CRLF policy as implemented by the backend. Use WriteBatch for line-wise edits.

function writeAll

FileOperationHandle writeAll(
    std::string_view text,
    const WriteOptions & opts
) const

Writes full text with explicit WriteOptions.

function writeAll

FileOperationHandle writeAll(
    std::span< const uint8_t > bytes
) const

Writes raw bytes to the file (overwrites by default).

Parameters:

• bytes Data to write

Return: Handle for the asynchronous write

function writeAll

FileOperationHandle writeAll(
    std::span< const uint8_t > bytes,
    const WriteOptions & opts
) const

Writes raw bytes with explicit WriteOptions.

function remove

FileOperationHandle remove() const

Deletes the file if it exists (idempotent).

Return: Handle for the asynchronous delete operation

function readRange

FileOperationHandle readRange(
    uint64_t offset,
    size_t length
) const

Reads a byte range from the file.

Parameters:

• offset Starting byte offset
• length Number of bytes to read

Return: Handle for the asynchronous read; status may be Partial if EOF reached early

function readLineBinary

FileOperationHandle readLineBinary(
    size_t lineNumber,
    uint8_t delimiter
) const

Reads a line using a custom byte delimiter (binary-safe).

Parameters:

• lineNumber Line index
• delimiter Byte delimiter to split lines

Return: Handle with raw bytes of the line

function readLine

FileOperationHandle readLine(
    size_t lineNumber
) const

Reads a line by index (0-based), trimming line-ending.

Parameters:

• lineNumber Line index to read

Return: Handle with contentsText() set to the line on success; Partial if index out of range

function readAll

FileOperationHandle readAll() const

Reads the entire file into memory.

Return: Handle representing the read operation

auto h = fh.readAll(); h.wait();
if (h.status()==FileOpStatus::Complete) ENTROPY_LOG_INFO(h.contentsText());

Asynchronously reads the full contents as bytes. Call contentsText() or contentsBytes() on the returned handle after wait().

function openWriteStream

std::unique_ptr< FileStream > openWriteStream(
    bool append =false
) const

Opens an unbuffered write-only stream.

Parameters:

• append If true, writes are appended; otherwise truncate/overwrite

Return: FileStream unique_ptr, or null on failure

function openReadWriteStream

std::unique_ptr< FileStream > openReadWriteStream() const

Opens an unbuffered read-write stream.

Return: FileStream unique_ptr, or null on failure

function openReadStream

std::unique_ptr< FileStream > openReadStream() const

Opens an unbuffered read-only stream.

Return: FileStream unique_ptr, or null on failure

function openBufferedStream

std::unique_ptr< BufferedFileStream > openBufferedStream(
    size_t bufferSize =65536
) const

Opens a buffered stream wrapper around an unbuffered stream.

Parameters:

• bufferSize Size of the internal buffer in bytes

Return: BufferedFileStream unique_ptr, or null on failure

function normalizedKey

inline const std::string & normalizedKey() const

Backend-aware normalized key for identity/locking.

Return: Normalized key string used for equality and advisory locks

function metadata

inline const Metadata & metadata() const

Returns static metadata captured at handle construction.

Return: Reference to file metadata (existence, size at creation time, etc.)

function createEmpty

FileOperationHandle createEmpty() const

Creates an empty file or truncates existing to zero.

Return: Handle for the asynchronous creation/truncation

Friends

friend VirtualFileSystem

friend class VirtualFileSystem(
    VirtualFileSystem
);

---

Updated on 2026-01-26 at 16:50:32 -0500