Skip to content

DurableTaskExtensions Methods

Provides awaiting, identification, scheduling, timeout, and combinator operations for durable task definitions and handles.

Detached(DurableTask)

staticextension
View source
public static ConfiguredDurableTask Detached(this DurableTask task)
Returns a configuration which starts the task as an independent root task.

Parameters

taskDurableTask
The definition to start, such as a durable grain call.

Detached(DurableTask, string)

staticextension
View source
public static ConfiguredDurableTask Detached(this DurableTask task, string rootId)
Returns a configuration which starts the task as the independent root task rootId.

Parameters

taskDurableTask
The definition to start, such as a durable grain call.
rootIdstring
The task's root identifier on its host, verbatim.

Exceptions

System.ArgumentException
rootId is null or empty.

Detached(DurableTask<TResult>)

staticextension
View source
public static ConfiguredDurableTask<TResult> Detached<TResult>(this DurableTask<TResult> task)
Returns a configuration which starts the task as an independent root task.

Parameters

taskDurableTask<TResult>
The definition to start, such as a durable grain call.

Detached(DurableTask<TResult>, string)

staticextension
View source
public static ConfiguredDurableTask<TResult> Detached<TResult>(this DurableTask<TResult> task, string rootId)
Returns a configuration which starts the task as the independent root task rootId.

Parameters

taskDurableTask<TResult>
The definition to start, such as a durable grain call.
rootIdstring
The task's root identifier on its host, verbatim.

Exceptions

System.ArgumentException
rootId is null or empty.

GetAwaiter(DurableTask)

staticextension
View source
public static DurableTaskAwaiter GetAwaiter(this DurableTask task)
Gets an awaiter for a durable task in the current execution context.

Parameters

taskDurableTask

GetAwaiter(DurableTask<TResult>)

staticextension
View source
public static DurableTaskAwaiter<TResult> GetAwaiter<TResult>(this DurableTask<TResult> task)
Gets an awaiter for a durable task in the current execution context.

Parameters

taskDurableTask<TResult>

Post(DurableTask)

staticextension
View source
public static ScheduledTask Post(this DurableTask task)
Stages the start of the task in the caller's durable outbox, and returns its handle without waiting.

Parameters

taskDurableTask

Returns

The task's handle, which the caller can await later.

Exceptions

System.InvalidOperationException
The caller has no durable outbox, for example because it's a client.

Post(DurableTask<TResult>)

staticextension
View source
public static ScheduledTask<TResult> Post<TResult>(this DurableTask<TResult> task)
Stages the start of the task in the caller's durable outbox, and returns its handle without waiting.

Parameters

taskDurableTask<TResult>

Returns

The task's handle, which the caller can await later.

Exceptions

System.InvalidOperationException
The caller has no durable outbox, for example because it's a client.

Race(IEnumerable<DurableTask<TResult>>)

staticextension
View source
public static DurableTask<(this int Index, TResult Result)> DurableTaskExtensions.Race<TResult>(IEnumerable<DurableTask<TResult>> tasks)
Creates a durable task which returns the input index and result of the first input task to complete, after requesting cancellation of every other input and waiting until each is terminal.

Parameters

tasksIEnumerable<DurableTask<TResult>>
The input tasks, which are captured when this method is called.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution.

Exceptions

System.ArgumentOutOfRangeException
tasks is empty.

Race(IEnumerable<DurableTask>)

staticextension
View source
public static DurableTask<int> Race(this IEnumerable<DurableTask> tasks)
Creates a durable task which returns the input index of the first input task to complete, after requesting cancellation of every other input and waiting until each is terminal.

Parameters

tasksIEnumerable<DurableTask>
The input tasks, which are captured when this method is called.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution.

Exceptions

System.ArgumentOutOfRangeException
tasks is empty.

Race(IReadOnlyList<ScheduledTask<TResult>>, CancellationToken)

staticextension
View source
public static Task<ScheduledTask<TResult>> Race<TResult>(this IReadOnlyList<ScheduledTask<TResult>> tasks, CancellationToken cancellationToken = default(CancellationToken))
Waits for the first scheduled task to complete, requests durable cancellation of every other task, waits until every task is terminal, and returns the first task.

