ludus::foundation::threading::JobSystem

Ludus Wiki · API overview · Browse API

Class

Explicitly budgeted pool that executes one sealed graph at a time.

Initialize, Submit, Wait, Shutdown and destruction are serialized by the application owner. Cancel and Snapshot may run concurrently with execution and with the owner's Wait, including from job callbacks, while the system stays initialized. Systems are independent; there is no hidden global pool. Platform, RHI and audio callback work does not belong in this pool.

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

#include <ludus/foundation/threading/jobs.hpp>

class ludus::foundation::threading::JobSystem final

Methods

JobSystem

ludus::foundation::threading::JobSystem::JobSystem() noexcept=default

Creates an uninitialized system with no threads.

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

~JobSystem

ludus::foundation::threading::JobSystem::~JobSystem() noexcept

Equivalent to Shutdown.

Warning

Destroying a system from any job callback is a fatal contract violation.

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

JobSystem

ludus::foundation::threading::JobSystem::JobSystem(const JobSystem &)=delete

Not copyable: workers reference the system state.

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

operator=

JobSystem & ludus::foundation::threading::JobSystem::operator=(const JobSystem &)=delete

Not copy-assignable.

Related types: JobSystem

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

JobSystem

ludus::foundation::threading::JobSystem::JobSystem(JobSystem &&)=delete

Not movable: workers reference the system state.

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

operator=

JobSystem & ludus::foundation::threading::JobSystem::operator=(JobSystem &&)=delete

Not move-assignable.

Related types: JobSystem

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

Initialize

JobStatus ludus::foundation::threading::JobSystem::Initialize(JobSystemConfig config={}) noexcept

Allocates scheduler state and starts every worker once.

When JobSystemHooks::WorkerStartOrNull is set, returns Ok only after it has run on every worker.

Parameter	Description
config	Worker budget and hooks; see JobSystemConfig.

Returns

Ok; InsideJob; AlreadyInitialized; InvalidArgument when WorkerCount exceeds 64; Unsupported for nonzero workers on browser builds; OutOfMemory; or ThreadCreationFailed, after joining any worker already started. On failure the system stays uninitialized and Initialize may be retried.

Related types: JobStatus · JobSystemConfig

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

Submit

JobStatus ludus::foundation::threading::JobSystem::Submit(JobGraph &inoutGraph) noexcept

Admits a sealed graph and publishes its jobs without prerequisites.

The graph stays reserved, and cannot be edited, reset or submitted elsewhere, until Wait returns. With zero workers every job runs on the caller before Submit returns; Wait is still required to release the graph.

Parameter	Description
inoutGraph	Graph whose per-job execution state is reset for this run.

Returns

Ok; InsideJob; NotInitialized for an uninitialized system or graph; Busy when this system already has a graph in flight or another system holds the graph; or NotSealed. There is no queue of pending graphs.

Related types: JobGraph · JobStatus

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

Wait

JobStatus ludus::foundation::threading::JobSystem::Wait(JobOutcome &outOutcome, bool shouldHelp=true) noexcept

Waits until every job of the in-flight graph is resolved, then releases it.

Acts as a lifetime fence: on return all callback writes are visible and no callback still references graph contexts. With shouldHelp, the caller also executes ready jobs; pass false when thread identity, thread-local state or responsiveness make that inappropriate.

Parameter	Description
outOutcome	Failed if any job failed, otherwise Cancelled if any job was cancelled, otherwise Succeeded. Blocked jobs follow from one of the former. Pending when the call fails.
shouldHelp	Whether the calling thread executes ready jobs while it waits.

Returns

Ok; InsideJob; NotInitialized; or InvalidArgument when no graph is submitted.

Related types: JobStatus · JobOutcome

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

Cancel

JobStatus ludus::foundation::threading::JobSystem::Cancel() noexcept

Requests that jobs which have not started are skipped and reported Cancelled.

Running callbacks finish and keep their actual outcomes; side effects are not rolled back. Once requested, every job that has not started reports Cancelled, including one that a failed prerequisite would otherwise report Blocked. Cancelling after the last job resolved does not change the graph outcome.

Returns

Ok; NotInitialized; or InvalidArgument when no graph is submitted.

Related types: JobStatus

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

Snapshot

JobStatus ludus::foundation::threading::JobSystem::Snapshot(JobSnapshot &outSnapshot) const noexcept

Counts the in-flight graph's job outcomes. O(jobs); do not poll per task.

Parameter	Description
outSnapshot	Receives the counts; all zero when no graph is submitted or on failure.

Returns

Ok or NotInitialized.

Related types: JobStatus · JobSnapshot

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

GetWorkerCount

uint32 ludus::foundation::threading::JobSystem::GetWorkerCount() const noexcept

Reports the worker budget accepted by Initialize, excluding a helping caller.

Lets a consumer that receives a borrowed system size its graphs to the owner's budget without a second, possibly disagreeing configuration value. Called by the owner, or by a consumer the owner has lent the system to, never concurrently with Initialize or Shutdown.

Returns

JobSystemConfig::WorkerCount of a successful Initialize; zero while uninitialized (including after Shutdown) and for the serial executor.

Related types: uint32

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp

Shutdown

JobStatus ludus::foundation::threading::JobSystem::Shutdown() noexcept

Drains accepted work, stops and joins every worker, and frees scheduler state.

Returns

Ok, including when not initialized; or InsideJob, leaving the system running.

Related types: JobStatus

Declared in modules/foundation/threading/include/ludus/foundation/threading/jobs.hpp