How to use the runtime-async task builders
This guide shows how to use the runtime-async builders of IcedTasks: task, backgroundTask, valueTask, coldTask, backgroundColdTask, cancellableTask, backgroundCancellableTask, and cancellableValueTask.
In a runtime-async method, the .NET 11 runtime suspends and resumes the method. The F# compiler does not generate a state machine for the method. Runtime async is a preview feature of F# 11. For the design and the limits, see Runtime-async task builders.
Before you start
You must have:
- The .NET 11 SDK.
- A project that targets
net11.0or later. - A version of IcedTasks that contains the
net11.0build.
The program must run on .NET 11 or later.
1. Set up the project file
- Set the target framework to
net11.0. - Set
LangVersiontopreview. - Add the IcedTasks package.
|
The net11.0 build of IcedTasks depends on FSharp.Core 11.0.101 or later. The .NET 11 SDK gives this version by default. If your project sets an older FSharp.Core version, the restore stops with error NU1605. To correct the error, remove the version reference or set FSharp.Core 11.0.101 or later.
2. Open the namespace
Open IcedTasks.Polyfill.RuntimeTask in the module that must use the builders.
module Orders =
open System.IO
open IcedTasks.Polyfill.RuntimeTask
let readLength (path: string) =
task {
let! text = File.ReadAllTextAsync path
return text.Length
}
In this module, the eight builder names now give the runtime-async builders. The open replaces the FSharp.Core task and backgroundTask builders, and the IcedTasks builders with the same names. Code in other modules continues to use the builders that it opens.
If the module also opens IcedTasks, put open IcedTasks.Polyfill.RuntimeTask after it. The last open gives the builder names. A later open IcedTasks gives the state-machine valueTask, cold, and cancellable builders again.
Put the open in a module, not at the top of a large file. Then the reader can see which code uses runtime async.
Always open the namespace. Most Source members of the builders are extension members in the namespace, so they work only after the open. If you write the full name of a builder without the open, only the Source members on the builder type work. For task, only binds of Task<'T> work:
open System.Threading.Tasks
let answer () =
IcedTasks.Polyfill.RuntimeTask.RuntimeTasks.task {
let! value = Task.FromResult 41
return value + 1
}
A bind of a Task, a ValueTask, or an Async in that expression stops with error FS0193. To keep the open small, put the code in its own module.
3. Write the computation expressions
Write the computation expressions as you write them with the other task builders.
module Orders =
open System.Collections.Generic
open System.IO
open System.Threading.Tasks
open IcedTasks.Polyfill.RuntimeTask
let readBoth (first: string) (second: string) =
task {
let! a = File.ReadAllTextAsync first
and! b = File.ReadAllTextAsync second
return a.Length + b.Length
}
let readOrEmpty (path: string) =
task {
try
return! File.ReadAllTextAsync path
with :? FileNotFoundException ->
return ""
}
let copyLines (lines: IAsyncEnumerable<string>) (path: string) =
backgroundTask {
use writer = new StreamWriter(path)
for line in lines do
do! writer.WriteLineAsync line
}
let getCached (cache: Dictionary<string, string>) (load: string -> Task<string>) (key: string) =
valueTask {
match cache.TryGetValue key with
| true, value -> return value
| false, _ ->
let! value = load key
cache[key] <- value
return value
}
let addOne (work: Async<int>) =
task {
let! value = work
return value + 1
}
The builders accept these values in let!, do!, return!, and and!:
Task<'T>,Task,ValueTask<'T>, andValueTask.Async<'T>. The builder starts it withAsync.StartImmediateAsTask.- A cold task,
unit -> Task<'T>orunit -> Task. The builder starts it. - An awaiter or an awaitable value, for example
Task.Yield(). - A function that returns an awaiter, for example
unit -> TaskAwaiter<'T>. The cancellable builders also acceptCancellationToken -> TaskAwaiter<'T>.
use and use! dispose IAsyncDisposable and IDisposable values. for works with seq<'T> and IAsyncEnumerable<'T>.
Use backgroundTask for library code that must not continue on the caller SynchronizationContext. For and! order and failure rules, see Runtime-async task builders.
4. Write cold and cancellable computations
Use coldTask for work that must not start until the caller calls it. Use cancellableTask or cancellableValueTask when the caller gives a CancellationToken.
module Downloads =
open System.Net.Http
open System.Threading
open System.Threading.Tasks
open IcedTasks
open IcedTasks.Polyfill.RuntimeTask
let getText (client: HttpClient) (url: string) =
cancellableTask {
let! ct = CancellableTask.getCancellationToken ()
return! client.GetStringAsync(url, ct)
}
let getBoth (client: HttpClient) (first: string) (second: string) =
cancellableTask {
let! a = getText client first
and! b = getText client second
return a.Length + b.Length
}
let loadOnce (load: unit -> Task<string>) =
coldTask {
let! text = load ()
return text.Trim()
}
getText client urlreturnsCancellationToken -> Task<string>. The caller starts it with a token:getText client url ct.- In
getBoth, the builder gives the ambient token to both calls ofgetText. It starts both calls before it awaits the first one. - The builder checks the token before each
let!,do!,return!, andand!. If the caller cancels the token, the task is cancelled at the next check, or when an operation that uses the token stops. loadOnce loadreturnsunit -> Task<string>. Each call runs the computation again.
CancellableTask.getCancellationToken comes from the IcedTasks namespace. The runtime-async builders bind it as they bind any CancellationToken -> ValueTask<'T> value.
5. Target net10.0 and net11.0 in one project
You can build one project for net10.0 and net11.0.
- Set
TargetFrameworksto the two frameworks. - Set
LangVersiontopreviewonly fornet11.0.
|
You do not need #if around the open. A net10.0 project gets the net9.0 build of IcedTasks. In that build, the namespace IcedTasks.Polyfill.RuntimeTask is empty. Thus, the same code uses the state-machine builders on net10.0 and the runtime-async builders on net11.0. On net10.0, task and backgroundTask come from FSharp.Core, and the other builder names come from IcedTasks.
6. Make sure that a method is runtime async
The compiler sets MethodImplAttributes.Async on the method that runs the computation expression. To examine the flag, read it in the body:
open System.Reflection
open IcedTasks.Polyfill.RuntimeTask
let isRuntimeAsync () =
task {
let method = MethodBase.GetCurrentMethod()
return method.MethodImplementationFlags.HasFlag MethodImplAttributes.Async
}
On net11.0, the task from isRuntimeAsync () gives true in Debug and Release builds. In a net10.0 build, the same task gives false, because the code uses the FSharp.Core task builder.
You can also examine the IL. In the IL view of ILSpy 9.1, the method header of a runtime-async method shows cil managed flag(2000). The value 0x2000 is MethodImplAttributes.Async.
Troubleshooting
Error or result |
Cause |
Correction |
|---|---|---|
|
|
Set |
|
In Debug, this error comes with FS3350. |
Correct FS3350. |
|
The project sets a FSharp.Core version older than 11.0.101. |
Use FSharp.Core 11.0.101 or later. |
|
The code writes |
Open the namespace. |
|
The extension |
Open the namespace. |
A function name is missing from a stack trace in a Release build. |
The optimizer moved a small function into its caller. |
Put |
Related
- Runtime-async task builders explains the design, the
and!rules, and the limits. - Polyfill namespaces and shadowing explains how a polyfill namespace replaces builder names.
- Use background builders to avoid caller context explains
backgroundTask.
val string: value: 'T -> string
--------------------
type string = System.String
type Async = static member AsBeginEnd: computation: ('Arg -> Async<'T>) -> ('Arg * AsyncCallback * obj -> IAsyncResult) * (IAsyncResult -> 'T) * (IAsyncResult -> unit) static member AwaitEvent: event: IEvent<'Del,'T> * ?cancelAction: (unit -> unit) -> Async<'T> (requires delegate and 'Del :> Delegate) 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 * obj -> 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 int: value: 'T -> int (requires member op_Explicit)
--------------------
type int = int32
--------------------
type int<'Measure> = int
IcedTasks