[Home] Type Microsoft.FSharp.Control.Async


A computation, which, when run, will eventually produce a value of the given type, or else raise an exception. The value and/or exception is not returned to the caller immediately, but is rather passed to a continuation or exception continuation. Async computations are normally specified using the F# 'workflow' syntax for building computations. Operationally, async computations typically run partly in the .NET Thread Pool via ThreadPool.QueueUserWorkItem, and, when waiting for asynchronous I/O, they are suspended as thunks using ThreadPool.RegisterWaitForSingleObject, waiting for the I/O completion. Some primitive asynchronous computations necessarily end up executing blocking operations: these should be run on a pool of threads specifically dedicated to resolving blocking conditions, via UnblockedPrimitive. For example, FileOpen on Windows is, by design, a blocking operation. However frequently it is important to code as if this is asynchronous. This can be done by running the blocking operation via UnblockedPrimitive. When run, async computations belong to an AsyncGroup. This can usually be specified when the async computation is started. The only action on an AsyncGroup is to raise a cancellation condition for the AsyncGroup. Async values check the cancellation condition for their AsyncGroup regularly, though synchronous computations within an asynchronous computation will not automatically check this condition. This gives a user-level cooperative cancellation protocol.

Full Type Signature

[<ExperimentalAttribute ("This type is part of an experimental feature called 'asynchronous workflows'")>]
type Async<'res>
  with
    static member AsyncFuture : computation:Async<'a> * ?asyncGroup:AsyncGroup -> IAsyncFuture<'a>
    [<Obsolete ("Consider using a computation expression 'async { ... }' or call 'async.Bind' directly")>]
    static member Bind : p:Async<'a> * f:('a -> Async<'b>) -> Async<'b>
    [<OverloadIDAttribute ("BuildPrimitve_three_arg")>]
    static member
      BuildPrimitive : 'arg1 * 'arg2 * 'arg3 * ('arg1 * 'arg2 * 'arg3 * AsyncCallback * obj -> IAsyncResult) *
                       (IAsyncResult -> 'a) -> Async<'a>
    [<OverloadIDAttribute ("BuildPrimitve_two_arg")>]
    static member
      BuildPrimitive : 'arg1 * 'arg2 * ('arg1 * 'arg2 * AsyncCallback * obj -> IAsyncResult) * (IAsyncResult -> 'a) ->
                       Async<'a>
    [<OverloadIDAttribute ("BuildPrimitve_one_arg")>]
    static member
      BuildPrimitive : 'arg1 * ('arg1 * AsyncCallback * obj -> IAsyncResult) * (IAsyncResult -> 'a) -> Async<'a>
    [<OverloadIDAttribute ("BuildPrimitve_zero_arg")>]
    static member BuildPrimitive : (AsyncCallback * obj -> IAsyncResult) * (IAsyncResult -> 'a) -> Async<'a>
    static member CancelCheck : unit -> Async<unit>
    static member CancelDefaultGroup : ?message:string -> unit
    static member Catch : Async<'a> -> Async<Choice<'a,exn>>
    [<Obsolete ("Consider using a computation expression 'async { ... }' or call 'async.Delay' directly")>]
    static member Delay : (unit -> Async<'a>) -> Async<'a>
    [<Obsolete ("This member has been renamed AsyncFuture")>]
    static member Future : computation:Async<'a> * ?asyncGroup:AsyncGroup -> IAsyncFuture<'a>
    static member Generate : N:int * generator:(int -> Async<'b>) * ?numGroups:int -> Async<'b array>
    [<Obsolete ("Consider using a computation expression 'async { let! _ = p in return () }'")>]
    static member Ignore : p:Async<'a> -> Async<unit>
    static member OnCancel : f:(string -> unit) -> Async<IDisposable>
    static member Parallel : #seq<Async<'b>> -> Async<'b array>
    static member Parallel2 : Async<'b> * Async<'c> -> Async<'b * 'c>
    static member Parallel3 : Async<'b> * Async<'c> * Async<'d> -> Async<'b * 'c * 'd>
    [<OverloadIDAttribute ("Primitive_with_ccont")>]
    static member Primitive : (('a -> unit) * (exn -> unit) * (OperationCanceledException -> unit) -> unit) -> Async<'a>
    [<OverloadIDAttribute ("Primitive")>]
    static member Primitive : (('a -> unit) * (exn -> unit) -> unit) -> Async<'a>
    [<Obsolete ("Consider using 'async { do raise ... }' instead")>]
    static member Raise : #exn -> Async<'b>
    [<Obsolete ("Consider using 'async { return ... }' instead, or call 'async.Return' directly")>]
    static member Return : 'a -> Async<'a>
    static member Run : computation:Async<'a> * ?asyncGroup:AsyncGroup * ?timeout:int * ?exitContext:bool -> 'a
    static member Spawn : computation:Async<unit> * ?asyncGroup:AsyncGroup -> unit
    static member SpawnChild : Async<unit> -> Async<unit>
    static member SpawnThenPostBack : computation:Async<'a> * postBack:('a -> unit) * ?asyncGroup:AsyncGroup -> unit
    static member SwitchToNewThread : unit -> Async<unit>
    static member SwitchToThreadPool : unit -> Async<unit>
    [<Obsolete ("Consider using 'async { try ... finally ... }' instead, or call 'async.TryFinally' directly")>]
    static member TryFinally : Async<'a> * (unit -> unit) -> Async<'a>
    [<Obsolete ("Consider using 'async { do! Async.SwitchToNewThread() ... }' instead")>]
    static member UnblockedPrimitive : (unit -> 'a) -> Async<'a>
    [<Obsolete ("Consider using 'async { use x = ... }' instead, or call 'async.Using' directly")>]
    static member Using : 'b * ('b -> Async<'a>) -> Async<'a> when 'b :> IDisposable
    static member WhenCancelled : Async<'a> * (OperationCanceledException -> unit) -> Async<'a>
    [<Obsolete ("Consider using 'async { return () }' instead")>]
    static member Done : Async<unit>
  end

Static Members

MemberDescription
member
  AsyncFuture : computation:Async<'a> * ?asyncGroup:AsyncGroup ->
                IAsyncFuture<'a>
Start the asynchronous computation in the .NET thread pool, initially as a CPU-intensive worker item. Return a handle to the computation as an IAsyncFuture.
[<OverloadIDAttribute ("BuildPrimitve_three_arg")>]
member
  BuildPrimitive : 'arg1 * 'arg2 * 'arg3 *
                   ('arg1 * 'arg2 * 'arg3 * AsyncCallback * obj -> IAsyncResult) *
                   (IAsyncResult -> 'a) -> Async<'a>
Build a new Async task in terms of a Begin/End pair of actions in the style frequently used in .NET APIs where the overall operation is qualified by three arguments. For example, Async.BuildPrimitive(arg1,arg2,arg3,ws.BeginGetWeather,ws.EndGetWeather)
[<OverloadIDAttribute ("BuildPrimitve_two_arg")>]
member
  BuildPrimitive : 'arg1 * 'arg2 *
                   ('arg1 * 'arg2 * AsyncCallback * obj -> IAsyncResult) *
                   (IAsyncResult -> 'a) -> Async<'a>
Build a new Async task in terms of a Begin/End pair of actions in the style frequently used in .NET APIs where the overall operation is qualified by two arguments. For example, Async.BuildPrimitive(arg1,arg2,ws.BeginGetWeather,ws.EndGetWeather)
[<OverloadIDAttribute ("BuildPrimitve_one_arg")>]
member
  BuildPrimitive : 'arg1 * ('arg1 * AsyncCallback * obj -> IAsyncResult) *
                   (IAsyncResult -> 'a) -> Async<'a>
Build a new Async task in terms of a Begin/End pair of actions in the style frequently used in .NET APIs where the overall operation is qualified by one argument. For example, Async.BuildPrimitive(place,ws.BeginGetWeather,ws.EndGetWeather)
[<OverloadIDAttribute ("BuildPrimitve_zero_arg")>]
member
  BuildPrimitive : (AsyncCallback * obj -> IAsyncResult) * (IAsyncResult -> 'a)
                   -> Async<'a>
Build a new Async task in terms of a Begin/End pair of actions in the style frequently used in .NET APIs where the overall operation is not qualified by any arguments. For example, Async.BuildPrimitive(ws.BeginGetWeather,ws.EndGetWeather)
member CancelCheck : unit -> Async<unit>
"CancelCheck" generates an asynchronous computation that checks if the cancellation condition for the AsyncGroup to which this Async computation belongs has been set. If so the operation raises a System.OperationCanceledException.
member CancelDefaultGroup : ?message:string -> unit
Raise the cancellation condition for the most recent set of Async computations started without any specific AsyncGroup. Replace the global group with a new global group for any async computations created after this point without any specific AsyncGroup.
member Catch : Async<'a> -> Async<Choice<'a,exn>>
member
  Generate : N:int * generator:(int -> Async<'b>) * ?numGroups:int ->
             Async<'b array>
Generate asynchronous computations for indexes 0..N-1. Do so in the indicated number of parallel groups, which defaults to the physical processor count on the machine. If any raise an exception attempt to cancel the others.
member OnCancel : f:(string -> unit) -> Async<IDisposable>
"async { use! holder = Async.OnCancel f ... }" generates an asynchronous computation where, if a cancellation happens any time during the execution of the asynchronous computation in the scope of 'holder', then action 'f' is executed on the thread that is performing the cancellation. You can use this to arrange for your own computation to be asynchronously notified that a cancellation has occurred, e.g. by setting a flag, or deregistering a pending I/O action.
member Parallel : #seq<Async<'b>> -> Async<'b array>
When the joint task is run, it will execute all the asynchronous computations, queueing each in the thread pool immediately. If any raise an exception then the overall computation will raise an exception, and attempt to cancel the others. All the sub-computations belong to an AsyncGroup that is a subsidiary of the AsyncGroup of the outer computations.
member Parallel2 : Async<'b> * Async<'c> -> Async<'b * 'c>
When the joint task is run, it will execute it will execute the two asynchronous computations, starting each in the thread pool. If any raise an exception then the overall computation will raise an exception, and attempt to cancel the others. All the sub-computations belong to an AsyncGroup that is a subsidiary of the AsyncGroup of the outer computations.
member Parallel3 : Async<'b> * Async<'c> * Async<'d> -> Async<'b * 'c * 'd>
When the joint task is run, it will execute it will execute the two asynchronous computations, starting each in the thread pool. If any raise an exception then the overall computation will raise an exception, and attempt to cancel the others. All the sub-computations belong to an AsyncGroup that is a subsidiary of the AsyncGroup of the outer computations.
[<OverloadIDAttribute ("Primitive_with_ccont")>]
member
  Primitive : (('a -> unit) * (exn -> unit) *
               (OperationCanceledException -> unit) -> unit) -> Async<'a>
Build a new Async task by specifying a callback that gets called when the task is run. The callback must eventually call either the continuation, the exception continuation or the cancel exception.
[<OverloadIDAttribute ("Primitive")>]
member Primitive : (('a -> unit) * (exn -> unit) -> unit) -> Async<'a>
Build a new Async task by specifying a callback that gets called when the task is run. The callback must eventually call either the continuation or the exception continuation.
member
  Run : computation:Async<'a> * ?asyncGroup:AsyncGroup * ?timeout:int *
        ?exitContext:bool -> 'a
Run the asynchronous computation and await its result. If an exception occurs in the asynchronous computation then an exception is re-raised by this function.
member Spawn : computation:Async<unit> * ?asyncGroup:AsyncGroup -> unit
Start the asynchronous computation in the thread pool. Do not await its result.
member SpawnChild : Async<unit> -> Async<unit>
Start the asynchronous computation in the thread pool, and add it to the AsyncGroup of of the asynchronous computation. Do not await its result. Exceptions in the asynchronous computation are currently ignored.
member
  SpawnThenPostBack : computation:Async<'a> * postBack:('a -> unit) *
                      ?asyncGroup:AsyncGroup -> unit
Start the asynchronous computation in the thread pool. When the result is available execute the given postBack in the synchronization context of the thread that originally called Run. This will frequently be the GUI thread, and in that case the postBack will be executed by sending a 'BeginInvoke' to the GUI message loop. If the System.Threading.SynchronizationContext.Current of the calling thread is 'null' then a FailureException is raised. If an exception occurs in the asynchronous computation then it is posted as a function that raises an exception in the synchronization context of the thread that originally called RunThenPostBack.
member SwitchToNewThread : unit -> Async<unit>
'SwitchToNewThread' creates an asynchronous computation that, when run, creates a brand new thread and runs its continutation in that thread
member SwitchToThreadPool : unit -> Async<unit>
'SwitchToThreadPool p' creates an asynchronous computation that, when run, queues a CPU-intensive work item that runs its continutation.
member
  WhenCancelled : Async<'a> * (OperationCanceledException -> unit) -> Async<'a>
"WhenCancelled p f" runs "p". If "p" is effectively cancelled before its termination then the process "f exn" is executed.

Deprecated Members

MemberDescription
[<Obsolete
  ("Consider using a computation expression 'async { ... }' or call 'async.Bind' directly")>]
member Bind : p:Async<'a> * f:('a -> Async<'b>) -> Async<'b>

Note: Consider using a computation expression 'async { ... }' or call 'async.Bind' directly

[<Obsolete
  ("Consider using a computation expression 'async { ... }' or call 'async.Delay' directly")>]
member Delay : (unit -> Async<'a>) -> Async<'a>

Note: Consider using a computation expression 'async { ... }' or call 'async.Delay' directly

"Delay f" generates an asynchronous computation that, when run, runs the asynchronous computation "f x"
[<Obsolete ("Consider using 'async { return () }' instead")>]
member Done : Async<unit>

Note: Consider using 'async { return () }' instead

"Done" generates an asynchronous computation that, when run, yields the value 'unit' immediately
[<Obsolete ("This member has been renamed AsyncFuture")>]
member
  Future : computation:Async<'a> * ?asyncGroup:AsyncGroup -> IAsyncFuture<'a>

Note: This member has been renamed AsyncFuture

[<Obsolete
  ("Consider using a computation expression 'async { let! _ = p in return () }'")>]
member Ignore : p:Async<'a> -> Async<unit>

Note: Consider using a computation expression 'async { let! _ = p in return () }'

Generate an asynchronous computation that, when run, runs 'p', ignoring the result and returning the result '()'.
[<Obsolete ("Consider using 'async { do raise ... }' instead")>]
member Raise : #exn -> Async<'b>

Note: Consider using 'async { do raise ... }' instead

"Raise exn" generates an asynchronous computation that, when run terminates by raising the given exception, i.e. the given exception is passed to the exception continuation.
[<Obsolete
  ("Consider using 'async { return ... }' instead, or call 'async.Return' directly")>]
member Return : 'a -> Async<'a>

Note: Consider using 'async { return ... }' instead, or call 'async.Return' directly

"Return x" generates an asynchronous computation that, when run, yields the value "x" immediately
[<Obsolete
  ("Consider using 'async { try ... finally ... }' instead, or call 'async.TryFinally' directly")>]
member TryFinally : Async<'a> * (unit -> unit) -> Async<'a>

Note: Consider using 'async { try ... finally ... }' instead, or call 'async.TryFinally' directly

[<Obsolete
  ("Consider using 'async { do! Async.SwitchToNewThread() ... }' instead")>]
member UnblockedPrimitive : (unit -> 'a) -> Async<'a>

Note: Consider using 'async { do! Async.SwitchToNewThread() ... }' instead

Run a primitive blocking operation on a brand new thread. Execute the continuation as a worker item in the thread pool.
[<Obsolete
  ("Consider using 'async { use x = ... }' instead, or call 'async.Using' directly")>]
member Using : 'b * ('b -> Async<'a>) -> Async<'a> when 'b :> IDisposable

Note: Consider using 'async { use x = ... }' instead, or call 'async.Using' directly

See Also

Microsoft.FSharp.Control


Documentation for assembly FSharp.Core, version 1.9.4.19, generated using F# version 1.9.4.19