Skip to content

ludus::foundation::filesystem

Ludus Wiki · API overview · Browse API

Namespace

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/async.hpp

Enumerations

AsyncStatus

enum class AsyncStatus : uint8
Admission/lifecycle outcome, independent of the eventual read result.

Related types: uint8

Ok

Ok
Operation succeeded.

InvalidArgument

InvalidArgument
Invalid configuration, file, range or options.

NotInitialized

NotInitialized
Initialize has not succeeded.

AlreadyInitialized

AlreadyInitialized
Shutdown and drain before destroying an initialized scheduler.

Stopped

Stopped
Shutdown has stopped admission.

OutOfMemory

OutOfMemory
Fixed scheduler storage could not be allocated.

CapacityExceeded

CapacityExceeded
All request slots are retained, including uncollected completions.

ByteBudgetExceeded

ByteBudgetExceeded
Requested destinations exceed the retained byte budget.

InvalidHandle

InvalidHandle
Handle is foreign, stale, or already collected.

IdentityExhausted

IdentityExhausted
Unique scheduler or request identities cannot be represented.

ThreadCreationFailed

ThreadCreationFailed
Native synchronization or a worker could not start; started workers are joined.

Unsupported

Unsupported
Blocking workers are unavailable on this target (including browser builds).

InsideRead

InsideRead
Shutdown was called from this reader's provider/worker and would join itself.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/async.hpp

RequestState

enum class RequestState : uint8
Observable request progression; cancellation is an intent rather than a state.

Related types: uint8

Queued

Queued
Accepted, waiting for a worker.

Submitted

Submitted
Worker owns the destination and may be reading.

Completing

Completing
Read is terminal; completion awaits host collection.

Completed

Completed
Host has collected the terminal completion and may reuse the destination.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/async.hpp

ReadDisposition

enum class ReadDisposition : uint8
Terminal disposition; Read retains the underlying ReadResult, including errors.

Related types: uint8

Read

Read
ReadAt finished, or cancellation arrived after it became terminal.

Cancelled

Cancelled
Cancellation won before terminal publication; discard any touched destination.

DeadlineExpired

DeadlineExpired
The latest-start deadline passed before I/O began; destination is untouched.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/async.hpp

Status

enum class Status : uint8
Explicit outcome of a filesystem operation; native failures retain their error number.

Related types: uint8

Ok

Ok
Operation completed successfully, including reads at EOF.

InvalidArgument

InvalidArgument
Invalid path, closed owner, invalid offset or native path component.

NotFound

NotFound
A requested native path component does not exist.

AccessDenied

AccessDenied
Native access was denied or a child symlink was refused.

NotRegularFile

NotRegularFile
The opened object is not a readable regular file.

OutOfMemory

OutOfMemory
Opening or cloning could not allocate its private owner.

IoError

IoError
A native operation failed for another reason.

Changed

Changed
Size or modification time no longer matches the captured revision.

Unsupported

Unsupported
Native I/O or a requested pack format/feature is unavailable.

CorruptData

CorruptData
A pack index, payload or integrity check is malformed.

LimitExceeded

LimitExceeded
Configured storage/index/decoded resource admission was exceeded.

Conflict

Conflict
A publication precondition or cooperative writer lock was refused.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/filesystem.hpp

Root

enum class Root : uint8
Host-selected read namespace. Write authorization remains a separate policy.

Related types: uint8

Assets

Assets
Published asset bytes.

Project

Project
Authoring project bytes.

Cache

Cache
Reconstructible cached bytes.

User

User
User-owned persistent bytes.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/namespace.hpp

SyncPolicy

enum class SyncPolicy : uint8
Requested native sync operations; acknowledgments are not power-loss guarantees.

Related types: uint8

PublishOnly

PublishOnly
Atomically publish without requesting sync.

File

File
Sync temporary file before publication.

FileAndDirectory

FileAndDirectory
Sync file before publication and parent directory afterward.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/persistence.hpp

WriteCondition

enum class WriteCondition : uint8
Publication admission checked under a cooperative, nonblocking parent-directory lock. Uncooperative writers may race the final check and rename; metadata is not a digest.

Related types: uint8

Any

Any
Permit an absent or regular-file destination.

Missing

Missing
Require the destination to be absent at both checks.

MatchingStamp

MatchingStamp
Require the regular destination to match Expected at both checks.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/persistence.hpp

