ludus::foundation::threading::JobGraph

Ludus Wiki · API overview · Browse API

Class

Bounded dependency graph, built, sealed and reset on one owner thread.

Add jobs, declare edges with DependsOn, then Seal. A sealed graph can be submitted repeatedly; each job keeps the context pointer given to Add, so update the data it points to between Wait and the next Submit. Reset invalidates every handle and permits rebuilding. Contexts and the data they reference must outlive the Wait that releases a submission.

Build/reset and destruction are serialized by the owner and must not race a submission. GetOutcome may run concurrently with execution.

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

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

class ludus::foundation::threading::JobGraph final

Methods

JobGraph

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

Creates an uninitialized graph that owns no storage.

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

~JobGraph

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

Drains an in-flight submission through its system, then frees storage.

Warning

Destroying a submitted graph from any job callback is a fatal contract violation.

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

JobGraph

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

Not copyable: graph storage and identity are not transferable.

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

operator=

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

Not copy-assignable.

Related types: JobGraph

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

JobGraph

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

Not movable: graph storage and identity are not transferable.

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

operator=

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

Not move-assignable.

Related types: JobGraph

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

Initialize

JobStatus ludus::foundation::threading::JobGraph::Initialize(JobGraphConfig config={}) noexcept

Reserves all job, edge and ready-queue storage and assigns a graph ID.

Parameter	Description
config	Fixed capacities; MaxJobs must be nonzero.

Returns

Ok; AlreadyInitialized; InvalidArgument for out-of-range capacities; OutOfMemory; or IdentityExhausted. On failure the graph stays uninitialized.

Related types: JobStatus · JobGraphConfig

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

Add

JobStatus ludus::foundation::threading::JobGraph::Add(JobFunction function, void *contextOrNull, JobHandle &outHandle, JobLabel label={}) noexcept

Appends a job to an unsealed graph.

Parameter	Description
function	Callback; must not be null.
contextOrNull	Value passed to every invocation of the callback. Not owned.
outHandle	Receives the new job's handle, or a default (invalid) handle on failure.
label	Optional identity reported to trace hooks; stored by value without allocation. The name is borrowed (see JobLabel::NameOrNull).

Returns

Ok; NotInitialized; Busy when sealed or submitted; InvalidArgument; or CapacityExceeded.

Related types: JobFunction · JobStatus · JobHandle · JobLabel

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

DependsOn

JobStatus ludus::foundation::threading::JobGraph::DependsOn(JobHandle dependent, JobHandle prerequisite) noexcept

Declares that dependent runs only after prerequisite succeeds.

The edge orders execution and publishes the prerequisite's writes to the dependent. If the prerequisite fails or is cancelled, the dependent and its descendants become Blocked without being called.

Returns

Ok; NotInitialized; Busy when sealed or submitted; InvalidHandle; CycleDetected for a self edge; DuplicateDependency; or CapacityExceeded.

Related types: JobStatus · JobHandle

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

Seal

JobStatus ludus::foundation::threading::JobGraph::Seal() noexcept

Validates the graph as acyclic in O(jobs + edges) without allocation and freezes it.

Returns

Ok; NotInitialized; Busy while submitted; or CycleDetected, in which case the graph stays unsealed and must be Reset to remove the cycle.

Related types: JobStatus

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

Reset

JobStatus ludus::foundation::threading::JobGraph::Reset() noexcept

Removes every job and edge and advances the generation, invalidating all handles.

Returns

Ok; NotInitialized; Busy until Wait releases a submission; or IdentityExhausted when the generation cannot advance without wrapping.

Related types: JobStatus

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

GetOutcome

JobStatus ludus::foundation::threading::JobGraph::GetOutcome(JobHandle handle, JobOutcome &outOutcome) const noexcept

Reads one job's published outcome with acquire ordering.

A Succeeded result makes that job's writes visible to the caller. Safe to call concurrently with execution, but never concurrently with Reset, rebuild or destruction.

Parameter	Description
handle	Job handle returned by Add in the current generation.
outOutcome	Receives the outcome; Pending on failure.

Returns

Ok; NotInitialized; or InvalidHandle for a foreign or stale handle.

Related types: JobStatus · JobOutcome · JobHandle

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