Gondwana.IUiDispatcher Interface Reference

Defines a contract for dispatching actions to the UI thread in a thread-safe manner. Implementations of this interface provide mechanisms for posting or sending work items from any thread to be executed on the application's main UI thread, ensuring thread-safe access to UI components and controls. More...

Inheritance diagram for Gondwana.IUiDispatcher:

Public Member Functions
void	Post (Action action)
	Asynchronously posts an action to be executed on the UI thread. This method queues the action and returns immediately without waiting for execution to complete.
void	Send (Action action)
	Synchronously sends an action to be executed on the UI thread, blocking the calling thread until the action completes. Use with caution to avoid deadlocks.

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

Detailed Description

Defines a contract for dispatching actions to the UI thread in a thread-safe manner. Implementations of this interface provide mechanisms for posting or sending work items from any thread to be executed on the application's main UI thread, ensuring thread-safe access to UI components and controls.

The UI dispatcher pattern is essential for cross-thread communication in applications with a dedicated UI thread. It allows background threads (such as the engine's update loop) to safely schedule UI updates without causing threading violations.

Most operations should use Post (asynchronous) rather than Send (synchronous) to avoid potential deadlocks and improve responsiveness.

Member Function Documentation

Post()

void Gondwana.IUiDispatcher.Post

(

Action

action

)

Asynchronously posts an action to be executed on the UI thread. This method queues the action and returns immediately without waiting for execution to complete.

Parameters

action

The action to execute on the UI thread. The action will be queued and executed asynchronously on the UI thread's message loop.

This is the preferred method for dispatching UI operations from background threads. It is non-blocking and avoids potential deadlocks that can occur with synchronous dispatch.

The action is queued to the UI thread's message pump and will be executed when the UI thread processes it. There is no guarantee about the exact timing of execution, and the calling thread continues immediately without waiting.

This method is thread-safe and can be called from any thread.

Implemented in Gondwana.UiDispatcher.

Send()

void Gondwana.IUiDispatcher.Send

(

Action

action

)

Synchronously sends an action to be executed on the UI thread, blocking the calling thread until the action completes. Use with caution to avoid deadlocks.

Parameters

action

The action to execute on the UI thread. The calling thread will block until this action completes execution on the UI thread.

This method provides synchronous dispatch to the UI thread, blocking the caller until the action has been executed and completed. This can be useful when the calling code needs to ensure UI updates have finished before proceeding, or when a return value from the UI operation is required.

Warning: Using Send can lead to deadlocks if the UI thread is waiting for the calling thread, or if there are circular dependencies. It should be avoided on web platforms and in single-threaded environments where blocking the caller would also block the UI thread.

In most cases, prefer using Post for asynchronous, non-blocking dispatch.

This method is thread-safe and can be called from any thread, but exercise caution to avoid deadlock scenarios.

Implemented in Gondwana.UiDispatcher.

Property Documentation

IsOnUIThread

bool Gondwana.IUiDispatcher.IsOnUIThread

get

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

true if the current thread is the UI thread; otherwise, false.

This property can be used to optimize action execution by running UI updates inline when already on the UI thread, avoiding unnecessary marshalling overhead. It also allows code to determine if cross-thread marshalling is required before accessing UI components.

Implemented in Gondwana.UiDispatcher.