Axial
Repository F# setup
open System
open System.IO
open System.Threading
open System.Threading.Tasks
open Axial
open Axial.Layers
open Axial.Console
open Axial.FileSystem
open Axial.Hosting
open Axial.Hosting.Browser
open Axial.Hosting.Node
open Axial.PlatformService
open Axial.State
open Axial.Telemetry
open Axial.Telemetry.JavaScript

Deferred and Semaphore

Axial includes a small set of concurrency primitives only where they add Axial semantics over the .NET primitives underneath.

Use .NET Task, Channel<T>, SemaphoreSlim, and ConcurrentQueue<T> directly when raw platform behavior is enough. Use Axial primitives when coordination should preserve typed Exit and Cause, participate in workflow interruption, or release resources through the Flow model.

Deferred

Deferred<'error, 'value> is a one-shot handoff point between fibers. It can be completed once with a full Exit<'value, 'error>, so success, typed failure, defects, and interruption all remain visible to waiters.

Completion operations are idempotent. They return true to the caller that completed the deferred value and false to later callers.

Show page setup
// Setup for the checked examples on this page.
open System
open System.IO
open System.Threading
open System.Threading.Tasks
open Axial
open Axial.Layers
open Axial.Console
open Axial.FileSystem
open Axial.Hosting
open Axial.Hosting.Browser
open Axial.Hosting.Node
open Axial.PlatformService
open Axial.State
open Axial.Telemetry
open Axial.Telemetry.JavaScript
/// Fails the docs test when an example's result differs from the value shown.
let shouldEqual expected actual =
    if actual <> expected then failwithf "Expected %A but got %A" expected actual
Verified
let handoff : Flow<ClockEnvironment, string, int> =
    flow {
        let! deferred = Deferred.make<ClockEnvironment, string, int> ()

        let! waiter =
            Deferred.await deferred
            |> Flow.fork

        let! completed = Deferred.succeed 42 deferred
        let! value = Fiber.join waiter

        if completed then
            return value
        else
            return! Flow.fail "deferred was already completed"
    }

Use Deferred when a fiber needs to wait for a typed outcome produced elsewhere:

For a synchronous host callback, Deferred.completeNow returns bool immediately, without starting a Flow. The succeedNow, failNow, dieNow, and interruptNow forms build the corresponding Exit for you. Only one caller receives true; the callback that receives false did not replace the outcome already stored. The waiting fiber still uses Deferred.await.

Awaiting respects runtime cancellation. If the waiting workflow is interrupted before the deferred value is completed, the await returns Cause.Interrupt.

Semaphore

FlowSemaphore limits how many workflows can enter a section at the same time. The public API is intentionally scoped: use Semaphore.withPermit instead of raw acquire/release.

Verified
/// How many requests are running now, and the most that ever ran at once.
type Load = { Active: int; Busiest: int }

let runRequest (load: Ref<Load>) (request: int) : Flow<ClockEnvironment, string, int> =
    flow {
        do! load |> Ref.update (fun l -> { Active = l.Active + 1; Busiest = max l.Busiest (l.Active + 1) })
        do! Flow.sleep (TimeSpan.FromMilliseconds 5.0)
        do! load |> Ref.update (fun l -> { l with Active = l.Active - 1 })
        return request * 10
    }

let limitedFetch (semaphore: FlowSemaphore) (load: Ref<Load>) (request: int) : Flow<ClockEnvironment, string, int> =
    Semaphore.withPermit semaphore (
        flow {
            // Only one workflow per permit can run this section.
            return! runRequest load request
        })

Semaphore.withPermit releases the permit after success, typed failure, defect, or interruption. This is the important difference from manually calling WaitAsync and Release: permit cleanup follows the workflow outcome.

Create semaphores with a positive permit count:

Verified
let program : Flow<ClockEnvironment, string, int list * int> =
    flow {
        let! semaphore = Semaphore.make 2
        let! load = Ref.make { Active = 0; Busiest = 0 }
        let! results = [ 1..8 ] |> Flow.traversePar (Parallelism.bounded 8) (limitedFetch semaphore load)
        let! final = Ref.get load
        return results, final.Busiest
    }
Verified
match program |> Flow.run (ClockEnvironment Clock.live) with
| Exit.Success(results, busiest) ->
    results |> shouldEqual [ 10; 20; 30; 40; 50; 60; 70; 80 ]
    busiest <= 2 |> shouldEqual true
| other -> failwithf "Expected success, got %A" other

Eight workers ran, but never more than the two permits at once.

Zero permits are rejected because Axial does not expose an external raw release operation. A semaphore created with zero permits would be a permanently blocked handle rather than a useful concurrency limit.

Queues

To hand a stream of values between fibers, use Queue. It adds bounded, dropping, and sliding strategies, a shutdown that lets the consumer drain its backlog, and interruption that never loses or duplicates a value.

The semaphore and deferred torture tests interrupt waiters and holders at random and check that no permit is lost and exactly one completion wins.