Logo FSharp.Core

AsyncTaskLikeExtensions Module

Namespace: FSharp.Control
Assembly: FSharp.Core.dll

A module of extension members providing support for awaiting any task-like value via the GetAwaiter pattern.

Starting Async Computations

Type extensions

Type extension Description

Async.StartTaskImmediate(createTask)

Full Usage: Async.StartTaskImmediate(createTask)

Parameters:
    createTask : CancellationToken -> ^TaskLike - A function that accepts a CancellationToken and returns a task-like value satisfying the GetAwaiter pattern.

Returns: Async<'T>
Modifiers: inline
Type parameters: ^TaskLike, ^Awaiter, 'T (requires (member GetAwaiter : ^TaskLike -> ^Awaiter) and :> System.Runtime.CompilerServices.ICriticalNotifyCompletion and (member get_IsCompleted : ^Awaiter -> Microsoft.FSharp.Core.bool) and (member GetResult : ^Awaiter -> 'T))

Creates an asynchronous computation that passes the ambient Async.CancellationToken to createTask, and then awaits the resulting task-like value.

The value returned by createTask must satisfy the GetAwaiter pattern: it must have a GetAwaiter() method returning an awaiter implementing ICriticalNotifyCompletion with IsCompleted and GetResult() members. This overload uses statically resolved type parameters (SRTP) so it can accept factories returning any task-like type, including YieldAwaitable (from Task.Yield()) and ConfiguredTaskAwaitable (from task.ConfigureAwait(false)). The specific overloads for Task, Task, ValueTask and ValueTask are preferred when the factory return type is known.

Extended Type: Async

createTask : CancellationToken -> ^TaskLike

A function that accepts a CancellationToken and returns a task-like value satisfying the GetAwaiter pattern.

Returns: Async<'T>
Example 

 // Straightforward: factory returns Task<string>, which is handled by
 // the specific Task<'T> overload of StartTaskImmediate (not this one).
 let fetchPlain (url: string) =
     Async.StartTaskImmediate(fun ct ->
         httpClient.GetStringAsync(url, ct))   // returns Task<string>

 // Adding ConfigureAwait(false) to the mix yields a ConfiguredTaskAwaitable<string>,
 // which has no specific overload — this SRTP overload handles it.
 let fetchConfigured (url: string) =
     Async.StartTaskImmediate(fun ct ->
         httpClient.GetStringAsync(url, ct).ConfigureAwait(false))

 async {
     let! html = fetchConfigured "https://example.com"
     printn $"Downloaded {html.Length} chars"
 } |> Async.RunSynchronouslyImmediate
val fetchPlain: url: string -> 'a
val url: string
Multiple items
val string: value: 'T -> string

