Class SimulationDispatcher

Defined in File simulation-dispatcher.h

Nested Relationships

Nested Types

Class SimulationDispatcher::Submission

Class Documentation

class SimulationDispatcher

Declaration: final

Transfers owned requests to the runtime’s simulation thread.

Only the simulation owner may access its mutable game state. Queue owned requests; borrowed captures must outlive completion or owner-thread cancellation. Never wait on a simulation future from the simulation owner. Delivery precedes input transfer at each actual update boundary in either runtime mode. Shutdown destroys pending captures on the owner before resource cleanup; futures report broken_promise. Submission handles remain safe after dispatcher destruction.

Public Functions

SimulationDispatcher() = default

Create a closed request queue.

GameRuntime opens and binds its single execution session.

See also

Detailed guide

~SimulationDispatcher()

Invalidate submission state and cancel unexecuted requests.

Runtime normally performs owner-thread cancellation before teardown; do not destroy while operations use this object. Retained Submission values remain safe and reject later work.

See also

Detailed guide

SimulationDispatcher(const SimulationDispatcher&) = delete

Copy construction is disabled; retain a copyable Submission endpoint instead.

See also

Detailed guide

SimulationDispatcher &operator=(const SimulationDispatcher&) = delete

Copy assignment is disabled; queue/session ownership cannot be replaced.

See also

Detailed guide

inline Submission submission() const

Declaration: [[nodiscard]]

Retain a copyable producer endpoint independent of dispatcher lifetime.

See also

Detailed guide

Returns:: Endpoint owning shared queue state, without a borrowed game/context pointer. Obtaining it does not open the queue; concurrent submission requires a live endpoint.

template<typename Work> inline std::future<std::invoke_result_t<std::decay_t<Work>&>> submit(Work &&work)

Declaration: [[nodiscard]]

Queue an owned callable for deferred simulation-owner execution.

See also

Detailed guide

Template Parameters:: Work – Callable invocable without arguments; move-only captures and void/value/reference results are supported.
Parameters:: work – Callable forwarded into owned queue storage; borrowed captures/results remain the caller’s lifetime responsibility.
Throws:: CE::Exceptions::failed_operation – If no active accepting runtime queue exists. Allocation/callable construction failures can propagate before acceptance. Always queues, even from the owner thread. Do not wait on this future from the execution owner. Delivery precedes input transfer at an actual update boundary in either execution mode; capture game state only with its simulation-owner lifetime protected.
Returns:: Future holding the invocation result or its exception; cancellation before entry produces broken_promise.

bool has_pending() const

Declaration: [[nodiscard]]

Observe whether requests remain in the shared queue.

See also

Detailed guide

Returns:: Synchronized queue snapshot; false does not establish closure or completion of an already detached batch.

CE::Diagnostics::DispatchStats diagnostics() const

Declaration: [[nodiscard]]

Copy synchronized queue/counter observations.

See also

Detailed guide

Returns:: Best-effort stats, including detached-batch running counts. Callback exceptions remain owned by their futures; this is not a completion barrier.