Parameters

tasksIReadOnlyList<ScheduledTask<TResult>>
The tasks, which are captured when this method is called.
cancellationTokenCancellationToken
A token which abandons the wait. It doesn't cancel the tasks.

Returns

The task which completed first, including a task which failed or was canceled. Every task has observed its terminal response, so ScheduledTask, ScheduledTask, and Orleans.Durable.Tasks.ScheduledTask.TryGetResult inspect the winner and the other tasks.

Exceptions

System.ArgumentOutOfRangeException
tasks is empty.

Race(IReadOnlyList<ScheduledTask>, CancellationToken)

staticextension
View source
public static Task<ScheduledTask> Race(this IReadOnlyList<ScheduledTask> tasks, CancellationToken cancellationToken = default(CancellationToken))
Waits for the first scheduled task to complete, requests durable cancellation of every other task, waits until every task is terminal, and returns the first task.

Parameters

tasksIReadOnlyList<ScheduledTask>
The tasks, which are captured when this method is called.
cancellationTokenCancellationToken
A token which abandons the wait. It doesn't cancel the tasks.

Returns

The task which completed first, including a task which failed or was canceled. Every task has observed its terminal response, so ScheduledTask, ScheduledTask, and Orleans.Durable.Tasks.ScheduledTask.TryGetResult inspect the winner and the other tasks.

Exceptions

System.ArgumentOutOfRangeException
tasks is empty.

ScheduleAll(IEnumerable<DurableTask<TResult>>)

staticextension
View source
public static DurableTask<ScheduledTask<TResult>[]> ScheduleAll<TResult>(this IEnumerable<DurableTask<TResult>> tasks)
Creates a durable task which schedules every input task and returns their handles, in input order.

Parameters

tasksIEnumerable<DurableTask<TResult>>
The input tasks, which are captured when this method is called.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution and returns each input's handle at its input index once the inputs are scheduled, without waiting for their results.

ScheduleAll(IEnumerable<DurableTask>)

staticextension
View source
public static DurableTask<ScheduledTask[]> ScheduleAll(this IEnumerable<DurableTask> tasks)
Creates a durable task which schedules every input task and returns their handles, in input order.

Parameters

tasksIEnumerable<DurableTask>
The input tasks, which are captured when this method is called.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution and returns each input's handle at its input index once the inputs are scheduled, without waiting for their results.

ScheduleAsync(DurableTask<TResult>, CancellationToken)

staticextension
View source
public static Task<ScheduledTask<TResult>> ScheduleAsync<TResult>(this DurableTask<TResult> task, CancellationToken cancellationToken = default(CancellationToken))
Starts the task and returns its handle once the task's host has accepted and durably stored the task.

Parameters

taskDurableTask<TResult>
A token which abandons the start. It doesn't cancel the task.
cancellationTokenCancellationToken

Returns

The task's handle, whose ScheduledTask addresses the task.

ScheduleAsync(DurableTask, CancellationToken)

staticextension
View source
public static Task<ScheduledTask> ScheduleAsync(this DurableTask task, CancellationToken cancellationToken = default(CancellationToken))
Starts the task and returns its handle once the task's host has accepted and durably stored the task.

Parameters

taskDurableTask
A token which abandons the start. It doesn't cancel the task.
cancellationTokenCancellationToken

Returns

The task's handle, whose ScheduledTask addresses the task.

Shielded(DurableTask)

staticextension
View source
public static ConfiguredDurableTask Shielded(this DurableTask task)
Returns a configuration which starts the task as an attached child, or runs it as part of the execution, out of reach of the starting execution's durable cancellation.

Parameters

taskDurableTask
The definition to start.

Shielded(DurableTask<TResult>)

staticextension
View source
public static ConfiguredDurableTask<TResult> Shielded<TResult>(this DurableTask<TResult> task)
Returns a configuration which starts the task as an attached child, or runs it as part of the execution, out of reach of the starting execution's durable cancellation.

