EntropyEngine::Core::IO::DirectoryHandle

EntropyEngine::Core::IO::DirectoryHandle

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

#include <DirectoryHandle.h>

Public Classes

	Name
struct	Metadata

Public Functions

	Name
FileOperationHandle	remove(bool recursive =false) const Removes the directory at this path.
const std::string &	normalizedKey() const Backend-aware normalized key for identity/locking.
const Metadata &	metadata() const Returns static metadata captured at handle construction.
FileOperationHandle	list(const ListDirectoryOptions & options ={}) const Lists the contents of this directory.
FileOperationHandle	getMetadata() const Retrieves metadata for this directory.
FileOperationHandle	create(bool createParents =true) const Creates the directory at this path.

Friends

	Name
class	VirtualFileSystem

Detailed Description

class EntropyEngine::Core::IO::DirectoryHandle;

Copyable handle to a directory path routed through a backend.

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

Design note: DirectoryHandle is a dumb handle; it does not probe the filesystem and contains no backend-specific behavior. All operations delegate to the routed backend through the VirtualFileSystem.

WorkContractGroup group(2000);
VirtualFileSystem vfs(&group);
auto dh = vfs.createDirectoryHandle("my_folder");
dh.create().wait();
auto listing = dh.list(); listing.wait();
for (const auto& entry : listing.directoryEntries()) {
    ENTROPY_LOG_INFO("Entry: " + entry.name);
}
dh.remove(true).wait(); // recursive

Public Functions Documentation

function remove

FileOperationHandle remove(
    bool recursive =false
) const

Removes the directory at this path.

Asynchronously removes the directory. Behavior is backend-specific:

• LocalFileSystem: Fails if non-empty unless recursive=true
• Object storage (S3/Azure): Deletes all objects with this prefix (potentially expensive) recursiveIf true, remove contents recursively (default false)

Handle representing the remove operation

function normalizedKey

inline const std::string & normalizedKey() const

Backend-aware normalized key for identity/locking.

Return: Normalized key string used for equality

function metadata

inline const Metadata & metadata() const

Returns static metadata captured at handle construction.

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

function list

FileOperationHandle list(
    const ListDirectoryOptions & options ={}
) const

Lists the contents of this directory.

Parameters:

• options Listing options (recursion, filters, sorting, pagination)

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

Asynchronously lists directory contents. Call directoryEntries() on the returned handle after wait() to access results.

function getMetadata

FileOperationHandle getMetadata() const

Retrieves metadata for this directory.

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

Asynchronously retrieves directory metadata (exists, permissions, timestamps).

function create

FileOperationHandle create(
    bool createParents =true
) const

Creates the directory at this path.

Asynchronously creates the directory. Behavior is backend-specific. Note: Currently, parameters are hints and may be ignored by the backend.

• LocalFileSystem: Always creates all parent directories (mkdir -p semantics), regardless of createParents. Operation is idempotent.
• Object storage (S3/Azure): May create 0-byte marker object (future). createParentsHint to create parent directories as needed (currently ignored)

Handle representing the create operation

Friends

friend VirtualFileSystem

friend class VirtualFileSystem(
    VirtualFileSystem
);

---

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