Class Dispatcher

Namespace

Avalonia.Threading

Assembly

Avalonia.Base.dll

Provides services for managing work items on a thread.

public class Dispatcher : IDispatcher

Inheritance

object

Dispatcher

Implements

IDispatcher

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

In Avalonia, there is usually only a single Dispatcher in the application - the one for the UI thread, retrieved via the UIThread property.

Properties

SupportsRunLoops

public bool SupportsRunLoops { get; }

Property Value

bool

UIThread

public static Dispatcher UIThread { get; }

Property Value

Dispatcher

Methods

AwaitWithPriority(Task, DispatcherPriority)

Returns a task awaitable that would invoke continuation on specified dispatcher priority

public DispatcherPriorityAwaitable AwaitWithPriority(Task task, DispatcherPriority priority)

Parameters

task Task

priority DispatcherPriority

Returns

DispatcherPriorityAwaitable

AwaitWithPriority<T>(Task<T>, DispatcherPriority)

Returns a task awaitable that would invoke continuation on specified dispatcher priority

public DispatcherPriorityAwaitable<T> AwaitWithPriority<T>(Task<T> task, DispatcherPriority priority)

Parameters

task Task<T>

priority DispatcherPriority

Returns

DispatcherPriorityAwaitable<T>

Type Parameters

T

BeginInvokeShutdown(DispatcherPriority)

Begins the process of shutting down the dispatcher.

public void BeginInvokeShutdown(DispatcherPriority priority)

Parameters

priority DispatcherPriority

CheckAccess()

Checks that the current thread is the UI thread.

public bool CheckAccess()

Returns

bool

DisableProcessing()

Disable the event processing of the dispatcher.

public Dispatcher.DispatcherProcessingDisabled DisableProcessing()

Returns

Dispatcher.DispatcherProcessingDisabled

Remarks

This is an advanced method intended to eliminate the chance of unrelated reentrancy. The effect of disabling processing is:

1. CLR locks will not pump messages internally.
2. No one is allowed to push a frame.
3. No message processing is permitted.

ExitAllFrames()

Requests that all nested frames exit.

public void ExitAllFrames()

HasJobsWithPriority(DispatcherPriority)

public bool HasJobsWithPriority(DispatcherPriority priority)

Parameters

priority DispatcherPriority

Returns

bool

Invoke(Action)

Executes the specified Action synchronously on the thread that the Dispatcher was created on.

public void Invoke(Action callback)

Parameters

callback Action

An Action delegate to invoke through the dispatcher.

Remarks

Note that the default priority is DispatcherPriority.Send.

Invoke(Action, DispatcherPriority)

Executes the specified Action synchronously on the thread that the Dispatcher was created on.

public void Invoke(Action callback, DispatcherPriority priority)

Parameters

callback Action

An Action delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the Dispatcher.

Invoke(Action, DispatcherPriority, CancellationToken)

Executes the specified Action synchronously on the thread that the Dispatcher was created on.

public void Invoke(Action callback, DispatcherPriority priority, CancellationToken cancellationToken)

Parameters

callback Action

An Action delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the Dispatcher.

cancellationToken CancellationToken

A cancellation token that can be used to cancel the operation. If the operation has not started, it will be aborted when the cancellation token is canceled. If the operation has started, the operation can cooperate with the cancellation request.

Invoke(Action, DispatcherPriority, CancellationToken, TimeSpan)

Executes the specified Action synchronously on the thread that the Dispatcher was created on.

public void Invoke(Action callback, DispatcherPriority priority, CancellationToken cancellationToken, TimeSpan timeout)

Parameters

callback Action

An Action delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the Dispatcher.

cancellationToken CancellationToken

A cancellation token that can be used to cancel the operation. If the operation has not started, it will be aborted when the cancellation token is canceled. If the operation has started, the operation can cooperate with the cancellation request.

timeout TimeSpan

The minimum amount of time to wait for the operation to start. Once the operation has started, it will complete before this method returns.

InvokeAsync(Action)

Executes the specified Action asynchronously on the thread that the Dispatcher was created on.

public DispatcherOperation InvokeAsync(Action callback)

Parameters

callback Action

An Action delegate to invoke through the dispatcher.

Returns

DispatcherOperation

An operation representing the queued delegate to be invoked.

Remarks

Note that the default priority is DispatcherPriority.Default.

InvokeAsync(Action, DispatcherPriority)

Executes the specified Action asynchronously on the thread that the Dispatcher was created on.

public DispatcherOperation InvokeAsync(Action callback, DispatcherPriority priority)

Parameters

callback Action

An Action delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the Dispatcher.

Returns

DispatcherOperation

An operation representing the queued delegate to be invoked.

InvokeAsync(Action, DispatcherPriority, CancellationToken)

Executes the specified Action asynchronously on the thread that the Dispatcher was created on.

