EntropyEngine::Core::IO::IFileSystemBackend

EntropyEngine::Core::IO::IFileSystemBackend

Inherits from EntropyEngine::Core::EntropyObject

Inherited by EntropyEngine::Core::IO::LocalFileSystemBackend, EntropyEngine::Core::IO::PackageBackend, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend

Public Classes

	Name
struct	AcquireWriteScopeResult Backend-specific primitive for write serialization.
struct	AcquireScopeOptions

Public Functions

	Name
	~IFileSystemBackend() override =default
virtual FileOperationHandle	writeLine(const std::string & path, size_t lineNumber, std::string_view line) =0 Replaces a single line by index (0-based).
virtual FileOperationHandle	writeFile(const std::string & path, std::span< const uint8_t > data, WriteOptions options ={}) =0 Writes file contents.
void	setVirtualFileSystem(VirtualFileSystem * vfs)
virtual FileOperationHandle	removeDirectory(const std::string & path) Removes a directory at the given path.
virtual FileOperationHandle	readLine(const std::string & path, size_t lineNumber) =0 Reads a single line by index (0-based).
virtual FileOperationHandle	readFile(const std::string & path, ReadOptions options ={}) =0 Reads file contents.
virtual std::unique_ptr< FileStream >	openStream(const std::string & path, StreamOptions options ={}) =0 Opens a stream for the given path.
virtual std::string	normalizeKey(const std::string & path) const
virtual FileOperationHandle	moveFile(const std::string & src, const std::string & dst, bool overwriteExisting =false)
virtual FileOperationHandle	listDirectory(const std::string & path, ListDirectoryOptions options ={}) Lists entries in the given directory.
virtual FileOperationHandle	getMetadataBatch(const BatchMetadataOptions & options)
virtual FileOperationHandle	getMetadata(const std::string & path) =0 Retrieves metadata for a file.
virtual BackendCapabilities	getCapabilities() const =0
virtual std::string	getBackendType() const =0
virtual bool	exists(const std::string & path) =0 Checks existence of a path.
virtual FileOperationHandle	deleteFile(const std::string & path) =0 Deletes a file.
virtual FileOperationHandle	createFile(const std::string & path) =0 Creates an empty file.
virtual FileOperationHandle	createDirectory(const std::string & path) Creates a directory at the given path.
virtual FileOperationHandle	copyFile(const std::string & src, const std::string & dst, const CopyOptions & options ={})
virtual const char *	className() const override Runtime class name for diagnostics and reflection.
virtual AcquireWriteScopeResult	acquireWriteScope(const std::string & path, AcquireScopeOptions options ={})

Protected Attributes

	Name
VirtualFileSystem *	_vfs

Additional inherited members

Protected Classes inherited from EntropyEngine::Core::EntropyObject

	Name
struct	HandleCore Optional handle identity stamped by an owner/registry.

Public Functions inherited from EntropyEngine::Core::EntropyObject

	Name
virtual	~EntropyObject() =default
virtual const TypeSystem::TypeInfo *	typeInfo() const Optional richer type information; may be null.
bool	tryRetain() const Attempts to retain only if the object is still alive.
virtual std::string	toString() const Human-readable short string (class@ptr by default).
void	retain() const Increments the reference count.
void	release() const Decrements the reference count and deletes when it reaches zero.
uint32_t	refCount() const Current reference count (approximate under contention).
EntropyObject &	operator=(const EntropyObject & ) =delete
EntropyObject &	operator=(EntropyObject && ) =delete
bool	hasHandle() const
template <class OwnerT > OwnerT *	handleOwnerAs() const Returns the stamped owner pointer cast to the requested type.
const void *	handleOwner() const
uint32_t	handleIndex() const
uint64_t	handleId() const
uint32_t	handleGeneration() const
WeakControlBlock *	getWeakControlBlock() const Lazily retrieves or creates the weak control block.
virtual std::string	description() const Long-form description; defaults to toString().
virtual std::string	debugString() const Debug-oriented string including refcount and handle when present.
virtual uint64_t	classHash() const Stable type hash for cross-language identification.
	EntropyObject() =default
	EntropyObject(EntropyObject && ) =delete
	EntropyObject(const EntropyObject & ) =delete

Protected Functions inherited from EntropyEngine::Core::EntropyObject

	Name
void	_setHandleIdentity(void * owner, uint32_t index, uint32_t generation)
void	_clearHandleIdentity()

Protected Attributes inherited from EntropyEngine::Core::EntropyObject

	Name
