EntropyEngine::Core::IO::VirtualFileSystem

EntropyEngine::Core::IO::VirtualFileSystem

Public Classes

	Name
struct	Config

Public Functions

	Name
	~VirtualFileSystem()
FileWatch *	watchDirectory(const std::string & path, FileWatchCallback callback, const WatchOptions & options ={}) Watches a directory and invokes callback on changes.
void	unwatchDirectory(FileWatch * watch) Stops watching a directory.
FileOperationHandle	submit(std::string path, std::function< void(FileOperationHandle::OpState &, const std::string &, const ExecContext &)> body) const Submit async work to VFS WorkContractGroup (for backends).
void	setDefaultBackend(RefObject< IFileSystemBackend > backend) Sets the default backend used when no mount matches.
FileHandle	operator()(std::string path) Functor shorthand for createFileHandle(path).
std::unique_ptr< FileStream >	openStream(const std::string & path, StreamOptions options ={}) Opens a stream via the routed backend.
std::unique_ptr< BufferedFileStream >	openBufferedStream(const std::string & path, size_t bufferSize =65536, StreamOptions options ={}) Opens a buffered stream wrapper.
std::string	normalizePath(const std::string & path) const Normalize path for consistent comparison (for backends).
void	mountBackend(const std::string & prefix, RefObject< IFileSystemBackend > backend) Mounts a backend at a path prefix (longest-prefix match).
FileHandle	handle(std::string path) Shorthand for createFileHandle(path).
EntropyEngine::Core::Concurrency::WorkContractGroup *	getWorkGroup() const Get WorkContractGroup for advanced scheduling (for backends).
RefObject< IFileSystemBackend >	getDefaultBackend() const Gets the current default backend.
const Config &	getConfig() const Get VFS configuration (for backends).
RefObject< IFileSystemBackend >	findBackend(const std::string & path) const Finds the backend that would handle a given path.
std::unique_ptr< WriteBatch >	createWriteBatch(const std::string & path) Creates a WriteBatch builder for atomic multi-line edits.
FileHandle	createFileHandle(std::string path) Creates a value-semantic handle for the given path.
DirectoryHandle	createDirectoryHandle(std::string path) Creates a value-semantic handle for a directory path.
	VirtualFileSystem(EntropyEngine::Core::Concurrency::WorkContractGroup * group, Config cfg ={})

Friends

	Name
class	WriteBatch
class	LocalFileSystemBackend
class	FileWatchManager
class	FileHandle

Public Functions Documentation

function ~VirtualFileSystem

~VirtualFileSystem()

function watchDirectory

FileWatch * watchDirectory(
    const std::string & path,
    FileWatchCallback callback,
    const WatchOptions & options ={}
)

Watches a directory and invokes callback on changes.

Parameters:

• path Directory to watch
• callback Callback invoked on file events
• options Watch options (recursive, filters, etc.)

Return: Opaque FileWatch handle, or nullptr if watching not available

function unwatchDirectory

void unwatchDirectory(
    FileWatch * watch
)

Stops watching a directory.

Parameters:

• watch Handle returned by watchDirectory

function submit

FileOperationHandle submit(
    std::string path,
    std::function< void(FileOperationHandle::OpState &, const std::string &, const ExecContext &)> body
) const

Submit async work to VFS WorkContractGroup (for backends).

Parameters:

• path Path for the operation (used for diagnostics)
• body Lambda that populates OpState and calls complete()

Return: FileOperationHandle that will be completed when body finishes

Third-party backends can use this method to schedule async operations through the VFS’s WorkContractGroup instead of spawning their own threads. The body lambda receives OpState& to populate results and must call state.complete() when done.

Example usage in a backend:

FileOperationHandle MyBackend::readFile(const std::string& path, ReadOptions options) {
    return _vfs->submit(path, [this, options](auto& state, const std::string& p, const ExecContext&) {
        // Fetch data asynchronously
        state.bytes = fetchFromRemote(p, options);
        state.complete(FileOpStatus::Complete);
    });
}

