Method InvokeAsync

Namespace

Terminal.Gui.App

Assembly

Terminal.Gui.dll

InvokeAsync(IApplication, Action, CancellationToken)

Runs action on the UI thread and completes after it returns.

public static Task InvokeAsync(this IApplication app, Action action, CancellationToken cancellationToken = default)

Parameters

app IApplication

The application that owns the UI thread.

action Action

The action to run.

cancellationToken CancellationToken

Cancels the dispatch if execution has not started.

Returns

Task

A task that reports completion, cancellation, or the action's exception.

Remarks

The action runs immediately when called on the UI thread during a running session. Otherwise it is queued for the next main-loop iteration. Exceptions from the action fault the task and do not enter the main-loop error handler, except that an OperationCanceledException carrying the canceled caller token cancels the task. Pending dispatches are canceled when the application is disposed or its final session ends. Queued dispatches are independent of user timers; removing or stopping timers does not discard them. Dispatches queued after initialization but before the first session wait for that session to start. After the final session ends or disposal begins, a canceled await may resume on a thread-pool thread. To observe action failures, await or otherwise inspect the returned task.

Exceptions

NotInitializedException

The application is not initialized or is shutting down.

NotSupportedException

The application does not support awaitable dispatch.

InvokeAsync(IApplication, Action<IApplication>, CancellationToken)

Runs action on the UI thread and completes after it returns.

public static Task InvokeAsync(this IApplication app, Action<IApplication> action, CancellationToken cancellationToken = default)

Parameters

app IApplication

The application that owns the UI thread.

action Action<IApplication>

The action to run with the application instance.

cancellationToken CancellationToken

Cancels the dispatch if execution has not started.

Returns

Task

A task that reports completion, cancellation, or the action's exception.

Remarks

The action runs immediately when called on the UI thread during a running session. Otherwise it is queued for the next main-loop iteration. Exceptions from the action fault the task and do not enter the main-loop error handler, except that an OperationCanceledException carrying the canceled caller token cancels the task. Pending dispatches are canceled when the application is disposed or its final session ends. Queued dispatches are independent of user timers; removing or stopping timers does not discard them. Dispatches queued after initialization but before the first session wait for that session to start. After the final session ends or disposal begins, a canceled await may resume on a thread-pool thread. To observe action failures, await or otherwise inspect the returned task.

InvokeAsync(IApplication, SessionToken, Action, CancellationToken)

Runs action while owner is active.

public static Task InvokeAsync(this IApplication app, SessionToken owner, Action action, CancellationToken cancellationToken = default)

Parameters

app IApplication

The application that owns the UI thread.

owner SessionToken

The session that owns the action's referenced views.

action Action

The action to run.

cancellationToken CancellationToken

Cancels the dispatch if execution has not started.

Returns

Task

A task that reports completion, cancellation, or the action's exception.

Remarks

The owner may be an outer session while an inner modal is running. Ending the owner cancels its pending dispatches; ending another session does not. An owner that has already ended yields a canceled task. An owner that has not started running yet, such as one reported by SessionBegun, runs the action on a later main-loop iteration after it starts. After the final session ends or disposal begins, a canceled await may resume on a thread-pool thread.

Exceptions

NotInitializedException

The application is not initialized or is shutting down.

NotSupportedException

The application does not support awaitable dispatch.

InvokeAsync(IApplication, SessionToken, Action<IApplication>, CancellationToken)

Runs action while owner is active.

public static Task InvokeAsync(this IApplication app, SessionToken owner, Action<IApplication> action, CancellationToken cancellationToken = default)

Parameters

app IApplication

The application that owns the UI thread.

owner SessionToken

The session that owns the action's referenced views.

action Action<IApplication>

The action to run with the application instance.

cancellationToken CancellationToken

Cancels the dispatch if execution has not started.

Returns

Task

A task that reports completion, cancellation, or the action's exception.

Remarks

The owner may be an outer session while an inner modal is running. Ending the owner cancels its pending dispatches; ending another session does not. An owner that has already ended yields a canceled task. An owner that has not started running yet, such as one reported by SessionBegun, runs the action on a later main-loop iteration after it starts. After the final session ends or disposal begins, a canceled await may resume on a thread-pool thread.