EntropyEngine::Core::Concurrency::NodeStateManager

Centralized state management for WorkGraph nodes. More…

#include <NodeStateManager.h>

Public Functions

	Name
bool	transitionState(const NodeHandle & node, NodeState from, NodeState to) Attempt to transition a node to a new state.
void	resetStats() Reset all statistics.
void	registerNode(const NodeHandle & node, NodeState initialState =NodeState::Pending) Register a node with initial state.
bool	isTerminal(const NodeHandle & node) const Check if a node is in a terminal state.
bool	hasActiveNodes() const Check if any nodes are in non-terminal states.
void	getStats(WorkGraphStats & stats) const Get statistics about current state distribution.
const char *	getStateName(NodeState state) Get human-readable name for a state.
NodeState	getState(const NodeHandle & node) const Get current state of a node.
void	getNodesInState(NodeState state, const std::vector< NodeHandle > & allNodes, std::vector< NodeHandle > & output) const Get all nodes in a specific state.
size_t	getMemoryUsage() const Get memory usage estimate.
void	forceState(const NodeHandle & node, NodeState to) Force a state transition without validation.
bool	canTransition(NodeState from, NodeState to) Check if a state transition is valid.
size_t	batchTransition(const std::vector< std::tuple< NodeHandle, NodeState, NodeState > > & updates) Batch update for multiple nodes.
	NodeStateManager(const WorkGraph * graph, Core::EventBus * eventBus =nullptr) Construct state manager.

Detailed Description

class EntropyEngine::Core::Concurrency::NodeStateManager;

Centralized state management for WorkGraph nodes.

This component is responsible for:

Validating state transitions
Publishing state change events
Tracking state statistics
Providing thread-safe state queries

Design goals:

Minimal memory footprint (suitable for thousands of instances)
Lock-free reads where possible
Optional event publishing (only if EventBus provided)

Public Functions Documentation

function transitionState

bool transitionState(
    const NodeHandle & node,
    NodeState from,
    NodeState to
)

Attempt to transition a node to a new state.

Parameters:

node The node to transition
from Expected current state (for CAS operation)
to Target state

Return: true if transition succeeded, false if current state didn’t match ‘from’

This is the primary method for all state changes. It validates the transition, updates the state atomically, and publishes events if configured.

function resetStats

inline void resetStats()

Reset all statistics.

function registerNode

void registerNode(
    const NodeHandle & node,
    NodeState initialState =NodeState::Pending
)

Parameters:

node The node to register
initialState Initial state (default: Pending)

function isTerminal

inline bool isTerminal(
    const NodeHandle & node
) const

Check if a node is in a terminal state.

Parameters:

node The node to check

Return: true if node is in Completed, Failed, or Cancelled state

function hasActiveNodes

inline bool hasActiveNodes() const

Check if any nodes are in non-terminal states.

Return: true if there are pending, ready, scheduled, or executing nodes

function getStats

inline void getStats(
    WorkGraphStats & stats
) const

Get statistics about current state distribution.

Parameters:

stats Output parameter for statistics

function getStateName

static inline const char * getStateName(
    NodeState state
)

Get human-readable name for a state.

Parameters:

state The state to convert

Return: String representation of the state

function getState

NodeState getState(
    const NodeHandle & node
) const

Get current state of a node.

Parameters:

node The node to query

Return: Current state, or Pending if node is invalid

function getNodesInState

void getNodesInState(
    NodeState state,
    const std::vector< NodeHandle > & allNodes,
    std::vector< NodeHandle > & output
) const

Get all nodes in a specific state.

Parameters:

state The state to query
allNodes List of all nodes to check
output Vector to fill with matching nodes

function getMemoryUsage

inline size_t getMemoryUsage() const

Get memory usage estimate.

Return: Approximate memory usage in bytes

function forceState

void forceState(
    const NodeHandle & node,
    NodeState to
)

Force a state transition without validation.

Parameters:

node The node to transition
to Target state

Use sparingly - only for error recovery or initialization

function canTransition

static inline bool canTransition(
    NodeState from,
    NodeState to
)

Check if a state transition is valid.

Parameters:

from Source state
to Target state

Return: true if transition is allowed

function batchTransition

size_t batchTransition(
    const std::vector< std::tuple< NodeHandle, NodeState, NodeState > > & updates
)

Batch update for multiple nodes.

Parameters:

updates Vector of (node, from, to) tuples

Return: Number of successful transitions

function NodeStateManager

inline explicit NodeStateManager(
    const WorkGraph * graph,
    Core::EventBus * eventBus =nullptr
)

Construct state manager.

Parameters:

graph The owning WorkGraph (for event context)
eventBus Optional event bus for publishing state changes

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