Boundaries

Examples using tasks import the .NET types and construct a graph with a manual dispatcher:

open System
open System.Threading
open System.Threading.Tasks
open Ranvier

let newGraph () =
    new Graph ({ GraphOptions.Default with Dispatcher = Some (ManualDispatcher () :> IGraphDispatcher) })

When a completion arrives from another thread, pump the graph on its owning thread. See Threading and dispatch and the pumpUntil helper in Testing async state.

A boundary supplies a value when its body is pending or fails. Its readers see that fallback or recovered value instead of the state it handles. Choose the value to suit your UI or computation.

The body always re-runs from the start. The suspended read linked its edge before throwing, so the source settling wakes the boundary.

All three return a Boundary<'T>. IsWaiting is true while a fallback stands in for the body, and Caught holds the exception a recover handled on the current run, or null. Both are tracked reads that bring the boundary current, so an effect reading only IsWaiting wakes when the body settles.

Stale while refreshing, and empty versus not yet known

A fallback receives the boundary's last value, ValueNone before the first. A fallback that returns it keeps the last result on screen while a new flight is in progress, and IsWaiting reports the refresh. Choose a value type that separates a result not known yet from a result that is empty:

type Results =
    | NotYetKnown
    | Loaded of string list

let searchGraph = newGraph ()
let query = searchGraph.Run (fun () -> createSignal "a")
let replies = ResizeArray<TaskCompletionSource<string list>> ()

let hits =
    searchGraph.Run (fun () ->
        createAsync (fun _ _ ->
            query.Value |> ignore // tracked: read before the first await
            let reply = TaskCompletionSource<string list> ()
            replies.Add reply
            reply.Task))

let results =
    searchGraph.Run (fun () ->
        createSuspense (fun last -> ValueOption.defaultValue NotYetKnown last) (fun () -> Loaded hits.Value))

let snapshot () = results.Value, results.IsWaiting

let unknown = snapshot ()
replies[0].SetResult []
let empty = snapshot ()
query.Value <- "ab"
let refreshing = snapshot ()
replies[1].SetResult [ "abc" ]
unknown, empty, refreshing, snapshot ()

((NotYetKnown, true), (Loaded [], false), (Loaded [], true), (Loaded ["abc"], false))

createSuspense

The boundary shows the fallback while the body is pending, and shows the body's value once every source the body waited on has settled. A failure passes through as Failed.

let viewGraph = newGraph ()
let data = viewGraph.Run (fun () -> createAsyncSource<string> ())

let view =
    viewGraph.Run (fun () -> createSuspense (fun () -> "loading") (fun () -> "loaded " + data.Value))

let waiting = view.TryValue, view.IsWaiting, view.Status
data.Settle "report"
waiting, (view.TryValue, view.IsWaiting)

((Ready "loading", true, None), (Ready "loaded report", false))

In the map, the effect reads view and runs with the fallback while data is pending. Settle runs the body again with the value; Fail passes the failure through the boundary to the effect.

createErrorBoundary

The boundary shows recover ex when the body throws, and shows the body's value again when a source the body read changes and the re-run succeeds. A pending body passes through as Pending.

Enter an invalid integer, then a valid one. The boundary displays its recovery value and later returns to the parsed value without rebuilding the graph.

let parseGraph = newGraph ()
let input = parseGraph.Run (fun () -> createSignal "42")

let parsed =
    parseGraph.Run (fun () -> createErrorBoundary (fun _ -> -1) (fun () -> int input.Value))

input.Value <- "forty-two"
let recovered = parsed.TryValue, parsed.Caught.GetType().Name
input.Value <- "7"
recovered, (parsed.TryValue, isNull parsed.Caught)

((Ready -1, "FormatException"), (Ready 7, true))

createBoundary

The boundary catches both channels: fallback () while the body is pending, recover ex when it throws, and the body's value once it succeeds.

let bothGraph = newGraph ()
let feed = bothGraph.Run (fun () -> createAsyncSource<int> ())

let panel =
    bothGraph.Run (fun () -> createBoundary (fun () -> 0) (fun _ -> -1) (fun () -> feed.Value))

let loading = panel.TryValue
feed.Fail (exn "offline")
let broken = panel.TryValue
feed.Settle 9
loading, broken, panel.TryValue

(Ready 0, Ready -1, Ready 9)