ludus::foundation::threading

Ludus Wiki · API overview · Browse API

Namespace

Declared in modules/content/scene_cook/include/ludus/content/scene_cook/best_effort_import.h

Related declarations

• ludus::foundation::threading::JobGraph
• ludus::foundation::threading::JobGraphConfig
• ludus::foundation::threading::JobHandle
• ludus::foundation::threading::JobLabel
• ludus::foundation::threading::JobSnapshot
• ludus::foundation::threading::JobSystem
• ludus::foundation::threading::JobSystemConfig
• ludus::foundation::threading::JobSystemHooks
• ludus::foundation::threading::JobTraceEvent
• ludus::foundation::threading::WorkerQueue

Enumerations

JobStatus

enum class JobStatus : uint8

Result of a graph or system operation. Every failure leaves outputs in a documented state.

Related types: uint8

Ok

Ok

The operation succeeded.

InvalidArgument

InvalidArgument

Invalid configuration or callback, or Wait/Cancel with no submitted graph.

NotInitialized

NotInitialized

The graph or system has not been successfully initialized.

AlreadyInitialized

AlreadyInitialized

Initialize was called again; the existing storage is unchanged.

OutOfMemory

OutOfMemory

Fixed storage could not be allocated; nothing was retained.

CapacityExceeded

CapacityExceeded

The graph's MaxJobs or MaxDependencies reservation is full.

InvalidHandle

InvalidHandle

The handle belongs to another graph or to a generation invalidated by Reset.

DuplicateDependency

DuplicateDependency

The same prerequisite edge was already declared.

CycleDetected

CycleDetected

A self edge was declared, or Seal found a dependency cycle.

NotSealed

NotSealed

Submit requires a graph that Seal accepted.

Busy

Busy

A graph is already in flight, or this graph is sealed/submitted and cannot change.

InsideJob

InsideJob

Called from a job callback of any system; it would wait for or destroy itself.

Unsupported

Unsupported

The request is unavailable on this target; browser builds require zero workers.

ThreadCreationFailed

ThreadCreationFailed

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

IdentityExhausted

IdentityExhausted

Graph IDs or the graph's reset generation cannot be represented without wrapping.

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

JobOutcome

enum class JobOutcome : uint8

Execution state of one job, and the aggregate outcome reported by JobSystem::Wait.

Related types: uint8

Pending

Pending

Not yet executed or resolved.

Running

Running

The callback is executing on a worker or a helping caller.

Succeeded

Succeeded

The callback returned Succeeded.

Failed

Failed

The callback returned Failed or an invalid outcome.

Cancelled

Cancelled

The callback returned Cancelled, or JobSystem::Cancel skipped the job before it started.

Blocked

Blocked

A prerequisite did not succeed, so the callback was never called.

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

JobTraceKind

enum class JobTraceKind : uint8

Scheduler transition reported to JobSystemHooks::TraceOrNull.

For one traced submission, the owner reports Submitted before any job can start and WaitEntered/WaitReturned from Wait. The thread executing a job reports Started, then, after the callback returns Succeeded, one Signalled per outgoing dependency edge, then Finished. Jobs skipped as Blocked or Cancelled are not reported.

Related types: uint8

Submitted

Submitted

Submit admitted the graph; its ReadyDepth roots become ready after this report returns.

Started

Started

The job's callback is about to run on the reporting thread.

Signalled

Signalled

The succeeded job is about to satisfy EdgeIndex of DependentIndex.

Finished

Finished

The callback returned Outcome; the outcome is published after this report returns.

WaitEntered

WaitEntered

The owner entered Wait for this submission.

WaitReturned

WaitReturned

Wait released the submission with Outcome and is about to return.

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

WorkerQueueStatus

enum class WorkerQueueStatus : uint8

Admission/lifecycle result for a dedicated worker queue.

Related types: uint8

Ready

Ready

Operation succeeded.

InvalidArgument

InvalidArgument

A required callback is null.

InvalidState

InvalidState

