EntropyEngine::Core::Concurrency

EntropyEngine::Core::Concurrency

Classes

	Name
class	EntropyEngine::Core::Concurrency::WorkService Thread pool service that executes work contracts from multiple groups.
struct	EntropyEngine::Core::Concurrency::WorkResultContext Extended result context for yieldable work functions with timing support.
struct	EntropyEngine::Core::Concurrency::WorkGraphStats Real-time metrics for your executing workflow - watch the action unfold.
struct	EntropyEngine::Core::Concurrency::WorkGraphNode The atomic unit of work in a dependency graph with self-managing execution timing.
struct	EntropyEngine::Core::Concurrency::WorkGraphEvent The mother of all WorkGraph events - timestamp and source.
struct	EntropyEngine::Core::Concurrency::WorkGraphConfig Configuration parameters and feature toggles for WorkGraph instances.
class	EntropyEngine::Core::Concurrency::WorkGraph Orchestrates complex parallel workflows with automatic dependency management.
struct	EntropyEngine::Core::Concurrency::WorkContractTag
class	EntropyEngine::Core::Concurrency::WorkContractHandle EntropyObject-stamped handle for work contracts.
class	EntropyEngine::Core::Concurrency::WorkContractGroup Factory and manager for work contracts with lock-free scheduling.
class	EntropyEngine::Core::Concurrency::SpinningDirectScheduler CPU-intensive scheduler that eliminates sleep/wake overhead for benchmarking.
class	EntropyEngine::Core::Concurrency::SignalTreeBase Abstract base class for SignalTree to enable polymorphic usage.
class	EntropyEngine::Core::Concurrency::SignalTree A lock-free binary tree for signal selection and management.
class	EntropyEngine::Core::Concurrency::RoundRobinScheduler Fair round-robin scheduler providing uniform work distribution.
class	EntropyEngine::Core::Concurrency::RandomScheduler The chaos monkey of schedulers - picks groups at random.
class	EntropyEngine::Core::Concurrency::NodeStateManager Centralized state management for WorkGraph nodes.
struct	EntropyEngine::Core::Concurrency::NodeStateChangedEvent The workhorse event - tracks every state transition in your workflow.
class	EntropyEngine::Core::Concurrency::NodeScheduler Manages graph node scheduling and overflow handling for work execution.
struct	EntropyEngine::Core::Concurrency::NodeScheduledEvent Node has been submitted to the thread pool.
struct	EntropyEngine::Core::Concurrency::NodeReadyEvent All dependencies satisfied - this node is ready to rock!
struct	EntropyEngine::Core::Concurrency::NodeFailedEvent Uh oh - a node threw an exception.
struct	EntropyEngine::Core::Concurrency::NodeExecutingEvent A thread has started running this node’s work.
struct	EntropyEngine::Core::Concurrency::NodeDeferredEvent Work queue is full - this node has to wait.
struct	EntropyEngine::Core::Concurrency::NodeCompletedEvent Success!
struct	EntropyEngine::Core::Concurrency::NodeCancelledEvent A node was cancelled due to upstream failure.
struct	EntropyEngine::Core::Concurrency::NodeAddedEvent Fired when a new task joins your workflow.
class	EntropyEngine::Core::Concurrency::IWorkScheduler Abstract interface for work scheduling strategies in the WorkService.
class	EntropyEngine::Core::Concurrency::IConcurrencyProvider Interface for concurrency providers that execute work from WorkContractGroups.
struct	EntropyEngine::Core::Concurrency::GraphStatsEvent Periodic health check - current graph statistics.
struct	EntropyEngine::Core::Concurrency::GraphExecutionStartedEvent The starting gun - workflow execution begins!
struct	EntropyEngine::Core::Concurrency::GraphExecutionCompletedEvent The finish line - all nodes have reached terminal states.
class	EntropyEngine::Core::Concurrency::DirectScheduler The “just give me work!” scheduler - absolute minimum overhead.
struct	EntropyEngine::Core::Concurrency::DependencyResolvedEvent One step closer - a parent completed and child’s dependency count dropped.
struct	EntropyEngine::Core::Concurrency::DependencyAddedEvent Fired when you wire two nodes together.
class	EntropyEngine::Core::Concurrency::AdaptiveRankingScheduler Adaptive scheduler that learns from workload patterns to optimize distribution.

