If an exception occurs in the asynchronous computation then an exception is re-raised by this function. If no cancellation token is provided then the default cancellation token is used. The computation is started on the current thread if SynchronizationContext.Current is null, Thread.CurrentThread has Thread.IsThreadPoolThread of true, and no timeout is specified. Otherwise the computation is started by queueing a new work item in the thread pool, and the current thread is blocked awaiting the completion of the computation. The timeout parameter is given in milliseconds. A value of -1 is equivalent to Timeout.Infinite.

computation : Async<'T>

The computation to run.

?timeout : int

The amount of time in milliseconds to wait for the result of the computation before raising a TimeoutException. If no value is provided for timeout then a default of -1 is used to correspond to Timeout.Infinite.

?cancellationToken : CancellationToken

The cancellation token to be associated with the computation. If one is not supplied, the default cancellation token is used.

Returns: 'T

The result of the computation.

Example

 printfn "A"

 let result = async {
     printfn "B"
     do! Async.Sleep(1000)
     printfn "C"
     17
 } |> Async.RunSynchronously

 printfn "D"

If no cancellation token is provided then the default cancellation token is used.

computation : Async<unit>

The computation to run asynchronously.

?cancellationToken : CancellationToken

The cancellation token to be associated with the computation. If one is not supplied, the default cancellation token is used.

Example

 printfn "A"

 async {
     printfn "B"
     do! Async.Sleep(1000)
     printfn "C"
 } |> Async.Start

 printfn "D"

If no cancellation token is provided then the default cancellation token is used.

computation : Async<'T>

?taskCreationOptions : TaskCreationOptions

?cancellationToken : CancellationToken

Returns: Task<'T>

A Task that will be completed in the corresponding state once the computation terminates (produces the result, throws exception or gets canceled)

Example

 printfn "A"

 let t =
     async {
         printfn "B"
         do! Async.Sleep(1000)
         printfn "C"
     } |> Async.StartAsTask

 printfn "D"
 t.Wait()
 printfn "E"

computation : Async<'T>

?taskCreationOptions : TaskCreationOptions

Returns: Async<Task<'T>>

If no cancellation token is provided then the default cancellation token is used.

computation : Async<unit>

The asynchronous computation to execute.

?cancellationToken : CancellationToken

The CancellationToken to associate with the computation. The default is used if this parameter is not provided.

Example

 printfn "A"

 async {
     printfn "B"
     do! Async.Sleep(1000)
     printfn "C"
 } |> Async.StartImmediate

 printfn "D"

If no cancellation token is provided then the default cancellation token is used. You may prefer using this method if you want to achieve a similar behavior to async await in C# as async computation starts on the current thread with an ability to return a result.

computation : Async<'T>

The asynchronous computation to execute.

?cancellationToken : CancellationToken

The CancellationToken to associate with the computation. The default is used if this parameter is not provided.

Returns: Task<'T>

A Task that will be completed in the corresponding state once the computation terminates (produces the result, throws exception or gets canceled)

Example

 printfn "A"

 let t =
     async {
         printfn "B"
         do! Async.Sleep(1000)
         printfn "C"
     } |> Async.StartImmediateAsTask

 printfn "D"
 t.Wait()
 printfn "E"

If no cancellation token is provided then the default cancellation token is used.

computation : Async<'T>

The asynchronous computation to execute.

continuation : 'T -> unit

The function called on success.

exceptionContinuation : exn -> unit

The function called on exception.

cancellationContinuation : OperationCanceledException -> unit

The function called on cancellation.

?cancellationToken : CancellationToken

The CancellationToken to associate with the computation. The default is used if this parameter is not provided.

If any child computation raises an exception, then the overall computation will trigger an exception, and cancel the others. The overall computation will respond to cancellation while executing the child computations. If cancelled, the computation will cancel any remaining child computations but will still wait for the other child computations to complete.

computations : Async<'T option> seq

A sequence of computations to be parallelized.

Returns: Async<'T option>

A computation that returns the first succeeding computation.

