Development documentation · Some APIs may be unreleased Published release →

Guides

Tasks and async

A Task<T> represents an operation and its eventual result. It does not imply a thread. Use await to continue when the operation completes, including in Main. Import System.Concurrency.Tasks.* for Task and Promise.

Start and await work

import System.*
import System.Concurrency.Tasks.*

async func Main() -> Task<()> {
    await Task.Run(() => Console.WriteLine("completed"))
    return ()
}

This prints completed. Task.Run submits work and returns its completion task. A value-producing callback returns Task<T>; a task-producing callback is unwrapped. Captured objects retain their identity, so shared updates need coordination.

Download the example · Supported entry points

Return a completed result

Task.CompletedTask provides an already successful Task<()>. Task.FromResult(42) creates a completed Task<int>. Neither schedules work. Use a Promise<T> when adapting an operation that will complete later: the producer completes or cancels the promise, while consumers receive its Task.

Expected errors and cancellation

Use Task<Result<T, E>> for an operation that can return an expected error. Await obtains the Result; ? propagates its error:

async func Read(input: Task<Result<int, string>>) -> Task<Result<int, string>> {
    let value = await input?
    return Ok(value + 1)
}

await input? awaits first and then propagates; (await input)? is also valid. Cancellation is a distinct task outcome, never Result.Failure. A runtime Fault is terminal and cannot be recovered through Task. This differs from .NET's faulted Task.

Complete propagation example · Optional and Result

Request cancellation

System.Concurrency.CancellationTokenSource owns cancellation authority. Pass its Token to cooperating I/O; CancellationToken.None makes no cancellation request. Requesting cancellation does not mean the operation has stopped. It must finish resource cleanup before acknowledging cancellation. An already completed Task keeps its result. Dispose token registrations and sources when their lifetimes end.

For HTTP, configure HttpClient.Timeout before sending. Timers and cancellation require scheduler progress; they cannot preempt arbitrary synchronous work.

Execution and resource lifetime

The runtime chooses how submitted work executes. The current Task.Run backend can progress other contexts during a blocked host call, but it does not promise parallel execution of arbitrary guest CPU code. Entry completion drains pending work.

The native compiler supports await in functions, class methods and ordinary for loops, with locals and cleanup retained across suspension. The SDK selects runtime-await and supplies private providers for async functions and generators. Native suspension supports macOS ARM64 and Windows x64 with matching runtime/JIT helpers. Compiler state machines remain an explicit project option. This does not promise parallel guest execution or unrestricted portable green threads.

Read further