Gondwana.EngineDispatcher Class Reference

Provides thread-safe dispatching of actions to the engine's background thread. This dispatcher allows external code to safely post work items that should execute on the engine's dedicated update loop thread, ensuring thread-safe access to engine state. More...

Inheritance diagram for Gondwana.EngineDispatcher:

Public Member Functions
void	BindToCurrentThread ()
	Binds this dispatcher to the current thread, establishing it as the engine thread. This method should be called once during engine startup from the thread that will run the engine's main update loop.
void	Post (Action action)
	Posts an action to be executed on the engine thread. If the current thread is already the engine thread, the action is executed inline immediately; otherwise, it is queued for execution during the next call to Drain.
void	Drain ()
	Executes all queued actions that have been posted to this dispatcher since the last call to Drain. This method should be called regularly by the engine's main update loop to process pending work items.

Properties
bool	IsOnEngineThread [get]
	Gets a value indicating whether the current thread is the engine thread to which this dispatcher is bound.

Detailed Description

Provides thread-safe dispatching of actions to the engine's background thread. This dispatcher allows external code to safely post work items that should execute on the engine's dedicated update loop thread, ensuring thread-safe access to engine state.

The EngineDispatcher uses a concurrent queue to collect actions posted from any thread and drains them on the engine thread during each engine cycle. Actions posted from the engine thread itself can optionally be executed inline for improved performance.

This dispatcher is bound to a specific thread using BindToCurrentThread during engine startup and is drained by the engine's main loop via Drain.

Member Function Documentation

BindToCurrentThread()

void Gondwana.EngineDispatcher.BindToCurrentThread

(

)

Binds this dispatcher to the current thread, establishing it as the engine thread. This method should be called once during engine startup from the thread that will run the engine's main update loop.

After binding, the dispatcher uses the current thread's managed thread ID to determine whether subsequent calls to Post are being made from the engine thread, allowing for optimizations such as inline execution. This method is typically called by the engine's main loop initialization code.

Implements Gondwana.IEngineDispatcher.

Drain()

void Gondwana.EngineDispatcher.Drain

(

)

Executes all queued actions that have been posted to this dispatcher since the last call to Drain. This method should be called regularly by the engine's main update loop to process pending work items.

This method dequeues and executes each action in FIFO order until the queue is empty. It should only be called from the engine thread to maintain thread safety guarantees.

If an action throws an exception, it will propagate to the caller and may interrupt processing of remaining queued actions. The engine's main loop should handle such exceptions appropriately to maintain stability.

Actions posted during the execution of Drain (including those posted by actions being drained) will not be executed until the next call to Drain.

Implements Gondwana.IEngineDispatcher.

Post()

void Gondwana.EngineDispatcher.Post

(

Action

action

)

Posts an action to be executed on the engine thread. If the current thread is already the engine thread, the action is executed inline immediately; otherwise, it is queued for execution during the next call to Drain.

Parameters

action

The action to execute on the engine thread. If null, this method returns immediately without taking any action.

This method is thread-safe and can be called from any thread. Actions are executed in the order they are posted when multiple threads are posting concurrently, though the exact ordering may vary due to thread scheduling.

The inline execution optimization for engine thread calls eliminates queueing overhead and guarantees immediate execution, which is useful for performance-critical operations that are already running on the correct thread.

Implements Gondwana.IEngineDispatcher.

Property Documentation

IsOnEngineThread

bool Gondwana.EngineDispatcher.IsOnEngineThread

get

Gets a value indicating whether the current thread is the engine thread to which this dispatcher is bound.

true if the current thread's managed thread ID matches the engine thread ID set by BindToCurrentThread; otherwise, false.

This property is used internally to optimize action execution by running actions inline when already on the engine thread, avoiding unnecessary queueing overhead. It can also be used by external code to determine if thread-safe access to engine state is required.

Implements Gondwana.IEngineDispatcher.