WatchHintKind

enum class WatchHintKind : uint8
Hint purpose; every hint requires explicit host revalidation before revision selection.

Related types: uint8

Changed

Changed
Debounced metadata difference, creation or disappearance.

RescanRequired

RescanRequired
Queue overflow or observation error invalidated incremental hints.

RescanEntry

RescanEntry
One current registered path observed during a bounded rescan.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/watch.hpp

Constants and variables

MAX_PATH_BYTES

constexpr usize ludus::foundation::filesystem::MAX_PATH_BYTES = 1024
Maximum encoded length of a validated relative path, excluding its terminator.

Related types: usize

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/filesystem.hpp

MAX_ROOT_BYTES

constexpr usize ludus::foundation::filesystem::MAX_ROOT_BYTES = 4096
Maximum encoded length of a trusted native root, excluding its terminator.

Related types: usize

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/filesystem.hpp

MAX_MEMORY_FILES

constexpr usize ludus::foundation::filesystem::MAX_MEMORY_FILES = 65536
Maximum memory-provider entry count, bounding index construction and lookup storage.

Related types: usize

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/namespace.hpp

MAX_MOUNTS

constexpr usize ludus::foundation::filesystem::MAX_MOUNTS = 256
Maximum mount count, bounding snapshot construction and resolution work.

Related types: usize

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/namespace.hpp

MAX_PACK_BLOCK_BYTES

constexpr uint32 ludus::foundation::filesystem::MAX_PACK_BLOCK_BYTES = 65536
Maximum decoded bytes in one independent version-1 pack block.

Related types: uint32

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/pack.hpp

Functions

AsyncNow

uint64 ludus::foundation::filesystem::AsyncNow() noexcept
Monotonic nanoseconds for scheduler deadlines and measurement; unrelated to wall-clock time.

Related types: uint64

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/async.hpp

ValidPath

bool ludus::foundation::filesystem::ValidPath(std::string_view path) noexcept
Validates a bounded UTF-8 relative path without normalization or case folding. Rejects absolute paths, empty/dot components, NUL, backslash, colon and control bytes.

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/filesystem.hpp

CreateMemoryProvider

Result ludus::foundation::filesystem::CreateMemoryProvider(std::span< const MemoryEntry > entries, ProviderHandle &output) noexcept
Copies and sorts entries into an immutable provider available on every target. Duplicate/invalid keys or unrepresentable allocation sizes return InvalidArgument; allocation failure returns OutOfMemory. Failure preserves output. No portable host case/Unicode collision guarantee is implied; pack publishing is F3's boundary.

Related types: ProviderHandle · MemoryEntry · Result

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/namespace.hpp

CreateDirectoryProvider

Result ludus::foundation::filesystem::CreateDirectoryProvider(std::string_view nativeRoot, ProviderHandle &output) noexcept
Pins a trusted native root using Directory's containment and platform contract. Failure preserves output; Unsupported on targets without native file I/O.

Related types: ProviderHandle · Result

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/namespace.hpp

CreatePackProvider

Result ludus::foundation::filesystem::CreatePackProvider(const ProviderHandle &storage, std::string_view relativePath, const PackLimits &limits, ProviderHandle &output) noexcept
Opens and validates a version-1 pack through an existing byte provider on any target. Retains the opened archive revision; failure preserves output. Path/source/limit misuse returns InvalidArgument; malformed index/ranges/checksums return CorruptData; unsupported version/flags/codecs return Unsupported; budget admission returns LimitExceeded. Native storage faults retain their status and native code; allocation returns OutOfMemory. All index paths, lengths, block ownership and nonoverlapping storage ranges are checked before publication. Payload checksums and bounded LZ4 decode run on each touched block before copying verified bytes. Payload faults do not trigger overlay fallback. Reads allocate nothing; each opened file owns at most twice the advertised block size in scratch bytes and serializes its concurrent reads. A Changed result has zero valid bytes; other faults report only earlier verified progress. Empty/EOF reads check the underlying archive revision. Index metadata is captured at mount; immutable publication remains required because size/mtime and CRC32 cannot establish authenticity or defeat hostile metadata-preserving mutation. See docs/architecture/filesystem.md.

Related types: ProviderHandle · PackLimits · Result

Declared in modules/foundation/filesystem/include/ludus/foundation/filesystem/pack.hpp