function setDefaultBackend

void setDefaultBackend(
    RefObject< IFileSystemBackend > backend
)

Sets the default backend used when no mount matches.

Parameters:

• backend Backend implementation (RefObject ownership)

function operator()

inline FileHandle operator()(
    std::string path
)

Functor shorthand for createFileHandle(path).

function openStream

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

Opens a stream via the routed backend.

Parameters:

• path Target file path
• options Stream options (mode, buffering)

Return: Unique pointer to FileStream, or null on failure

function openBufferedStream

std::unique_ptr< BufferedFileStream > openBufferedStream(
    const std::string & path,
    size_t bufferSize =65536,
    StreamOptions options ={}
)

Opens a buffered stream wrapper.

Parameters:

• path Target file path
• bufferSize Buffer size in bytes
• options Base stream options (buffered is ignored; wrapper handles buffering)

Return: BufferedFileStream unique_ptr, or null on failure

function normalizePath

std::string normalizePath(
    const std::string & path
) const

Normalize path for consistent comparison (for backends).

Parameters:

• path Path to normalize

Return: Normalized path (canonical + case-insensitive on Windows)

Backends can use this to normalize paths consistently with VFS locking.

function mountBackend

void mountBackend(
    const std::string & prefix,
    RefObject< IFileSystemBackend > backend
)

Mounts a backend at a path prefix (longest-prefix match).

Parameters:

• prefix Path prefix (e.g., “s3://bucket/”)
• backend Backend to route to when prefix matches

function handle

inline FileHandle handle(
    std::string path
)

Shorthand for createFileHandle(path).

function getWorkGroup

inline EntropyEngine::Core::Concurrency::WorkContractGroup * getWorkGroup() const

Get WorkContractGroup for advanced scheduling (for backends).

Return: Pointer to WorkContractGroup, may be null

Backends can use this to detect same-group execution and avoid nested scheduling.

function getDefaultBackend

RefObject< IFileSystemBackend > getDefaultBackend() const

Gets the current default backend.

Return: RefObject to default backend (may be empty)

function getConfig

inline const Config & getConfig() const

Get VFS configuration (for backends).

Return: Reference to VFS configuration

Backends can check settings like defaultCreateParentDirs to respect VFS policy.

function findBackend

RefObject< IFileSystemBackend > findBackend(
    const std::string & path
) const

Finds the backend that would handle a given path.

Parameters:

• path Input path

Return: RefObject to backend (mounted or default), or empty if none

function createWriteBatch

std::unique_ptr< WriteBatch > createWriteBatch(
    const std::string & path
)

Creates a WriteBatch builder for atomic multi-line edits.

Parameters:

• path Target file path

Return: Unique pointer to WriteBatch

function createFileHandle

FileHandle createFileHandle(
    std::string path
)

Creates a value-semantic handle for the given path.

Parameters:

• path Target path

Return: FileHandle bound to this VFS

Routes the path to the appropriate backend (mounted or default). The handle is copyable and caches a backend-normalized identity key for equality/locking purposes.

function createDirectoryHandle

DirectoryHandle createDirectoryHandle(
    std::string path
)

Creates a value-semantic handle for a directory path.

Parameters:

• path Target directory path

Return: DirectoryHandle bound to this VFS

Routes the path to the appropriate backend (mounted or default). The handle is copyable and caches a backend-normalized identity key for equality purposes.

function VirtualFileSystem

explicit VirtualFileSystem(
    EntropyEngine::Core::Concurrency::WorkContractGroup * group,
    Config cfg ={}
)

Friends

friend WriteBatch

friend class WriteBatch(
    WriteBatch
);

friend LocalFileSystemBackend

friend class LocalFileSystemBackend(
    LocalFileSystemBackend
);

friend FileWatchManager

friend class FileWatchManager(
    FileWatchManager
);

friend FileHandle

friend class FileHandle(
    FileHandle
);

---

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