Table of Contents

Class AsyncHelper

Namespace
Ecng.Common
Assembly
Ecng.Common.dll

Provides helper methods for asynchronous operations, including cancellation support, task conversion, and exception handling.

public static class AsyncHelper
Inheritance
AsyncHelper
Inherited Members

Methods

AsValueTask(Task)

Converts a Task to a ValueTask.

public static ValueTask AsValueTask(this Task task)

Parameters

task Task

The task to convert.

Returns

ValueTask

A ValueTask representing the task.

AsValueTask<T>(Task<T>)

Converts a Task<TResult> to a ValueTask<TResult>.

public static ValueTask<T> AsValueTask<T>(this Task<T> task)

Parameters

task Task<T>

The task to convert.

Returns

ValueTask<T>

A ValueTask representing the task.

Type Parameters

T

The type of the result.

AsValueTask<T>(ValueTask<T>)

Awaits the specified ValueTask<TResult> and returns its result.

public static ValueTask AsValueTask<T>(this ValueTask<T> valueTask)

Parameters

valueTask ValueTask<T>

The ValueTask to await.

Returns

ValueTask

The result of the ValueTask.

Type Parameters

T

The type of the result.

CatchHandle(Func<Task>, CancellationToken, Action<Exception>, Action<Exception>, Action, bool, bool)

Executes the task obtained from the provided function, handles errors and cancellation, and optionally rethrows exceptions.

public static ValueTask CatchHandle(Func<Task> getTask, CancellationToken token, Action<Exception> handleError = null, Action<Exception> handleCancel = null, Action finalizer = null, bool rethrowErr = false, bool rethrowCancel = false)

Parameters

getTask Func<Task>

A function that returns a Task.

token CancellationToken

The cancellation token to observe.

handleError Action<Exception>

An action to handle errors.

handleCancel Action<Exception>

An action to handle cancellation scenarios.

finalizer Action

An action to execute in the finally block.

rethrowErr bool

Indicates whether to rethrow general exceptions.

rethrowCancel bool

Indicates whether to rethrow cancellation exceptions.

Returns

ValueTask

A ValueTask representing the asynchronous operation.

CatchHandle(Func<ValueTask>, CancellationToken, Action<Exception>, Action<Exception>, Action, bool, bool)

Executes the ValueTask obtained from the provided function, handles errors and cancellation, and optionally rethrows exceptions.

public static ValueTask CatchHandle(Func<ValueTask> getTask, CancellationToken token, Action<Exception> handleError = null, Action<Exception> handleCancel = null, Action finalizer = null, bool rethrowErr = false, bool rethrowCancel = false)

Parameters

getTask Func<ValueTask>

A function that returns a ValueTask.

token CancellationToken

The cancellation token to observe.

handleError Action<Exception>

An action to handle errors.

handleCancel Action<Exception>

An action to handle cancellation scenarios.

finalizer Action

An action to execute in the finally block.

rethrowErr bool

Indicates whether to rethrow general exceptions.

rethrowCancel bool

Indicates whether to rethrow cancellation exceptions.

Returns

ValueTask

A ValueTask representing the asynchronous operation.

CatchHandle(Task, CancellationToken, Action<Exception>, Action<Exception>, Action, bool, bool)

Executes the task, handles errors and cancellation, and optionally rethrows exceptions.

public static ValueTask CatchHandle(this Task task, CancellationToken token, Action<Exception> handleError = null, Action<Exception> handleCancel = null, Action finalizer = null, bool rethrowErr = false, bool rethrowCancel = false)

Parameters

task Task

The task to execute.

token CancellationToken

The cancellation token to observe.

handleError Action<Exception>

An action to handle errors.

handleCancel Action<Exception>

An action to handle cancellation scenarios.

finalizer Action

An action to execute in the finally block.

rethrowErr bool

Indicates whether to rethrow general exceptions.

rethrowCancel bool

Indicates whether to rethrow cancellation exceptions.

Returns

ValueTask

A ValueTask representing the asynchronous operation.

CatchHandle(ValueTask, CancellationToken, Action<Exception>, Action<Exception>, Action, bool, bool)

