ludus::audio::content::Loader¶

Class

Acquire sound/music revisions on a Linux/macOS background worker. Exactly one control owner calls all methods; at most one acquisition is pending. Background work owns inputs/results, and Poll installs a whole revision.

Note

The referenced AudioSystem must outlive this loader. Destroy the loader on its control owner; destruction joins pending acquisition before reclaiming it.

Declared in modules/audio/content/include/ludus/audio/content/loader.h

#include <ludus/audio/content/loader.h>

class ludus::audio::content::Loader final

Methods¶

Loader¶

explicit ludus::audio::content::Loader::Loader(AudioSystem &audio) noexcept

Bind to an AudioSystem without acquiring any content.

Related types: AudioSystem

Declared in modules/audio/content/include/ludus/audio/content/loader.h

~Loader¶

ludus::audio::content::Loader::~Loader() noexcept

Blocking cold shutdown: cancel/join acquisition and release revisions.

Declared in modules/audio/content/include/ludus/audio/content/loader.h

Loader¶

ludus::audio::content::Loader::Loader(const Loader &)=delete

Loader ownership cannot be copied.

Declared in modules/audio/content/include/ludus/audio/content/loader.h

operator=¶

Loader & ludus::audio::content::Loader::operator=(const Loader &)=delete

Loader ownership cannot be assigned.

Related types: Loader

Declared in modules/audio/content/include/ludus/audio/content/loader.h

Begin¶

ContentStatus ludus::audio::content::Loader::Begin(std::string_view root, std::string_view id, const Sound *draft=nullptr, const Music *musicDraft=nullptr, const ludus::content::Catalog *snapshot=nullptr) noexcept

Begin cold file acquisition and decoding without blocking the control owner.

Parameter	Description
`root`	Native content root copied into the pending job.
`id`	Catalog resource identifier copied into the pending job.
`draft`	Optional sound draft copied and validated before worker launch.
`musicDraft`	Optional music draft; mutually exclusive with draft.
`snapshot`	Optional immutable version-1 catalog copied before launch; worker lookup uses this snapshot instead of reopening catalog.json. Source files remain loose-file revisions; this does not freeze their path contents.

Returns

Pending after launch or while an acquisition is already pending; Invalid for invalid input/uninitialized audio; OutOfMemory for allocation failure; Limit if loader identity space is exhausted; IoError for worker creation failure. Other platforms are Unsupported.

Related types: ludus::content::Catalog · ContentStatus · Music · Sound

Declared in modules/audio/content/include/ludus/audio/content/loader.h

Poll¶

ContentStatus ludus::audio::content::Loader::Poll(const Routing &routing, Lease &output, Diagnostic &diagnostic) noexcept

Install completed acquisition on the control owner after routing checks.

Parameter	Description
`routing`	Bus/group names borrowed during this call.
`output`	Receives the new lease on Ok; preserved on failure/Pending.
`diagnostic`	Receives completed acquisition/validation diagnostics.

Returns

Pending while the worker runs; Ok on installation; NotFound with no pending job; Cancelled after the audio session changes or stops; otherwise the acquisition/validation status. Cancelled also follows RequestCancel. Completed work is detached and reclaimed without waiting for thread exit; detach failure returns IoError and retains the job for blocking Cancel.

Note

Never joins or waits for file/decode work. Installation and candidate cleanup still perform bounded cold work; this is not an audio-callback API. While cancellation drains, Begin remains Pending and cannot replace inputs.

Related types: ContentStatus · Lease · Routing · Diagnostic

Declared in modules/audio/content/include/ludus/audio/content/loader.h

RequestCancel¶

void ludus::audio::content::Loader::RequestCancel() noexcept

Signal cancellation without joining, releasing inputs or installing results. Idempotent; no pending acquisition is a no-op. Call Poll until Cancelled (or an earlier terminal error) to drain ownership, or use blocking Cancel. Already-issued leases remain valid. Call only on the control owner.

Declared in modules/audio/content/include/ludus/audio/content/loader.h

Cancel¶

void ludus::audio::content::Loader::Cancel() noexcept

Cancel and join pending acquisition on the control owner before freeing its inputs. May block until current file/decode work returns; no pending acquisition is a no-op. Existing revision leases remain valid.

Declared in modules/audio/content/include/ludus/audio/content/loader.h

GetSound¶

ContentStatus ludus::audio::content::Loader::GetSound(Lease lease, Sound &definition, app::EventDescriptor &descriptor) const noexcept

Copy a sound definition and resolved descriptor on Ok; preserve outputs otherwise. Reject foreign/stale/released or wrong-kind leases as Invalid; unavailable installed clips return Cancelled. Descriptor borrows clip identity; retain the lease until playback has been submitted.

Related types: ContentStatus · app::EventDescriptor · Lease · Sound

Declared in modules/audio/content/include/ludus/audio/content/loader.h

GetMusic¶

ContentStatus ludus::audio::content::Loader::GetMusic(Lease lease, Music &definition) const noexcept

Copy a music definition on Ok; preserve output for invalid/foreign/stale or wrong-kind leases. The source descriptor remains owned by the lease.

Related types: ContentStatus · Lease · Music

Declared in modules/audio/content/include/ludus/audio/content/loader.h

PlayMusic¶

Status ludus::audio::content::Loader::PlayMusic(Lease lease, VoiceHandle &voice) noexcept

Start an independent stream from a valid music lease. Playback retains its own source reader and survives lease release; voice is assigned on success. Stream preparation is cold work. Invalid leases return InvalidHandle.

Related types: Status · VoiceHandle · Lease

Declared in modules/audio/content/include/ludus/audio/content/loader.h

Release¶

ContentStatus ludus::audio::content::Loader::Release(Lease lease) noexcept

Release one owned revision, including after its audio session ends. Foreign/stale/already-released tokens return Invalid without mutation. Last shared-clip release requests AudioSystem retirement; active playback frees only through AudioSystem's acknowledgments. Control owner only.

Related types: ContentStatus · Lease

Declared in modules/audio/content/include/ludus/audio/content/loader.h

Service¶

void ludus::audio::content::Loader::Service() noexcept

Service AudioSystem and request retirement of terminal music instances. Does not poll or join acquisition. Call on the control owner.

Declared in modules/audio/content/include/ludus/audio/content/loader.h