Types

	Name
using std::function< WorkResultContext()>	YieldableWorkFunction Work that can yield/suspend with timing.
enum class uint8_t	WorkResult { YieldUntil = 2, Yield = 1, Complete = 0} Return value from yieldable work functions.
using std::function< void()>	WorkFunction The actual work to execute (legacy).
using std::function< std::unique_ptr< IWorkScheduler >(const IWorkScheduler::Config &)>	SchedulerFactory Factory function type for creating schedulers.
enum class	ScheduleResult { Scheduled, NotScheduled, Invalid, Executing, AlreadyScheduled} Result of schedule/unschedule operations.
enum class uint8_t	NodeState { Yielded = 7, Scheduled = 2, Ready = 1, Pending = 0, Failed = 5, Executing = 3, Completed = 4, Cancelled = 6} The lifecycle states of a task node - from birth to completion.
using Graph::AcyclicNodeHandle< WorkGraphNode >	NodeHandle How you reference nodes.
using std::function< void(NodeHandle)>	NodeCallback Callbacks that receive nodes.
enum class uint8_t	ExecutionType { MainThread = 1, AnyThread = 0} Defines where a work contract can be executed.
enum class uint8_t	ExecutionResult { Success = 0, Skipped = 3, Failed = 1, Cancelled = 2} The final verdict on how a node’s execution went.
enum class uint32_t	ContractState { Scheduled = 2, Free = 0, Executing = 3, Completed = 4, Allocated = 1} States that a work contract can be in during its lifecycle.
using std::function< void(ExecutionResult)>	CompletionCallback Notified when work completes.

Functions

	Name
size_t	roundUpToPowerOf2(size_t n)
const char *	nodeStateToString(NodeState state) Human-readable state names for logging and debugging.
bool	isValidTransition(NodeState from, NodeState to) Validates state transitions - prevents impossible state changes.
bool	isTerminalState(NodeState state) Check if a node has reached the end of its journey.

Types Documentation

using YieldableWorkFunction

using EntropyEngine::Core::Concurrency::YieldableWorkFunction = std::function<WorkResultContext()>;

Work that can yield/suspend with timing.

enum WorkResult

Enumerator	Value	Description
YieldUntil	2	Suspend and reschedule at specific time (use WorkResultContext).
Yield	1	Suspend and reschedule immediately for later execution.
Complete	0	Work is done, proceed to completion.

Return value from yieldable work functions.

Work functions can now return a status to control their execution flow. Complete means the work is done, Yield means suspend and reschedule later. This enables coroutine-like behavior without actual C++ coroutines.

auto node = graph.addYieldableNode([]() -> WorkResultContext {
    if (!dataReady()) {
        return WorkResultContext::yield();  // Try again later
    }
    processData();
    return WorkResultContext::complete();
});

using WorkFunction

using EntropyEngine::Core::Concurrency::WorkFunction = std::function<void()>;

The actual work to execute (legacy).

using SchedulerFactory

using EntropyEngine::Core::Concurrency::SchedulerFactory = std::function<std::unique_ptr<IWorkScheduler>(const IWorkScheduler::Config&)>;

Factory function type for creating schedulers.

Enables registration of schedulers by name and dynamic switching between implementations. The factory receives configuration parameters and returns a new scheduler instance.

std::map<std::string, SchedulerFactory> schedulers = {
    {"round-robin", [](auto& cfg) { return std::make_unique<RoundRobinScheduler>(cfg); }},
    {"adaptive", [](auto& cfg) { return std::make_unique<AdaptiveRankingScheduler>(cfg); }},
    {"random", [](auto& cfg) { return std::make_unique<RandomScheduler>(cfg); }}
};

// Create scheduler by name
auto scheduler = schedulers["adaptive"](config);

enum ScheduleResult

Enumerator	Value	Description
Scheduled		Contract is now scheduled (successful schedule operation).
NotScheduled		Contract is not scheduled (successful unschedule operation).
Invalid		Invalid handle provided.
Executing		Cannot modify - currently executing.
AlreadyScheduled		Contract was already scheduled (schedule operation failed).

Result of schedule/unschedule operations.

enum NodeState