Parameters

taskDurableTask<TResult>
The definition to start.

WaitAsync(DurableTask, TimeSpan)

staticextension
View source
public static DurableTask WaitAsync(this DurableTask task, TimeSpan timeout)
Creates a durable task which runs task and requests its durable cancellation once timeout elapses.

Parameters

taskDurableTask
The task to run.
timeoutTimeSpan
The time to wait before requesting cancellation, which is zero or positive.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution and completes once task is terminal.

Exceptions

System.ArgumentNullException
task is null.
System.ArgumentOutOfRangeException
timeout is negative, including System.Threading.Timeout.InfiniteTimeSpan; await the task itself to wait without a timeout.

WaitAsync(DurableTask<TResult>, TimeSpan)

staticextension
View source
public static DurableTask<TResult> WaitAsync<TResult>(this DurableTask<TResult> task, TimeSpan timeout)
Creates a durable task which runs task, returns its result, and requests its durable cancellation once timeout elapses.

Parameters

taskDurableTask<TResult>
The task to run.
timeoutTimeSpan
The time to wait before requesting cancellation, which is zero or positive.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution and completes once task is terminal.

Exceptions

System.ArgumentNullException
task is null.
System.ArgumentOutOfRangeException
timeout is negative, including System.Threading.Timeout.InfiniteTimeSpan; await the task itself to wait without a timeout.

WaitUntilAsync(DurableTask, DateTimeOffset)

staticextension
View source
public static DurableTask WaitUntilAsync(this DurableTask task, DateTimeOffset dueTime)
Creates a durable task which runs task and requests its durable cancellation once dueTime passes.

Parameters

taskDurableTask
The task to run.
dueTimeDateTimeOffset
The time, measured using host logical time, at which to request cancellation. A time which has passed times out promptly.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution and completes once task is terminal.

Exceptions

System.ArgumentNullException
task is null.

WaitUntilAsync(DurableTask<TResult>, DateTimeOffset)

staticextension
View source
public static DurableTask<TResult> WaitUntilAsync<TResult>(this DurableTask<TResult> task, DateTimeOffset dueTime)
Creates a durable task which runs task, returns its result, and requests its durable cancellation once dueTime passes.

Parameters

taskDurableTask<TResult>
The task to run.
dueTimeDateTimeOffset
The time, measured using host logical time, at which to request cancellation. A time which has passed times out promptly.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution and completes once task is terminal.

Exceptions

System.ArgumentNullException
task is null.

WhenAll(IEnumerable<DurableTask>)

staticextension
View source
public static DurableTask WhenAll(this IEnumerable<DurableTask> tasks)
Creates a durable task which completes once every input task has completed.

Parameters

tasksIEnumerable<DurableTask>
The input tasks, which are captured when this method is called.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution.

WhenAll(IEnumerable<DurableTask<TResult>>)

staticextension
View source
public static DurableTask<TResult[]> WhenAll<TResult>(this IEnumerable<DurableTask<TResult>> tasks)
Creates a durable task which returns the results of every input task, in input order.

Parameters

tasksIEnumerable<DurableTask<TResult>>
The input tasks, which are captured when this method is called.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution and returns an array with each input's result at its input index.

WhenAll(IReadOnlyList<ScheduledTask>, CancellationToken)

staticextension
View source
public static Task WhenAll(this IReadOnlyList<ScheduledTask> tasks, CancellationToken cancellationToken = default(CancellationToken))
Waits for every scheduled task to complete successfully.

Parameters

tasksIReadOnlyList<ScheduledTask>
cancellationTokenCancellationToken

WhenAll(IReadOnlyList<ScheduledTask<TResult>>, CancellationToken)

staticextension
View source
public static Task WhenAll<TResult>(this IReadOnlyList<ScheduledTask<TResult>> tasks, CancellationToken cancellationToken = default(CancellationToken))
Waits for every scheduled task to complete successfully.

Parameters

tasksIReadOnlyList<ScheduledTask<TResult>>
cancellationTokenCancellationToken