Example

 printfn "Starting"
 let primes = [ 2; 3; 5; 7 ]
 let computations =
     [ for i in primes do
         async {
             do! Async.Sleep(System.Random().Next(1000, 2000))
             return if i % 2 > 0 then Some(i) else None
         }
     ]

 computations
 |> Async.Choice
 |> Async.RunSynchronously
 |> function
     | Some (i) -> printfn $"{i}"
     | None -> printfn "No Result"

Example

 let primes = [ 2; 3; 5; 7 ]
 let computations =
     [ for i in primes do
         async {
             do! Async.Sleep(System.Random().Next(1000, 2000))

             return
                 if i % 2 > 0 then
                     Some(i)
                 else
                     failwith $"Even numbers not supported: {i}"
         }
     ]

 computations
 |> Async.Choice
 |> Async.RunSynchronously
 |> function
     | Some (i) -> printfn $"{i}"
     | None -> printfn "No Result"

callback : ('T -> unit) * (exn -> unit) * (OperationCanceledException -> unit) -> unit

The function that accepts the current success, exception, and cancellation continuations.

Returns: Async<'T>

An asynchronous computation that provides the callback with the current continuations.

Example

 let someRiskyBusiness() =
 match DateTime.Today with
 | dt when dt.DayOfWeek = DayOfWeek.Monday -> failwith "Not compatible with Mondays"
 | dt -> dt
 
 let computation =
     (fun (successCont, exceptionCont, cancellationCont) ->
         try
             someRiskyBusiness () |> successCont
         with
         | :? OperationCanceledException as oce -> cancellationCont oce
         | e -> exceptionCont e)
     |> Async.FromContinuations

 Async.StartWithContinuations(
     computation,
     (fun result -> printfn $"Result: {result}"),
     (fun e -> printfn $"Exception: {e}"),
     (fun oce -> printfn $"Cancelled: {oce}")
  )

computation : Async<'T>

The input computation.

Returns: Async<unit>

A computation that is equivalent to the input computation, but disregards the result.

Example

 let readFile filename numBytes =
     async {
         use file = System.IO.File.OpenRead(filename)
         printfn "Reading from file %s." filename
         // Throw away the data being read.
         do! file.AsyncRead(numBytes) |> Async.Ignore
     }
 readFile "example.txt" 42 |> Async.Start

If all child computations succeed, an array of results is passed to the success continuation. If any child computation raises an exception, then the overall computation will trigger an exception, and cancel the others. The overall computation will respond to cancellation while executing the child computations. If cancelled, the computation will cancel any remaining child computations but will still wait for the other child computations to complete.

computations : Async<'T> seq

A sequence of distinct computations to be parallelized.

?maxDegreeOfParallelism : int

The maximum degree of parallelism in the parallel execution.

Returns: Async<'T array>

A computation that returns an array of values from the sequence of input computations.

Example

 let primes = [ 2; 3; 5; 7; 10; 11 ]
 let computations =
     [ for i in primes do
         async {
             do! Async.Sleep(System.Random().Next(1000, 2000))

             return
                 if i % 2 > 0 then
                     printfn $"{i}"
                     true
                 else
                     false
         } ]

 let t =
     Async.Parallel(computations, maxDegreeOfParallelism=3)
     |> Async.StartAsTask

 t.Wait()
 printfn $"%A{t.Result}"

If all child computations succeed, an array of results is passed to the success continuation. If any child computation raises an exception, then the overall computation will trigger an exception, and cancel the others. The overall computation will respond to cancellation while executing the child computations. If cancelled, the computation will cancel any remaining child computations but will still wait for the other child computations to complete.

computations : Async<'T> seq

A sequence of distinct computations to be parallelized.

Returns: Async<'T array>

A computation that returns an array of values from the sequence of input computations.

Example

 let primes = [ 2; 3; 5; 7; 10; 11 ]
 let t =
     [ for i in primes do
         async {
             do! Async.Sleep(System.Random().Next(1000, 2000))

             if i % 2 > 0 then
                 printfn $"{i}"
                 return true
             else
                 return false
         }
     ]
     |> Async.Parallel
     |> Async.StartAsTask

 t.Wait()
 printfn $"%A{t.Result}"

If all child computations succeed, an array of results is passed to the success continuation. If any child computation raises an exception, then the overall computation will trigger an exception, and cancel the others. The overall computation will respond to cancellation while executing the child computations. If cancelled, the computation will cancel any remaining child computations but will still wait for the other child computations to complete.

computations : Async<'T> seq

A sequence of distinct computations to be run in sequence.

Returns: Async<'T array>

A computation that returns an array of values from the sequence of input computations.

Example

 let primes = [ 2; 3; 5; 7; 10; 11 ]
 let computations =
     [ for i in primes do
             async {
                 do! Async.Sleep(System.Random().Next(1000, 2000))

                 if i % 2 > 0 then
                     printfn $"{i}"
                     return true
                 else
                     return false
             }
    ]

 let t =
     Async.Sequential(computations)
     |> Async.StartAsTask

 t.Wait()
 printfn $"%A{t.Result}"

The computation will respond to cancellation while waiting for the event. If a cancellation occurs, and cancelAction is specified, then it is executed, and the computation continues to wait for the event. If cancelAction is not specified, then cancellation causes the computation to cancel immediately.

event : IEvent<'Del, 'T>

The event to handle once.

?cancelAction : unit -> unit

An optional function to execute instead of cancelling when a cancellation is issued.

Returns: Async<'T>

An asynchronous computation that waits for the event to be invoked.

The computation returns true if the handle indicated a result within the given timeout.

iar : IAsyncResult

The IAsyncResult to wait on.

?millisecondsTimeout : int

The timeout value in milliseconds. If one is not provided then the default value of -1 corresponding to Timeout.Infinite.

Returns: Async<bool>

An asynchronous computation that waits on the given IAsyncResult.

If an exception occurs in the asynchronous computation then an exception is re-raised by this function. If the task is cancelled then Tasks.TaskCanceledException is raised. Note that the task may be governed by a different cancellation token to the overall async computation where the AwaitTask occurs. In practice you should normally start the task with the cancellation token returned by let! ct = Async.CancellationToken, and catch any Tasks.TaskCanceledException at the point where the overall async is started.

task : Task

The task to await.

Returns: Async<unit>

If an exception occurs in the asynchronous computation then an exception is re-raised by this function. If the task is cancelled then Tasks.TaskCanceledException is raised. Note that the task may be governed by a different cancellation token to the overall async computation where the AwaitTask occurs. In practice you should normally start the task with the cancellation token returned by let! ct = Async.CancellationToken, and catch any Tasks.TaskCanceledException at the point where the overall async is started.

task : Task<'T>

The task to await.

Returns: Async<'T>

The computation returns true if the handle indicated a result within the given timeout.

waitHandle : WaitHandle

The WaitHandle that can be signalled.

?millisecondsTimeout : int

The timeout value in milliseconds. If one is not provided then the default value of -1 corresponding to Timeout.Infinite.

Returns: Async<bool>

An asynchronous computation that waits on the given WaitHandle.

dueTime : TimeSpan

The amount of time to sleep.

Returns: Async<unit>

An asynchronous computation that will sleep for the given time.

Example

 async {
     printfn "A"
     do! Async.Sleep(TimeSpan(0, 0, 1))
     printfn "B"
 } |> Async.Start
 printfn "C"

millisecondsDueTime : int

The number of milliseconds to sleep.

Returns: Async<unit>

An asynchronous computation that will sleep for the given time.

Example

 async {
     printfn "A"
     do! Async.Sleep(1000)
     printfn "B"
 } |> Async.Start

 printfn "C"

Example

 let primes = [ 2; 3; 5; 7; 11 ]

 let computations =
     [ for i in primes do
             async {
                 do! Async.Sleep(i * 1000)
                 printfn $"{i}"
             }
     ]

 try
     let t =
         Async.Parallel(computations, 3) |> Async.StartAsTask

     Thread.Sleep(6000)
     Async.CancelDefaultToken()
     printfn $"Tasks Finished: %A{t.Result}"
 with
 | :? System.AggregateException as ae -> printfn $"Tasks Not Finished: {ae.Message}"

In async { let! token = Async.CancellationToken ...} token can be used to initiate other asynchronous operations that will cancel cooperatively with this workflow.

Returns: Async<CancellationToken>

An asynchronous computation capable of retrieving the CancellationToken from a computation expression.

computation : Async<'T>

The input computation that returns the type T.

Returns: Async<Choice<'T, exn>>

A computation that returns a choice of type T or exception.

Example

 let someRiskyBusiness() =
 match DateTime.Today with
 | dt when dt.DayOfWeek = DayOfWeek.Monday -> failwith "Not compatible with Mondays"
 | dt -> dt
 
 async { return someRiskyBusiness() }
 |> Async.Catch
 |> Async.RunSynchronously
 |> function
     | Choice1Of2 result -> printfn $"Result: {result}"
     | Choice2Of2 e -> printfn $"Exception: {e}"

Returns: CancellationToken

The default CancellationToken.

Example

 Async.DefaultCancellationToken.Register(fun () -> printfn "Computation Cancelled") |> ignore
 let primes = [ 2; 3; 5; 7; 11 ]

 for i in primes do
     async {
         do! Async.Sleep(i * 1000)
         printfn $"{i}"
     }
     |> Async.Start

 Thread.Sleep(6000)
 Async.CancelDefaultToken()
 printfn "Tasks Finished"

For example, async { use! holder = Async.OnCancel interruption ... } 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 interruption is executed on the thread that is performing the cancellation. This can be used to arrange for a computation to be asynchronously notified that a cancellation has occurred, e.g. by setting a flag, or deregistering a pending I/O action.

interruption : unit -> unit

The function that is executed on the thread performing the cancellation.

Returns: Async<IDisposable>

An asynchronous computation that triggers the interruption if it is cancelled before being disposed.

Example

 let primes = [ 2; 3; 5; 7; 11 ]
 for i in primes do
     async {
         use! holder = Async.OnCancel(fun () -> printfn $"Computation Cancelled: {i}")
         do! Async.Sleep(i * 1000)
         printfn $"{i}"
     }
     |> Async.Start

 Thread.Sleep(6000)
 Async.CancelDefaultToken()
 printfn "Tasks Finished"

This method should normally be used as the immediate right-hand-side of a let! binding in an F# asynchronous workflow, that is,

     async { ...
            let! completor1 = childComputation1 |> Async.StartChild  
            let! completor2 = childComputation2 |> Async.StartChild  
            ... 
            let! result1 = completor1 
            let! result2 = completor2 
            ... }

computation : Async<'T>

The child computation.

?millisecondsTimeout : int

The timeout value in milliseconds. If one is not provided then the default value of -1 corresponding to Timeout.Infinite.

Returns: Async<Async<'T>>

A new computation that waits for the input computation to finish.

Example

 let computeWithTimeout timeout =
     async {
         let! completor1 =
             Async.StartChild(
                 (async {
                     do! Async.Sleep(1000)
                     return 1
                  }),
                 millisecondsTimeout = timeout)

         let! completor2 =
             Async.StartChild(
                 (async {
                     do! Async.Sleep(2000)
                     return 2
                  }),
                 millisecondsTimeout = timeout)

         let! v1 = completor1
         let! v2 = completor2
         printfn $"Result: {v1 + v2}"
     } |> Async.RunSynchronously

computation : Async<'T>

The input asynchronous computation.

compensation : OperationCanceledException -> unit

The function to be run if the computation is cancelled.

Returns: Async<'T>

An asynchronous computation that runs the compensation if the input computation is cancelled.

Example

 let primes = [ 2; 3; 5; 7; 11 ]
 for i in primes do
     Async.TryCancelled(
         async {
             do! Async.Sleep(i * 1000)
             printfn $"{i}"
         },
         fun oce -> printfn $"Computation Cancelled: {i}")
     |> Async.Start

 Thread.Sleep(6000)
 Async.CancelDefaultToken()
 printfn "Tasks Finished"

syncContext : SynchronizationContext

The synchronization context to accept the posted computation.

Returns: Async<unit>

An asynchronous computation that uses the syncContext context to execute.

Returns: Async<unit>

A computation that will execute on a new thread.

Example

 async {
     do! Async.SwitchToNewThread()
     do! someLongRunningComputation()
 } |> Async.StartImmediate

Returns: Async<unit>

A computation that generates a new work item in the thread pool.

Example

 async {
     do! Async.SwitchToNewThread()
     do! someLongRunningComputation()
     do! Async.SwitchToThreadPool()

     for i in 1 .. 10 do
         do! someShortRunningComputation()
 } |> Async.StartImmediate

computation : 'Arg -> Async<'T>

A function generating the asynchronous computation to split into the traditional .NET Asynchronous Programming Model.

Returns: ('Arg * AsyncCallback * objnull -> IAsyncResult) * (IAsyncResult -> 'T) * (IAsyncResult -> unit)

A tuple of the begin, end, and cancel members.

The computation will respond to cancellation while waiting for the completion of the operation. If a cancellation occurs, and cancelAction is specified, then it is executed, and the computation continues to wait for the completion of the operation. If cancelAction is not specified, then cancellation causes the computation to stop immediately, and subsequent invocations of the callback are ignored.

arg1 : 'Arg1

The first argument for the operation.

arg2 : 'Arg2

The second argument for the operation.

arg3 : 'Arg3

The third argument for the operation.

beginAction : 'Arg1 * 'Arg2 * 'Arg3 * AsyncCallback * objnull -> IAsyncResult

The function initiating a traditional CLI asynchronous operation.

endAction : IAsyncResult -> 'T

The function completing a traditional CLI asynchronous operation.

?cancelAction : unit -> unit

An optional function to be executed when a cancellation is requested.

Returns: Async<'T>

An asynchronous computation wrapping the given Begin/End functions.

The computation will respond to cancellation while waiting for the completion of the operation. If a cancellation occurs, and cancelAction is specified, then it is executed, and the computation continues to wait for the completion of the operation. If cancelAction is not specified, then cancellation causes the computation to stop immediately, and subsequent invocations of the callback are ignored.

arg1 : 'Arg1

The first argument for the operation.

arg2 : 'Arg2

The second argument for the operation.

beginAction : 'Arg1 * 'Arg2 * AsyncCallback * objnull -> IAsyncResult

The function initiating a traditional CLI asynchronous operation.

endAction : IAsyncResult -> 'T

The function completing a traditional CLI asynchronous operation.

?cancelAction : unit -> unit

An optional function to be executed when a cancellation is requested.

Returns: Async<'T>

An asynchronous computation wrapping the given Begin/End functions.

The computation will respond to cancellation while waiting for the completion of the operation. If a cancellation occurs, and cancelAction is specified, then it is executed, and the computation continues to wait for the completion of the operation. If cancelAction is not specified, then cancellation causes the computation to stop immediately, and subsequent invocations of the callback are ignored.

arg : 'Arg1

The argument for the operation.

beginAction : 'Arg1 * AsyncCallback * objnull -> IAsyncResult

The function initiating a traditional CLI asynchronous operation.

endAction : IAsyncResult -> 'T

The function completing a traditional CLI asynchronous operation.

?cancelAction : unit -> unit

An optional function to be executed when a cancellation is requested.

Returns: Async<'T>

An asynchronous computation wrapping the given Begin/End functions.

The computation will respond to cancellation while waiting for the completion of the operation. If a cancellation occurs, and cancelAction is specified, then it is executed, and the computation continues to wait for the completion of the operation. If cancelAction is not specified, then cancellation causes the computation to stop immediately, and subsequent invocations of the callback are ignored.

beginAction : AsyncCallback * objnull -> IAsyncResult

The function initiating a traditional CLI asynchronous operation.

endAction : IAsyncResult -> 'T

The function completing a traditional CLI asynchronous operation.

?cancelAction : unit -> unit

An optional function to be executed when a cancellation is requested.

Returns: Async<'T>

An asynchronous computation wrapping the given Begin/End functions.