std::atomic< WeakControlBlock * >	_weakBlock Lazily allocated control block for weak refs.
std::atomic< uint32_t >	_refCount Thread-safe retain/release counter.
struct EntropyEngine::Core::EntropyObject::HandleCore	_handle

Friends inherited from EntropyEngine::Core::EntropyObject

	Name
struct	HandleAccess

Public Functions Documentation

function ~IFileSystemBackend

~IFileSystemBackend() override =default

function writeLine

virtual FileOperationHandle writeLine(
    const std::string & path,
    size_t lineNumber,
    std::string_view line
) =0

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

Parameters:

• path Target file
• lineNumber Line index
• line New content without newline

Return: Handle representing the write

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::writeLine, EntropyEngine::Core::IO::PackageBackend::writeLine, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::writeLine

function writeFile

virtual FileOperationHandle writeFile(
    const std::string & path,
    std::span< const uint8_t > data,
    WriteOptions options ={}
) =0

Writes file contents.

Parameters:

• path Target path
• data Bytes to write
• options WriteOptions (append/offset/truncate, parent dirs, final newline, fsync)

Return: Handle representing the async write

Note:

• Symlink behavior: Writes follow symlinks and modify the target file.
• Dangling symlinks cause FileError::FileNotFound.
• Special files (FIFO, device, socket) are rejected with FileError::InvalidPath on Unix.
• Set options.fsync=true for durability guarantee (Unix/POSIX only; forces data to disk).

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::writeFile, EntropyEngine::Core::IO::PackageBackend::writeFile, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::writeFile

function setVirtualFileSystem

inline void setVirtualFileSystem(
    VirtualFileSystem * vfs
)

function removeDirectory

inline virtual FileOperationHandle removeDirectory(
    const std::string & path
)

Removes a directory at the given path.

Parameters:

• path Directory to remove

Return: A FileOperationHandle; status() will be Pending for default impl

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::removeDirectory, EntropyEngine::Core::IO::PackageBackend::removeDirectory

Backend-specific semantics:

• LocalFileSystemBackend: Removes directory and all contents recursively (like rm -rf). Succeeds even if directory doesn’t exist (idempotent).
• S3Backend (future): Deletes all objects with this prefix. Warning: Potentially expensive for deep hierarchies. May require pagination and multiple requests.
• AzureBlobBackend (future): Similar to S3. Deletes all blobs matching prefix. With HNS, can delete directory object itself if empty.
• WebDAVBackend (future): Issues HTTP DELETE on collection. May fail if collection is non-empty depending on server implementation (RFC 4918 allows but doesn’t require recursive delete).
• HTTPBackend (non-WebDAV): Not supported. Returns empty handle.

function readLine

virtual FileOperationHandle readLine(
    const std::string & path,
    size_t lineNumber
) =0

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

Parameters:

• path Target file
• lineNumber Line index

Return: Handle with contentsBytes/Text containing the line

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::readLine, EntropyEngine::Core::IO::PackageBackend::readLine, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::readLine

function readFile

virtual FileOperationHandle readFile(
    const std::string & path,
    ReadOptions options ={}
) =0

Reads file contents.

Parameters:

• path Path to read
• options ReadOptions (offset/length, binary)

Return: Handle whose contents are available after wait()

Note:

• Symlink behavior: File operations follow symlinks by default on Unix systems.
• Dangling symlinks cause FileError::FileNotFound.
• Use getMetadata() with FileMetadata::isSymlink to detect symlinks before operations.
• Special files (FIFO, device, socket) are rejected with FileError::InvalidPath on Unix.

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::readFile, EntropyEngine::Core::IO::PackageBackend::readFile, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::readFile

function openStream

virtual std::unique_ptr< FileStream > openStream(
    const std::string & path,
    StreamOptions options ={}
) =0

Opens a stream for the given path.

Parameters:

• path Target path
• options StreamOptions (mode, buffering)

Return: Unique pointer to FileStream, or null on failure

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::openStream, EntropyEngine::Core::IO::PackageBackend::openStream, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::openStream

function normalizeKey

inline virtual std::string normalizeKey(
    const std::string & path
) const

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::normalizeKey, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::normalizeKey

function moveFile

inline virtual FileOperationHandle moveFile(
    const std::string & src,
    const std::string & dst,
    bool overwriteExisting =false
)

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::moveFile

function listDirectory

inline virtual FileOperationHandle listDirectory(
    const std::string & path,
    ListDirectoryOptions options ={}
)

Lists entries in the given directory.

