Async.RunSynchronously<'T> Method (F#)

Article
04/03/2013

Runs the provided asynchronous computation and awaits its result.

Namespace/Module Path: Microsoft.FSharp.Control

Assembly: FSharp.Core (in FSharp.Core.dll)

// Signature:
static member RunSynchronously : Async<'T> * ?int * ?CancellationToken -> 'T

// Usage:
Async.RunSynchronously (computation)
Async.RunSynchronously (computation, timeout = timeout, cancellationToken = cancellationToken)

Parameters

computation
Type: Async<'T>

The computation to run.
timeout
Type: 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 Infinite.
cancellationToken
Type: CancellationToken

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

Return Value

The result of the computation.

Remarks

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 timeout parameter is given in milliseconds. A value of -1 is equivalent to Infinite.

If you provide a cancellation token, the timeout is ignored. Instead, you can implement your own timeout by canceling the operation.

Async.RunSynchronously should not be used on the main thread in asynchronous programming environments, such as in Silverlight-based applications.

Example

The following example shows how to use Async.RunSynchronously to run an asynchronous computation created by using Async.Parallel, with no timeout.

let bufferData (number:int) =
    [| for count in 1 .. 1000 -> byte (count % 256) |]
    |> Array.permute (fun index -> index)

let writeFile fileName bufferData =
    async {
      use outputFile = System.IO.File.Create(fileName)
      do! outputFile.AsyncWrite(bufferData) 
    }

Seq.init 1000 (fun num -> bufferData num)
|> Seq.mapi (fun num value -> writeFile ("file" + num.ToString() + ".dat") value)
|> Async.Parallel
|> Async.RunSynchronously
|> ignore

The following example shows how to use Async.RunSynchronously with a timeout.

let bufferData (number:int) =
    [| for i in 1 .. 1000 -> byte (i % 256) |]
    |> Array.permute (fun index -> index)

// Create a counter as a reference cell that can be modified in parallel. 
let counter = ref 0

// writeFileInner writes the data to an open stream 
// that represents the file. It also updates the counter. 

// The counter is locked because it will be accessed by 
// multiple asynchronous computations. 

// The counter must be updated as soon as the 
// AsyncWrite completes, in the same synchronous 
// program flow. There must not be a let! or do! between 
// the AsyncWrite call and the counter update. 
let writeFileInner (stream:System.IO.Stream) data =
    let result = stream.AsyncWrite(data)
    lock counter (fun () -> counter := !counter + 1)
    result

// writeFile encapsulates the asynchronous write operation. 
// The do! includes both the file I/O operation and the 
// counter update in order to keep those operations 
// together. 
let writeFile fileName bufferData =
    async {
      use outputFile = System.IO.File.Create(fileName)
      do! writeFileInner outputFile bufferData
      // Updating the counter here would not be effective.
    }

let async1 = Seq.init 1000 (fun num -> bufferData num)
             |> Seq.mapi (fun num value ->
                 writeFile ("file" + num.ToString() + ".dat") value)
             |> Async.Parallel
try
    Async.RunSynchronously(async1, 100) |> ignore
with
   | exc -> printfn "%s" exc.Message
            printfn "%d write operations completed successfully." !counter

Sample Output

The operation has timed out.

420 write operations completed successfully.

Platforms

Windows 8, Windows 7, Windows Server 2012, Windows Server 2008 R2

Version Information

F# Core Library Versions

Supported in: 2.0, 4.0, Portable