Enumerator	Value	Description
Yielded	7	Suspended execution, will be rescheduled.
Scheduled	2	Submitted to WorkContractGroup, in queue.
Ready	1	All dependencies satisfied, waiting for thread.
Pending	0	Waiting for dependencies - can’t run yet.
Failed	5	Exception thrown - children will be cancelled.
Executing	3	Currently running on a worker thread.
Completed	4	Finished successfully - triggered children.
Cancelled	6	Skipped due to parent failure - never ran.

The lifecycle states of a task node - from birth to completion.

Every node in your WorkGraph moves through these states as it progresses from “waiting for parents” to “done”. The transitions are carefully controlled to ensure thread safety and proper dependency management.

State flow:

• Pending → Ready (when all dependencies complete)
• Ready → Scheduled (when submitted to thread pool)
• Scheduled → Executing (when thread picks it up)
• Executing → Completed/Failed/Yielded (based on return value or exceptions)
• Yielded → Ready (for rescheduling)
• Any state → Cancelled (if parent fails)

Terminal states (Completed, Failed, Cancelled) are final - no further transitions.

using NodeHandle

using EntropyEngine::Core::Concurrency::NodeHandle = Graph::AcyclicNodeHandle<WorkGraphNode>;

How you reference nodes.

using NodeCallback

using EntropyEngine::Core::Concurrency::NodeCallback = std::function<void(NodeHandle)>;

Callbacks that receive nodes.

enum ExecutionType

Enumerator	Value	Description
MainThread	1	Must run on the main/UI thread.
AnyThread	0	Runs on any worker thread from the pool.

Defines where a work contract can be executed.

Choose AnyThread for CPU-bound work that can run anywhere. Choose MainThread for UI updates, OpenGL calls, or other operations that must run on a specific thread. Dependencies work seamlessly across execution types.

// Background processing
auto compute = graph.addNode([]{ heavyComputation(); },
                             "compute", nullptr, ExecutionType::AnyThread);

// UI update that depends on computation
auto update = graph.addNode([]{ updateProgressBar(); },
                            "update-ui", nullptr, ExecutionType::MainThread);

graph.addDependency(compute, update);  // UI waits for computation

enum ExecutionResult

Enumerator	Value	Description
Success	0	Work function completed without throwing.
Skipped	3	Skipped for other reasons (reserved for future use).
Failed	1	Work function threw an exception.
Cancelled	2	Never ran due to parent failure.

The final verdict on how a node’s execution went.

Simple enum to categorize the outcome of node execution. Used in callbacks and events to communicate results without needing to check multiple states.

enum ContractState

Enumerator	Value	Description
Scheduled	2	Contract is scheduled and ready for execution.
Free	0	Contract slot is available for allocation.
Executing	3	Contract is currently being executed.
Completed	4	Contract has completed execution.
Allocated	1	Contract has been allocated but not scheduled.

States that a work contract can be in during its lifecycle.

using CompletionCallback

using EntropyEngine::Core::Concurrency::CompletionCallback = std::function<void(ExecutionResult)>;

Notified when work completes.

Functions Documentation

function roundUpToPowerOf2

static size_t roundUpToPowerOf2(
    size_t n
)

function nodeStateToString

inline const char * nodeStateToString(
    NodeState state
)

Human-readable state names for logging and debugging.

Parameters:

• state The state to stringify

Return: Static string representation (no allocation)

LOG_DEBUG("Node {} transitioned to {}",
          node.getData()->name,
          nodeStateToString(node.getData()->state));

function isValidTransition

inline bool isValidTransition(
    NodeState from,
    NodeState to
)

Validates state transitions - prevents impossible state changes.

Parameters:

• from Current state
• to Desired new state

Return: true if the transition is legal

Valid transitions:

• Pending → Ready or Cancelled
• Ready → Scheduled or Cancelled
• Scheduled → Executing or Cancelled
• Executing → Completed, Failed, or Yielded
• Yielded → Ready (for rescheduling)
• Terminal states → Nothing

function isTerminalState

inline bool isTerminalState(
    NodeState state
)

Check if a node has reached the end of its journey.

Parameters:

• state The state to check

Return: true if this is a final state

Terminal states (Completed, Failed, Cancelled) are final. Yielded is NOT terminal - the node will resume execution.

---

Updated on 2026-01-26 at 17:14:35 -0500