ludus::foundation::filesystem::AsyncReader¶

Class

Host-owned bounded offset-read scheduler. Native blocking pool on Linux/macOS/Windows; browser initialization returns Unsupported. Dedicated workers may block; never call Submit/Poll/Shutdown from an audio callback or render critical section. Initialize/destruction are owner-thread operations exclusive of all other calls. Submit, Cancel, GetState, Poll, PollTrace and Metrics may run concurrently while alive. Shutdown is serialized with itself and destruction, and may overlap those other calls. The host keeps each accepted destination alive and exclusively writable until Poll returns its completion, or until destruction has drained all I/O. No completion callbacks. Stop with Shutdown, collect every completion, then destroy. Destruction also drains, but deliberately abandons any completion the host chose not to collect.

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

#include <ludus/foundation/filesystem/async.hpp>

class ludus::foundation::filesystem::AsyncReader final

Methods¶

AsyncReader¶

ludus::foundation::filesystem::AsyncReader::AsyncReader() noexcept=default

Creates an uninitialized scheduler.

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

~AsyncReader¶

ludus::foundation::filesystem::AsyncReader::~AsyncReader() noexcept

Stops admission, cancels queued reads, joins workers, and releases abandoned records.

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

AsyncReader¶

ludus::foundation::filesystem::AsyncReader::AsyncReader(const AsyncReader &)=delete

Scheduler identity and native synchronization are immovable.

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

operator=¶

AsyncReader & ludus::foundation::filesystem::AsyncReader::operator=(const AsyncReader &)=delete

Scheduler identity and native synchronization are immovable.

Related types: AsyncReader

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

AsyncReader¶

ludus::foundation::filesystem::AsyncReader::AsyncReader(AsyncReader &&)=delete

Scheduler identity and native synchronization are immovable.

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

operator=¶

AsyncReader & ludus::foundation::filesystem::AsyncReader::operator=(AsyncReader &&)=delete

Scheduler identity and native synchronization are immovable.

Related types: AsyncReader

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

Initialize¶

AsyncStatus ludus::foundation::filesystem::AsyncReader::Initialize(AsyncConfig config={}) noexcept

Allocates fixed storage and starts all workers; failure leaves this uninitialized.

Related types: AsyncStatus · AsyncConfig

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

Submit¶

AsyncStatus ludus::foundation::filesystem::AsyncReader::Submit(const VirtualFile &file, uint64 offset, std::span< uint8 > destination, RequestHandle &handle, ReadOptions options={}) noexcept

Retains file without opening/cloning descriptors. Charges full destination bytes until collection, including EOF and empty reads. Offset must be <= file.Size(); no overlapping live destinations are permitted (host responsibility). Rejection preserves handle and destination. TracePath, when provided, must be valid even if tracing is disabled.

Related types: VirtualFile · uint64 · uint8 · AsyncStatus · ReadOptions · RequestHandle

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

Cancel¶

AsyncStatus ludus::foundation::filesystem::AsyncReader::Cancel(RequestHandle handle) noexcept

Records first cancellation intent. Queued reads skip I/O; running reads drain and report Cancelled with zero valid bytes. A Completing request keeps its already published result. Success never permits immediate buffer reuse; stale/foreign handles return InvalidHandle.

Related types: AsyncStatus · RequestHandle

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

GetState¶

AsyncStatus ludus::foundation::filesystem::AsyncReader::GetState(RequestHandle handle, RequestState &output) const noexcept

Inspects a live request; failure preserves output. Collected handles are invalid.

Related types: RequestState · AsyncStatus · RequestHandle

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

Poll¶

bool ludus::foundation::filesystem::AsyncReader::Poll(ReadCompletion &output) noexcept

Collects one terminal request in terminal-publication order, releases its budget/file, and returns true. False preserves output. No payload reads, completion callbacks or scheduler allocations; file release may close the final provider revision, so collect outside critical engine sections.

Related types: ReadCompletion

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

PollTrace¶

bool ludus::foundation::filesystem::AsyncReader::PollTrace(ReadTrace &output) noexcept

Removes the oldest trace without allocation; false preserves output.

Related types: ReadTrace

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

Metrics¶

AsyncStatus ludus::foundation::filesystem::AsyncReader::Metrics(AsyncMetrics &output) const noexcept

Copies counters; failure preserves output. No external tracing/logging occurs.

Related types: AsyncStatus · AsyncMetrics

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

Shutdown¶

AsyncStatus ludus::foundation::filesystem::AsyncReader::Shutdown() noexcept

Permanently stops admission, cancels queued requests and joins all submitted reads. Does not deliver or discard completions: Poll remains usable. Repeated calls succeed. Can block for an uninterruptible provider read; providers must eventually return. Returns InsideRead without stopping admission if invoked by this reader's provider on its I/O worker. Never destroy a reader from a provider it is currently reading.

Related types: AsyncStatus

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