public DispatcherOperation InvokeAsync(Action callback, DispatcherPriority priority, CancellationToken cancellationToken)

Parameters

callback Action

An Action delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the Dispatcher.

cancellationToken CancellationToken

A cancellation token that can be used to cancel the operation. If the operation has not started, it will be aborted when the cancellation token is canceled. If the operation has started, the operation can cooperate with the cancellation request.

Returns

DispatcherOperation

An operation representing the queued delegate to be invoked.

InvokeAsync(Func<Task>)

Executes the specified Func<Task> asynchronously on the thread that the Dispatcher was created on

public Task InvokeAsync(Func<Task> callback)

Parameters

callback Func<Task>

A Func<Task> delegate to invoke through the dispatcher.

Returns

Task

An task that completes after the task returned from callback finishes.

InvokeAsync(Func<Task>, DispatcherPriority)

Executes the specified Func<Task> asynchronously on the thread that the Dispatcher was created on

public Task InvokeAsync(Func<Task> callback, DispatcherPriority priority)

Parameters

callback Func<Task>

A Func<Task> delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the Dispatcher.

Returns

Task

An task that completes after the task returned from callback finishes

InvokeAsync<TResult>(Func<Task<TResult>>)

Executes the specified Func<Task<TResult>> asynchronously on the thread that the Dispatcher was created on

public Task<TResult> InvokeAsync<TResult>(Func<Task<TResult>> action)

Parameters

action Func<Task<TResult>>

A Func<Task<TResult>> delegate to invoke through the dispatcher.

Returns

Task<TResult>

An task that completes after the task returned from callback finishes

Type Parameters

TResult

InvokeAsync<TResult>(Func<Task<TResult>>, DispatcherPriority)

Executes the specified Func<Task<TResult>> asynchronously on the thread that the Dispatcher was created on

public Task<TResult> InvokeAsync<TResult>(Func<Task<TResult>> action, DispatcherPriority priority)

Parameters

action Func<Task<TResult>>

A Func<Task<TResult>> delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the Dispatcher.

Returns

Task<TResult>

An task that completes after the task returned from callback finishes

Type Parameters

TResult

InvokeAsync<TResult>(Func<TResult>)

Executes the specified Func<TResult> asynchronously on the thread that the Dispatcher was created on.

public DispatcherOperation<TResult> InvokeAsync<TResult>(Func<TResult> callback)

Parameters

callback Func<TResult>

A Func<TResult> delegate to invoke through the dispatcher.

Returns

DispatcherOperation<TResult>

An operation representing the queued delegate to be invoked.

Type Parameters

TResult

The type of the callback return value.

Remarks

Note that the default priority is DispatcherPriority.Default.

InvokeAsync<TResult>(Func<TResult>, DispatcherPriority)

Executes the specified Func<TResult> asynchronously on the thread that the Dispatcher was created on.

public DispatcherOperation<TResult> InvokeAsync<TResult>(Func<TResult> callback, DispatcherPriority priority)

Parameters

callback Func<TResult>

A Func<TResult> delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the Dispatcher.

Returns

DispatcherOperation<TResult>

An operation representing the queued delegate to be invoked.

Type Parameters

TResult

InvokeAsync<TResult>(Func<TResult>, DispatcherPriority, CancellationToken)

Executes the specified Func<TResult> asynchronously on the thread that the Dispatcher was created on.

public DispatcherOperation<TResult> InvokeAsync<TResult>(Func<TResult> callback, DispatcherPriority priority, CancellationToken cancellationToken)

Parameters

callback Func<TResult>

A Func<TResult> delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the Dispatcher.

cancellationToken CancellationToken

A cancellation token that can be used to cancel the operation. If the operation has not started, it will be aborted when the cancellation token is canceled. If the operation has started, the operation can cooperate with the cancellation request.

Returns

DispatcherOperation<TResult>

An operation representing the queued delegate to be invoked.

Type Parameters

TResult

The type of the callback return value.

InvokeShutdown()

Initiates the shutdown process of the Dispatcher synchronously.

public void InvokeShutdown()

Invoke<TResult>(Func<TResult>)

Executes the specified Func<TResult> synchronously on the thread that the Dispatcher was created on.

public TResult Invoke<TResult>(Func<TResult> callback)

Parameters

callback Func<TResult>

A Func<TResult> delegate to invoke through the dispatcher.

Returns

TResult

The return value from the delegate being invoked.

Type Parameters

TResult

The type of the callback return value.

Remarks

Note that the default priority is DispatcherPriority.Send.

Invoke<TResult>(Func<TResult>, DispatcherPriority)

Executes the specified Func<TResult> synchronously on the thread that the Dispatcher was created on.

public TResult Invoke<TResult>(Func<TResult> callback, DispatcherPriority priority)

Parameters

callback Func<TResult>

A Func<TResult> delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the Dispatcher.