--------------------
type string = System.String
Multiple items
type Async =
  static member AsBeginEnd:
      computation: ('Arg -> Async<'T>) ->
          ('Arg * AsyncCallback * objnull -> IAsyncResult) * (IAsyncResult -> 'T) * (IAsyncResult -> unit)
  static member AwaitEvent: event: IEvent<'Del,'T> * ?cancelAction: (unit -> unit) -> Async<'T> (requires delegate and 'Del :> Delegate and 'Del: not null)
  static member AwaitIAsyncResult:
      iar: IAsyncResult *
      ?millisecondsTimeout: int ->
          Async<bool>
  static member AwaitTask: task: Task<'T> -> Async<'T> + 1 overload
  static member AwaitWaitHandle:
      waitHandle: WaitHandle *
      ?millisecondsTimeout: int ->
          Async<bool>
  static member CancelDefaultToken: unit -> unit
  static member Catch: computation: Async<'T> -> Async<Choice<'T,exn>>
  static member Choice: computations: Async<'T option> seq -> Async<'T option>
  static member FromBeginEnd: beginAction: (AsyncCallback * objnull -> IAsyncResult) * endAction: (IAsyncResult -> 'T) * ?cancelAction: (unit -> unit) -> Async<'T> + 3 overloads
  static member FromContinuations:
      callback: (('T -> unit) * (exn -> unit) * (OperationCanceledException -> unit) -> unit) ->
          Async<'T>
  ...

--------------------
type Async<'T>
val fetchConfigured: url: string -> 'a
val async: AsyncBuilder
val html: obj

Awaiting Results

Type extensions

Type extension Description

Async.Await(task)

Full Usage: Async.Await(task)

Parameters:
    task : ^TaskLike - The task-like value to await.

Returns: Async<'T>
Modifiers: inline
Type parameters: ^TaskLike, ^Awaiter, 'T (requires (member GetAwaiter : ^TaskLike -> ^Awaiter) and :> System.Runtime.CompilerServices.ICriticalNotifyCompletion and (member get_IsCompleted : ^Awaiter -> Microsoft.FSharp.Core.bool) and (member GetResult : ^Awaiter -> 'T))

Creates an asynchronous computation that will wait for the given task-like value to complete and return its result.

For the common case where you are running a Task within an Asynchronous Computation, see StartTaskImmediate, which surfaces the ambient CancellationToken so that it can be passed to the Task being started.

The value must satisfy the GetAwaiter pattern: it must have a GetAwaiter() method returning an awaiter implementing with IsCompleted and GetResult() members.

Exceptions thrown by GetResult() are propagated directly.

Unlike the and overloads, an carrying multiple inner exceptions is not preserved: the first inner exception surfaces (standard GetResult() semantics).

This overload uses statically resolved type parameters (SRTP) so it can accept any task-like type. The specific overloads for , , and are preferred when the argument type is known.

Extended Type: Async

task : ^TaskLike

The task-like value to await.

Returns: Async<'T>
Example 

 // A minimal custom task-like type
 type MyTask<'T>(task: System.Threading.Tasks.Task<'T>) =
     member _.GetAwaiter() = task.GetAwaiter()

 let myTask = MyTask(System.Threading.Tasks.Task.FromResult 42)
 async {
     let! result = Async.Await myTask
     printn $"Result: {result}"
 } |> Async.RunSynchronously
Multiple items
type MyTask<'T> =
  new: task: Task<'T> -> MyTask<'T>
  member GetAwaiter: unit -> TaskAwaiter<'T>

--------------------
new: task: System.Threading.Tasks.Task<'T> -> MyTask<'T>
'T
val task: System.Threading.Tasks.Task<'T>
namespace System
namespace System.Threading
namespace System.Threading.Tasks
Multiple items
Represents an asynchronous operation that can return a value.