Parameters:

• path Directory to list
• options Listing options (recursion, filters, sorting, pagination)

Return: A FileOperationHandle; status() will be Pending for default impl

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::listDirectory, EntropyEngine::Core::IO::PackageBackend::listDirectory, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::listDirectory

Backend-specific semantics:

• LocalFileSystemBackend: Native filesystem iteration using std::filesystem::directory_iterator. Supports recursion, glob patterns, hidden file filtering, sorting, and pagination.
• S3Backend (future): Uses ListObjectsV2 with delimiter=”/” to simulate directory listing. Recursion requires multiple requests. Pagination is native (continuation tokens).
• AzureBlobBackend (future): Uses List Blobs API with delimiter=”/”. Similar to S3. With HNS enabled, can use true hierarchical listing APIs.
• WebDAVBackend (future): Issues HTTP PROPFIND request with Depth: 1 header for non-recursive, Depth: infinity for recursive. Parses XML response (RFC 4918 multistatus).
• HTTPBackend (non-WebDAV): Not supported. Returns empty handle.

function getMetadataBatch

inline virtual FileOperationHandle getMetadataBatch(
    const BatchMetadataOptions & options
)

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::getMetadataBatch

function getMetadata

virtual FileOperationHandle getMetadata(
    const std::string & path
) =0

Retrieves metadata for a file.

Parameters:

• path Target path

Return: Handle whose metadata() is populated after wait()

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::getMetadata, EntropyEngine::Core::IO::PackageBackend::getMetadata, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::getMetadata

function getCapabilities

virtual BackendCapabilities getCapabilities() const =0

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::getCapabilities, EntropyEngine::Core::IO::PackageBackend::getCapabilities, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::getCapabilities

function getBackendType

virtual std::string getBackendType() const =0

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::getBackendType, EntropyEngine::Core::IO::PackageBackend::getBackendType, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::getBackendType

function exists

virtual bool exists(
    const std::string & path
) =0

Checks existence of a path.

Parameters:

• path Target path

Return: true if path exists, false otherwise

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::exists, EntropyEngine::Core::IO::PackageBackend::exists, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::exists

function deleteFile

virtual FileOperationHandle deleteFile(
    const std::string & path
) =0

Deletes a file.

Parameters:

• path Target path

Return: Handle representing the delete operation

Note: Symlink behavior: Deletes the symlink itself, not the target.

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::deleteFile, EntropyEngine::Core::IO::PackageBackend::deleteFile, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::deleteFile

function createFile

virtual FileOperationHandle createFile(
    const std::string & path
) =0

Creates an empty file.

Parameters:

• path Target path

Return: Handle representing the create operation

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::createFile, EntropyEngine::Core::IO::PackageBackend::createFile, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::createFile

function createDirectory

inline virtual FileOperationHandle createDirectory(
    const std::string & path
)

Creates a directory at the given path.

Parameters:

• path Directory to create

Return: A FileOperationHandle; status() will be Pending for default impl

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::createDirectory, EntropyEngine::Core::IO::PackageBackend::createDirectory, EntropyEngine::Networking::WebDAV::WebDAVFileSystemBackend::createDirectory

Backend-specific semantics:

• LocalFileSystemBackend: Creates all parent directories (like mkdir -p). Always succeeds if directory already exists.
• S3Backend (future): Creates a 0-byte marker object with ”/” suffix for compatibility with tools expecting directory markers. This is optional; S3 has no native directory concept.
• AzureBlobBackend (future): With hierarchical namespace (HNS) enabled, creates a true directory object. Without HNS, creates a 0-byte blob with ”/” suffix (like S3).
• WebDAVBackend (future): Issues HTTP MKCOL request to create collection (directory).
• HTTPBackend (non-WebDAV): Not supported. Returns empty handle.

function copyFile

inline virtual FileOperationHandle copyFile(
    const std::string & src,
    const std::string & dst,
    const CopyOptions & options ={}
)

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::copyFile

function className

inline virtual const char * className() const override

Runtime class name for diagnostics and reflection.

Reimplements: EntropyEngine::Core::EntropyObject::className

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::className

function acquireWriteScope

inline virtual AcquireWriteScopeResult acquireWriteScope(
    const std::string & path,
    AcquireScopeOptions options ={}
)

Reimplemented by: EntropyEngine::Core::IO::LocalFileSystemBackend::acquireWriteScope

Protected Attributes Documentation

variable _vfs

VirtualFileSystem * _vfs = nullptr;

---

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