Executes the ValueTask, handles errors and cancellation, and optionally rethrows exceptions.

public static ValueTask CatchHandle(this ValueTask task, CancellationToken token, Action<Exception> handleError = null, Action<Exception> handleCancel = null, Action finalizer = null, bool rethrowErr = false, bool rethrowCancel = false)

Parameters

task ValueTask

The ValueTask to execute.

token CancellationToken

The cancellation token to observe.

handleError Action<Exception>

An action to handle errors.

handleCancel Action<Exception>

An action to handle cancellation scenarios.

finalizer Action

An action to execute in the finally block.

rethrowErr bool

Indicates whether to rethrow general exceptions.

rethrowCancel bool

Indicates whether to rethrow cancellation exceptions.

Returns

ValueTask

A ValueTask representing the asynchronous operation.

CheckNull(ValueTask?)

Returns a ValueTask from the provided nullable ValueTask.

public static ValueTask CheckNull(this ValueTask? task)

Parameters

task ValueTask?

The nullable ValueTask.

Returns

ValueTask

A ValueTask representing the operation.

CheckNull(Task)

Returns a ValueTask that completes when the provided task is not null.

public static ValueTask CheckNull(this Task task)

Parameters

task Task

The task to check for null.

Returns

ValueTask

A ValueTask representing the operation.

CreateChildToken(CancellationToken, TimeSpan?)

Creates a child cancellation token linked with the provided token, optionally with a delay.

public static (CancellationTokenSource cts, CancellationToken token) CreateChildToken(this CancellationToken token, TimeSpan? delay = null)

Parameters

token CancellationToken

The parent cancellation token.

delay TimeSpan?

Optional delay after which the child token cancels.

Returns

(CancellationTokenSource cts, CancellationToken token)

A tuple containing the newly created CancellationTokenSource and the linked CancellationToken.

CreateTaskCompletionSource(bool)

Creates a new TaskCompletionSource with the specified configuration.

public static TaskCompletionSource CreateTaskCompletionSource(bool forceAsync = true)

Parameters

forceAsync bool

If true, uses asynchronous continuations.

Returns

TaskCompletionSource

A new TaskCompletionSource with the provided configuration.

CreateTaskCompletionSource<TValue>(bool)

Creates a new TaskCompletionSource with the specified configuration.

public static TaskCompletionSource<TValue> CreateTaskCompletionSource<TValue>(bool forceAsync = true)

Parameters

forceAsync bool

If true, uses asynchronous continuations.

Returns

TaskCompletionSource<TValue>

A new TaskCompletionSource with the provided configuration.

Type Parameters

TValue

The type of the task result.

CreateTimeoutToken(TimeSpan)

Creates a cancellation token that will be canceled after the specified timeout.

public static CancellationToken CreateTimeoutToken(this TimeSpan timeout)

Parameters

timeout TimeSpan

The timeout after which the token is canceled.

Returns

CancellationToken

A CancellationToken that is canceled after the timeout.

Delay(TimeSpan, CancellationToken)

Creates a delay for the specified time interval.

public static Task Delay(this TimeSpan delay, CancellationToken cancellationToken = default)

Parameters

delay TimeSpan

The time interval to wait.

cancellationToken CancellationToken

A token to observe while waiting.

Returns

Task

A task that completes after the specified time delay.

FromResult<TValue>(TValue)

Returns a completed task with the specified result.

public static Task<TValue> FromResult<TValue>(this TValue value)

Parameters

value TValue

The value to be used as the task result.

Returns

Task<TValue>

A task that has completed successfully with the given result.

Type Parameters

TValue

The type of the result.

GetResult<T>(Task)

Retrieves the result of a completed task.

public static T GetResult<T>(this Task task)

Parameters

task Task

The completed task.

Returns

T

The result of the task.

Type Parameters

T

The type of the result.

Run(Func<ValueTask>)

Executes the provided asynchronous function in a synchronous context.

public static void Run(Func<ValueTask> getTask)

Parameters

getTask Func<ValueTask>

A function that returns a ValueTask.

Run<T>(Func<ValueTask<T>>)

Executes the provided asynchronous function in a synchronous context and returns the result.

