.FS File Format – Computation expressions

The keywords

The documentation also lists the method Delay (wraps the rest of a block as a function), Run (executes the whole computation), BindReturn and BindNReturn (efficient let! … return), Quote (gets the block as a quotation) and the pairs ReturnFromFinal and YieldFromFinal (F# 10, tail calls). An empty body builder { } is allowed from F# 9 and calls Zero.

The four built-in kinds

// a sequence: lazy, with yield
let evens = seq { for i in 1 .. 10 do if i % 2 = 0 then yield i }
let squares = [ for i in 1 .. 3 -> i * i ]       // list and array comprehensions use the same forms

// async: a cold computation run later
let fetchLength (url: string) : Async<int> =
    async {
        use client = new System.Net.Http.HttpClient()
        let! html = client.GetStringAsync(url) |> Async.AwaitTask
        return html.Length
    }
let n = fetchLength "https://example.org" |> Async.RunSynchronously

// task: a hot .NET Task, started at once (F# 6)
let work () : System.Threading.Tasks.Task<int> =
    task {
        let! a = System.Threading.Tasks.Task.FromResult 1
        and! b = System.Threading.Tasks.Task.FromResult 2   // and! in task: F# 10
        return a + b
    }

// query: operators over IQueryable and sequences
let adults =
    query {
        for p in people do
        where (p.Age >= 18)
        sortBy p.Name
        select p.Name
    }

• Sequence expressions seq { … }, and list and array expressions [ … ] and [| … |], are lazy (the sequence form) or eager (the others); yield is optional when the value is on its own (implicit yields, F# 4.7).
• async { … } builds an Async<'T> that does nothing until run with Async.RunSynchronously, Async.Start, Async.StartImmediate or similar; Async.Parallel combines several; Async.AwaitTask and Async.StartAsTask convert from and to tasks. It carries a cancellation token implicitly.
• task { … } (F# 6) builds a .NET Task<'T> that starts to run at once up to its first await; it does not propagate a cancellation token implicitly and does not support asynchronous tail calls (a recursive return! can overflow the stack unless it waits in between). backgroundTask { … } runs on the thread pool; a task block can be made a ValueTask with |> ValueTask<int>.
• query { … } translates to LINQ. Its operators are custom operations: all averageBy averageByNullable contains count distinct exactlyOne exactlyOneOrDefault exists find groupBy groupJoin groupValBy head headOrDefault join last lastOrDefault leftOuterJoin maxBy maxByNullable minBy minByNullable nth select skip skipWhile sortBy sortByDescending sortByNullable sortByNullableDescending sumBy sumByNullable take takeWhile thenBy thenByDescending thenByNullable thenByNullableDescending where.

Writing a builder

type MaybeBuilder() =
    member _.Bind(m: 'a option, f: 'a -> 'b option) =
        match m with
        | Some x -> f x
        | None -> None
    member _.Return(x) = Some x
    member _.ReturnFrom(m: 'a option) = m
    member _.Zero() = None

let maybe = MaybeBuilder()

let sum a b =
    maybe {
        let! x = Int32.TryParse a |> function true, v -> Some v | _ -> None
        let! y = Int32.TryParse b |> function true, v -> Some v | _ -> None
        return x + y
    }

type RetryBuilder(times: int) =
    member _.Bind(x, f) = f x
    member _.Return(x) = x
    [<CustomOperation("log", MaintainsVariableSpace = true)>]
    member _.Log(state, message: string) = printfn "%s" message; state

A custom operation is a builder method marked with [<CustomOperation("name")>]; the name becomes a keyword inside the block, as where and select are in query. F# 6 allows overloads of custom operations, and F# 9 a parameterless CustomOperationAttribute constructor. InlineIfLambda and resumable code (F# 6) let builder authors remove the overhead of closures; F# 11 adds a runtime-async mode for builder authors and reraise() inside the block.

In the viewer

The words with a bang are coloured as keywords with the bang included. async, seq, task, backgroundTask and query are coloured as library functions; the names of custom operations (where, select) and of your own builders are not known to the scanner and stay plain unless followed directly by a bracket.

Not described

Known, not yet covered

• Reference: the full translation rules of the specification (how Delay, Run, Combine and Zero are placed, return after and!, error cases), the rest of the async and task pages (cancellation, bounded concurrency, Async primitives in FSharp.Control.CommonExtensions), the MailboxProcessor and Event classes, resumable code, and the query operator semantics (what each operator does and the SQL comparison table) are not described.
• Reference: the list of builder methods and the translation table were taken from the documentation’s Computation Expressions page; the examples were written for this page and not compiled (the Int32.TryParse line needs open System).

See also

• The standard library – the Async, Seq and Option modules and the builders
• Lexical structure – the words with a bang