WhenAllCompleted(IEnumerable<DurableTask<TResult>>)

staticextension
View source
public static DurableTask<ScheduledTask<TResult>[]> WhenAllCompleted<TResult>(this IEnumerable<DurableTask<TResult>> tasks)
Creates a durable task which schedules every input task, waits until each is terminal, and returns their handles, in input order.

Parameters

tasksIEnumerable<DurableTask<TResult>>
The input tasks, which are captured when this method is called.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution and returns each input's handle at its input index. Each handle has observed its terminal response, so ScheduledTask, ScheduledTask, and Orleans.Durable.Tasks.ScheduledTask.TryGetResult inspect it.

WhenAllCompleted(IEnumerable<DurableTask>)

staticextension
View source
public static DurableTask<ScheduledTask[]> WhenAllCompleted(this IEnumerable<DurableTask> tasks)
Creates a durable task which schedules every input task, waits until each is terminal, and returns their handles, in input order.

Parameters

tasksIEnumerable<DurableTask>
The input tasks, which are captured when this method is called.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution and returns each input's handle at its input index. Each handle has observed its terminal response, so ScheduledTask, ScheduledTask, and Orleans.Durable.Tasks.ScheduledTask.TryGetResult inspect it.

WhenAllCompleted(IReadOnlyList<ScheduledTask<TResult>>, CancellationToken)

staticextension
View source
public static Task<ScheduledTask<TResult>[]> WhenAllCompleted<TResult>(this IReadOnlyList<ScheduledTask<TResult>> tasks, CancellationToken cancellationToken = default(CancellationToken))
Waits until every scheduled task is terminal, and returns the tasks in input order.

Parameters

tasksIReadOnlyList<ScheduledTask<TResult>>
The tasks, which are captured when this method is called.
cancellationTokenCancellationToken
A token which abandons the wait. It doesn't cancel the tasks.

Returns

The tasks, in input order. Each has observed its terminal response, so ScheduledTask, ScheduledTask, and Orleans.Durable.Tasks.ScheduledTask.TryGetResult inspect it.

WhenAllCompleted(IReadOnlyList<ScheduledTask>, CancellationToken)

staticextension
View source
public static Task<ScheduledTask[]> WhenAllCompleted(this IReadOnlyList<ScheduledTask> tasks, CancellationToken cancellationToken = default(CancellationToken))
Waits until every scheduled task is terminal, and returns the tasks in input order.

Parameters

tasksIReadOnlyList<ScheduledTask>
The tasks, which are captured when this method is called.
cancellationTokenCancellationToken
A token which abandons the wait. It doesn't cancel the tasks.

Returns

The tasks, in input order. Each has observed its terminal response, so ScheduledTask, ScheduledTask, and Orleans.Durable.Tasks.ScheduledTask.TryGetResult inspect it.

WhenAny(IEnumerable<DurableTask<TResult>>)

staticextension
View source
public static DurableTask<(this int Index, TResult Result)> DurableTaskExtensions.WhenAny<TResult>(IEnumerable<DurableTask<TResult>> tasks)
Creates a durable task which returns the input index and result of the first input task to complete.

Parameters

tasksIEnumerable<DurableTask<TResult>>
The input tasks.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution.

Exceptions

System.ArgumentOutOfRangeException
tasks is empty.

WhenAny(IEnumerable<DurableTask>)

staticextension
View source
public static DurableTask<int> WhenAny(this IEnumerable<DurableTask> tasks)
Creates a durable task which returns the input index of the first input task to complete.

Parameters

tasksIEnumerable<DurableTask>
The input tasks.

Returns

A combinator which, awaited within a durable execution, runs as part of that execution.

Exceptions

System.ArgumentOutOfRangeException
tasks is empty.

WhenAny(IReadOnlyList<ScheduledTask<TResult>>, CancellationToken)

staticextension
View source
public static Task<ScheduledTask<TResult>> WhenAny<TResult>(this IReadOnlyList<ScheduledTask<TResult>> tasks, CancellationToken cancellationToken = default(CancellationToken))
Returns the first scheduled task whose response completes, including failed or canceled durable responses. Wait cancellation and transport failures are propagated, and losing waits are canceled without canceling the durable tasks. Candidates are captured when this method is called.