Returns

TResult

The return value from the delegate being invoked.

Type Parameters

TResult

The type of the callback return value.

Invoke<TResult>(Func<TResult>, DispatcherPriority, CancellationToken)

Executes the specified Func<TResult> synchronously on the thread that the Dispatcher was created on.

public TResult Invoke<TResult>(Func<TResult> callback, DispatcherPriority priority, CancellationToken cancellationToken)

Parameters

callback Func<TResult>

A Func<TResult> delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the Dispatcher.

cancellationToken CancellationToken

A cancellation token that can be used to cancel the operation. If the operation has not started, it will be aborted when the cancellation token is canceled. If the operation has started, the operation can cooperate with the cancellation request.

Returns

TResult

The return value from the delegate being invoked.

Type Parameters

TResult

The type of the callback return value.

Invoke<TResult>(Func<TResult>, DispatcherPriority, CancellationToken, TimeSpan)

Executes the specified Func<TResult> synchronously on the thread that the Dispatcher was created on.

public TResult Invoke<TResult>(Func<TResult> callback, DispatcherPriority priority, CancellationToken cancellationToken, TimeSpan timeout)

Parameters

callback Func<TResult>

A Func<TResult> delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the Dispatcher.

cancellationToken CancellationToken

A cancellation token that can be used to cancel the operation. If the operation has not started, it will be aborted when the cancellation token is canceled. If the operation has started, the operation can cooperate with the cancellation request.

timeout TimeSpan

The minimum amount of time to wait for the operation to start. Once the operation has started, it will complete before this method returns.

Returns

TResult

The return value from the delegate being invoked.

Type Parameters

TResult

The type of the callback return value.

MainLoop(CancellationToken)

Runs the dispatcher's main loop.

public void MainLoop(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A cancellation token used to exit the main loop.

Post(Action, DispatcherPriority)

Posts an action that will be invoked on the dispatcher thread.

public void Post(Action action, DispatcherPriority priority = default)

Parameters

action Action

The method.

priority DispatcherPriority

The priority with which to invoke the method.

Post(SendOrPostCallback, object?, DispatcherPriority)

Posts an action that will be invoked on the dispatcher thread.

public void Post(SendOrPostCallback action, object? arg, DispatcherPriority priority = default)

Parameters

action SendOrPostCallback

The method.

arg object

The argument of method to call.

priority DispatcherPriority

The priority with which to invoke the method.

PushFrame(DispatcherFrame)

Push an execution frame.

public void PushFrame(DispatcherFrame frame)

Parameters

frame DispatcherFrame

The frame for the dispatcher to process.

RunJobs(DispatcherPriority?)

Force-runs all dispatcher operations ignoring any pending OS events, use with caution

public void RunJobs(DispatcherPriority? priority = null)

Parameters

priority DispatcherPriority?

VerifyAccess()

Checks that the current thread is the UI thread and throws if not.

public void VerifyAccess()

Exceptions

InvalidOperationException

The current thread is not the UI thread.

Events

ShutdownFinished

Raised when the dispatcher is shut down.

public event EventHandler? ShutdownFinished

Event Type

EventHandler

ShutdownStarted

Raised when the dispatcher is shutting down.

public event EventHandler? ShutdownStarted

Event Type

EventHandler

UnhandledException

Occurs when a thread exception is thrown and uncaught during execution of a delegate by way of Invoke(Action) or InvokeAsync(Action).

public event DispatcherUnhandledExceptionEventHandler? UnhandledException

Event Type

DispatcherUnhandledExceptionEventHandler

Remarks

This event is raised when an exception that was thrown during execution of a delegate by way of Invoke(Action) or InvokeAsync(Action) is uncaught. A handler can mark the exception as handled, which will prevent the internal exception handler from being called. Event handlers for this event must be written with care to avoid creating secondary exceptions and to catch any that occur. It is recommended to avoid allocating memory or doing any resource intensive operations in the handler.

UnhandledExceptionFilter

Occurs when a thread exception is thrown and uncaught during execution of a delegate by way of Invoke(Action) or InvokeAsync(Action) when in the filter stage.

public event DispatcherUnhandledExceptionFilterEventHandler? UnhandledExceptionFilter

Event Type

DispatcherUnhandledExceptionFilterEventHandler

Remarks

This event is raised during the filter stage for an exception that is raised during execution of a delegate by way of Invoke(Action) or InvokeAsync(Action) and is uncaught. The call stack is not unwound at this point (first-chance exception). Event handlers for this event must be written with care to avoid creating secondary exceptions and to catch any that occur. It is recommended to avoid allocating memory or doing any resource intensive operations in the handler. The UnhandledExceptionFilter event provides a means to not raise the UnhandledException event. The UnhandledExceptionFilter event is raised first, and If RequestCatch is set to false, the UnhandledException event will not be raised.