TResult: The type of the result produced by this Task`1.
type Task<'TResult> =
  inherit Task
  new: ``function`` : Func<obj,'TResult> * state: obj -> unit + 7 overloads
  member ConfigureAwait: continueOnCapturedContext: bool -> ConfiguredTaskAwaitable<'TResult> + 1 overload
  member ContinueWith: continuationAction: Action<Task<'TResult>,obj> * state: obj -> Task + 19 overloads
  member GetAwaiter: unit -> TaskAwaiter<'TResult>
  member WaitAsync: cancellationToken: CancellationToken -> Task<'TResult> + 4 overloads
  member Result: 'TResult
  static member Factory: TaskFactory<'TResult>

--------------------
Represents an asynchronous operation.
type Task =
  interface IAsyncResult
  interface IDisposable
  new: action: Action -> unit + 7 overloads
  member ConfigureAwait: continueOnCapturedContext: bool -> ConfiguredTaskAwaitable + 1 overload
  member ContinueWith: continuationAction: Action<Task,obj> * state: obj -> Task + 19 overloads
  member Dispose: unit -> unit
  member GetAwaiter: unit -> TaskAwaiter
  member RunSynchronously: unit -> unit + 1 overload
  member Start: unit -> unit + 1 overload
  member Wait: unit -> unit + 5 overloads
  ...

--------------------
System.Threading.Tasks.Task(``function`` : System.Func<'TResult>) : System.Threading.Tasks.Task<'TResult>
System.Threading.Tasks.Task(``function`` : System.Func<obj,'TResult>, state: obj) : System.Threading.Tasks.Task<'TResult>
System.Threading.Tasks.Task(``function`` : System.Func<'TResult>, cancellationToken: System.Threading.CancellationToken) : System.Threading.Tasks.Task<'TResult>
System.Threading.Tasks.Task(``function`` : System.Func<'TResult>, creationOptions: System.Threading.Tasks.TaskCreationOptions) : System.Threading.Tasks.Task<'TResult>
System.Threading.Tasks.Task(``function`` : System.Func<obj,'TResult>, state: obj, cancellationToken: System.Threading.CancellationToken) : System.Threading.Tasks.Task<'TResult>
System.Threading.Tasks.Task(``function`` : System.Func<obj,'TResult>, state: obj, creationOptions: System.Threading.Tasks.TaskCreationOptions) : System.Threading.Tasks.Task<'TResult>
System.Threading.Tasks.Task(``function`` : System.Func<'TResult>, cancellationToken: System.Threading.CancellationToken, creationOptions: System.Threading.Tasks.TaskCreationOptions) : System.Threading.Tasks.Task<'TResult>
System.Threading.Tasks.Task(``function`` : System.Func<obj,'TResult>, state: obj, cancellationToken: System.Threading.CancellationToken, creationOptions: System.Threading.Tasks.TaskCreationOptions) : System.Threading.Tasks.Task<'TResult>

--------------------
System.Threading.Tasks.Task(action: System.Action) : System.Threading.Tasks.Task
System.Threading.Tasks.Task(action: System.Action, cancellationToken: System.Threading.CancellationToken) : System.Threading.Tasks.Task
System.Threading.Tasks.Task(action: System.Action, creationOptions: System.Threading.Tasks.TaskCreationOptions) : System.Threading.Tasks.Task
System.Threading.Tasks.Task(action: System.Action<obj>, state: obj) : System.Threading.Tasks.Task
System.Threading.Tasks.Task(action: System.Action, cancellationToken: System.Threading.CancellationToken, creationOptions: System.Threading.Tasks.TaskCreationOptions) : System.Threading.Tasks.Task
System.Threading.Tasks.Task(action: System.Action<obj>, state: obj, cancellationToken: System.Threading.CancellationToken) : System.Threading.Tasks.Task
System.Threading.Tasks.Task(action: System.Action<obj>, state: obj, creationOptions: System.Threading.Tasks.TaskCreationOptions) : System.Threading.Tasks.Task
System.Threading.Tasks.Task(action: System.Action<obj>, state: obj, cancellationToken: System.Threading.CancellationToken, creationOptions: System.Threading.Tasks.TaskCreationOptions) : System.Threading.Tasks.Task
System.Threading.Tasks.Task.GetAwaiter() : System.Runtime.CompilerServices.TaskAwaiter<'T>
val myTask: MyTask<int>
System.Threading.Tasks.Task.FromResult<'TResult>(result: 'TResult) : System.Threading.Tasks.Task<'TResult>
val async: AsyncBuilder
val result: obj
Multiple items
type Async =
  static member AsBeginEnd:
      computation: ('Arg -> Async<'T>) ->
          ('Arg * AsyncCallback * objnull -> IAsyncResult) * (IAsyncResult -> 'T) * (IAsyncResult -> unit)
  static member AwaitEvent: event: IEvent<'Del,'T> * ?cancelAction: (unit -> unit) -> Async<'T> (requires delegate and 'Del :> Delegate and 'Del: not null)
  static member AwaitIAsyncResult:
      iar: IAsyncResult *
      ?millisecondsTimeout: int ->
          Async<bool>
  static member AwaitTask: task: Task<'T> -> Async<'T> + 1 overload
  static member AwaitWaitHandle:
      waitHandle: WaitHandle *
      ?millisecondsTimeout: int ->
          Async<bool>
  static member CancelDefaultToken: unit -> unit
  static member Catch: computation: Async<'T> -> Async<Choice<'T,exn>>
  static member Choice: computations: Async<'T option> seq -> Async<'T option>
  static member FromBeginEnd: beginAction: (AsyncCallback * objnull -> IAsyncResult) * endAction: (IAsyncResult -> 'T) * ?cancelAction: (unit -> unit) -> Async<'T> + 3 overloads
  static member FromContinuations:
      callback: (('T -> unit) * (exn -> unit) * (OperationCanceledException -> unit) -> unit) ->
          Async<'T>
  ...

--------------------
type Async<'T>
static member Async.RunSynchronously:
    computation: Async<'T> *
    ?timeout: int *
    ?cancellationToken: System.Threading.CancellationToken ->
        'T
Prints Result: 42.

Type something to start searching.