Parameters

tasksIReadOnlyList<ScheduledTask<TResult>>
cancellationTokenCancellationToken

Exceptions

System.ArgumentOutOfRangeException
tasks is empty.
System.InvalidOperationException
The host's wait for the selected task returned an incomplete response.

WhenAny(IReadOnlyList<ScheduledTask>, CancellationToken)

staticextension
View source
public static Task<ScheduledTask> WhenAny(this IReadOnlyList<ScheduledTask> tasks, CancellationToken cancellationToken = default(CancellationToken))
Returns the first scheduled task whose response completes, including failed or canceled durable responses. Wait cancellation and transport failures are propagated, and losing waits are canceled without canceling the durable tasks. Candidates are captured when this method is called.

Parameters

tasksIReadOnlyList<ScheduledTask>
cancellationTokenCancellationToken

Exceptions

System.ArgumentOutOfRangeException
tasks is empty.
System.InvalidOperationException
The host's wait for the selected task returned an incomplete response.

WhenEach(IEnumerable<DurableTask<TResult>>)

staticextension
View source
public static IAsyncEnumerable<ScheduledTask<TResult>> WhenEach<TResult>(this IEnumerable<DurableTask<TResult>> tasks)
Schedules every input task and yields each input's handle once, in completion order, as the input reaches a terminal state.

Parameters

tasksIEnumerable<DurableTask<TResult>>
The input tasks, which are captured when this method is called.

Returns

The inputs' handles in completion order. Each yielded handle has observed its terminal response, including a failure or a cancellation, which doesn't fail the enumeration.

Exceptions

System.InvalidOperationException
The method is called outside a durable execution.

WhenEach(IReadOnlyList<ScheduledTask<TResult>>)

staticextension
View source
public static IAsyncEnumerable<ScheduledTask<TResult>> WhenEach<TResult>(this IReadOnlyList<ScheduledTask<TResult>> tasks)
Yields each scheduled task once, in completion order, as it reaches a terminal state.

Parameters

tasksIReadOnlyList<ScheduledTask<TResult>>
The tasks, which are captured when this method is called.

Returns

The tasks in completion order. Each yielded task has observed its terminal response, including a failure or a cancellation, which doesn't fail the enumeration.

WhenEach(IEnumerable<DurableTask>)

staticextension
View source
public static IAsyncEnumerable<ScheduledTask> WhenEach(this IEnumerable<DurableTask> tasks)
Schedules every input task and yields each input's handle once, in completion order, as the input reaches a terminal state.

Parameters

tasksIEnumerable<DurableTask>
The input tasks, which are captured when this method is called.

Returns

The inputs' handles in completion order. Each yielded handle has observed its terminal response, including a failure or a cancellation, which doesn't fail the enumeration.

Exceptions

System.InvalidOperationException
The method is called outside a durable execution.

WhenEach(IReadOnlyList<ScheduledTask>)

staticextension
View source
public static IAsyncEnumerable<ScheduledTask> WhenEach(this IReadOnlyList<ScheduledTask> tasks)
Yields each scheduled task once, in completion order, as it reaches a terminal state.

Parameters

tasksIReadOnlyList<ScheduledTask>
The tasks, which are captured when this method is called.

Returns

The tasks in completion order. Each yielded task has observed its terminal response, including a failure or a cancellation, which doesn't fail the enumeration.

WithId(DurableTask, string)

staticextension
View source
public static ConfiguredDurableTask WithId(this DurableTask task, string name)
Returns a configuration which names the task.

Parameters

taskDurableTask
The definition to start.
namestring
The task's name.

WithId(DurableTask<TResult>, string)

staticextension
View source
public static ConfiguredDurableTask<TResult> WithId<TResult>(this DurableTask<TResult> task, string name)
Returns a configuration which names the task.

Parameters

taskDurableTask<TResult>
The definition to start.
namestring
The task's name.