Not initialized, already initialized, or called from a callback.

CapacityExceeded

CapacityExceeded

All task slots await execution or completion collection.

OutOfMemory

OutOfMemory

Queue storage could not be allocated.

Unavailable

Unavailable

Native synchronization/thread startup failed; browser is unsupported.

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

Aliases

JobFunction

using ludus::foundation::threading::JobFunction = JobOutcome (*)(void* context) noexcept

Job callback. Runs to completion on any worker or a helping caller, with no thread affinity.

Only Succeeded, Failed and Cancelled are valid return values; any other value is recorded as Failed. A callback must not block on other jobs or synchronous I/O, and must not call JobSystem Initialize, Submit, Wait or Shutdown (they return InsideJob). The code must stay loaded until the owning Wait returns.

Related types: JobOutcome

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

JobWorkerFunction

using ludus::foundation::threading::JobWorkerFunction = void (*)(void* contextOrNull, uint32 workerIndex) noexcept

Worker setup or teardown hook. Runs once on the worker thread it names.

Parameter	Description
contextOrNull	JobSystemHooks::ContextOrNull.
workerIndex	Zero-based worker index, below JobSystemConfig::WorkerCount.

Related types: uint32

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

JobTraceFunction

using ludus::foundation::threading::JobTraceFunction = void (*)(void* contextOrNull, const JobTraceEvent& event) noexcept

Receives one trace event. Called concurrently from workers and the owner.

Related types: JobTraceEvent

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

JobTraceFilterFunction

using ludus::foundation::threading::JobTraceFilterFunction = bool (*)(void* contextOrNull) noexcept

Asked once per Submit, on the calling thread, whether to trace that submission.

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

WorkerQueueFunction

using ludus::foundation::threading::WorkerQueueFunction = void (*)(void* contextOrNull) noexcept

A nonthrowing task or completion function; context is borrowed until completion returns.

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

Constants and variables

CALLING_THREAD_WORKER_INDEX

constexpr uint32 ludus::foundation::threading::CALLING_THREAD_WORKER_INDEX = static_cast<uint32>(-1)

WorkerIndex of a trace event reported on the thread that called Submit or Wait.

Related types: uint32

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

NO_JOB_EDGE

constexpr uint32 ludus::foundation::threading::NO_JOB_EDGE = static_cast<uint32>(-1)

EdgeIndex of a Started trace event for a job without prerequisites.

Related types: uint32

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

MAX_WORKER_QUEUE_TASKS

constexpr usize ludus::foundation::threading::MAX_WORKER_QUEUE_TASKS = 64

Maximum accepted tasks, including running and uncollected completions.

Related types: usize

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

Functions

RegisterJobLabelSite

uint32 ludus::foundation::threading::RegisterJobLabelSite(const profiling::ZoneDescriptor &descriptor) noexcept

Records a job label's profiler site so exported traces show its name.

Used by LUDUS_JOB_LABEL; call at most once per descriptor.

Parameter	Description
descriptor	Site metadata with static storage duration.

Returns

The descriptor's site ID, so the call can initialize a function-local static.

Related types: uint32 · profiling::ZoneDescriptor

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

MakeProfilerJobHooks

JobSystemHooks ludus::foundation::threading::MakeProfilerJobHooks(const char *workerNamePrefixOrNull=nullptr) noexcept

Returns hooks that connect a JobSystem to the profiler.

Pass the result as JobSystemConfig::Hooks. Each worker registers with profiling::RegisterThreadForTrace as "<prefix> <index>" during Initialize and unregisters, publishing its partial trace chunk, during Shutdown. Each Submit is traced only while a capture is active, and is then traced completely. Builds with profiling compiled out return empty hooks, so the scheduler does no tracing work.

Parameter	Description
workerNamePrefixOrNull	Static NUL-terminated thread-name prefix; null selects "Job worker". Names are truncated to the profiler's thread-name capacity.

Returns

Hooks whose context is the prefix pointer; it must outlive the system.

Related types: JobSystemHooks

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