public static T Run<T>(Func<ValueTask<T>> getTask)

Parameters

getTask Func<ValueTask<T>>

A function that returns a ValueTask{T}.

Returns

T

The result from the asynchronous operation.

Type Parameters

T

The type of the result.

ToCompleteSource<TValue>(TValue)

Creates a TaskCompletionSource<TResult> that is already completed with the specified value.

public static TaskCompletionSource<TValue> ToCompleteSource<TValue>(this TValue value)

Parameters

value TValue

The value to complete the task with.

Returns

TaskCompletionSource<TValue>

A TaskCompletionSource completed with the given value.

Type Parameters

TValue

The type of the value.

TryCompleteFromCompletedTask(TaskCompletionSource, Task)

Attempts to complete the TaskCompletionSource using the state of the completed task.

public static bool TryCompleteFromCompletedTask(this TaskCompletionSource tcs, Task task)

Parameters

tcs TaskCompletionSource

The TaskCompletionSource to complete.

task Task

The completed task whose state is used.

Returns

bool

True if TaskCompletionSource was updated successfully; otherwise, false.

Exceptions

InvalidOperationException

Thrown if the task is not completed or in an invalid state.

WhenAll(IEnumerable<ValueTask>)

Awaits all the provided ValueTask tasks.

public static ValueTask WhenAll(this IEnumerable<ValueTask> tasks)

Parameters

tasks IEnumerable<ValueTask>

The collection of ValueTasks to await.

Returns

ValueTask

A task representing the asynchronous operation.

Exceptions

ArgumentNullException

Thrown if tasks is null.

AggregateException

Thrown if one or more tasks fail.

WhenAll<T>(IEnumerable<ValueTask<T>>)

Awaits all the provided ValueTask<TResult> tasks and returns an array of their results.

public static ValueTask<T[]> WhenAll<T>(this IEnumerable<ValueTask<T>> tasks)

Parameters

tasks IEnumerable<ValueTask<T>>

The collection of ValueTasks to await.

Returns

ValueTask<T[]>

An array of the results from the tasks.

Type Parameters

T

The type of the task result.

Exceptions

ArgumentNullException

Thrown if tasks is null.

AggregateException

Thrown if one or more tasks fail.

WhenCanceled(CancellationToken)

Returns a task that completes when the cancellation token is canceled.

public static Task WhenCanceled(this CancellationToken token)

Parameters

token CancellationToken

The cancellation token.

Returns

Task

A task that completes when the token is canceled.

WithCancellation(Task, CancellationToken)

Awaits the task and supports cancellation by throwing an OperationCanceledException if the cancellation token is triggered.

public static Task WithCancellation(this Task task, CancellationToken cancellationToken)

Parameters

task Task

The task to await.

cancellationToken CancellationToken

The token used to cancel the operation.

Returns

Task

Exceptions

OperationCanceledException

Thrown when the cancellation token is triggered.

WithCancellation<T>(Task<T>, CancellationToken)

Awaits the task and supports cancellation by throwing an OperationCanceledException if the cancellation token is triggered.

public static Task<T> WithCancellation<T>(this Task<T> task, CancellationToken cancellationToken)

Parameters

task Task<T>

The task to await.

cancellationToken CancellationToken

The token used to cancel the operation.

Returns

Task<T>

A task representing the asynchronous operation that returns a result of type T.

Type Parameters

T

The type of the task result.

Exceptions

OperationCanceledException

Thrown when the cancellation token is triggered.

WithEnforcedCancellation<T>(IAsyncEnumerable<T>, CancellationToken)

Returns an asynchronous enumerable that enforces cancellation using the provided token.

public static IAsyncEnumerable<T> WithEnforcedCancellation<T>(this IAsyncEnumerable<T> source, CancellationToken cancellationToken)

Parameters

source IAsyncEnumerable<T>

The source asynchronous enumerable.

cancellationToken CancellationToken

The cancellation token to observe.

Returns

IAsyncEnumerable<T>

An asynchronous enumerable that throws an exception if cancellation is requested.

Type Parameters

T

The type of the elements in the enumerable.

Exceptions

ArgumentNullException

Thrown if source is null.