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

Ref (Atomic References)

Ref<'T> holds a mutable value that concurrent workflows can update atomically.

Verified

open Axial
open Axial.State

Axial

State

Why Use Ref?

In a functional program, state is usually passed as parameters or through the environment. Some state, such as a shared counter, a cache, or a status flag, needs several concurrent workflows to observe and update the same value.

Ref uses lightweight per-instance locking to make updates atomic without manual lock management.

Creating a Ref

Use Ref.make to create a new reference with an initial value. Creating a Ref returns a Flow.

Verified

> open Axial.State;;
> let counted () : Flow<int> =
-     flow {
-         let! counter = Ref.make 0
-         do! Ref.update ((+) 1) counter
-         return! Ref.get counter
-     };;
> Flow.run () (counted ());;
> Flow.run () (counted ());;

val it: Exit<int,Never> = Success 1
val it: Exit<int,Never> = Success 1

Axial

State

counted: unit -> Flow<int>

Flow

A flow that requires no environment and cannot fail with a typed error.

int

An abbreviation for the CLI type . Basic Types

flow: FlowBuilder

The universal flow { } computation expression.

counter: Ref<int>

Axial.State.RefModule

make: 'T -> Flow<'env,'none,Ref<'T>>

Creates a new with the initial value. The initial value of the reference. A flow that creates and returns the reference. (Ref.make 10).RunSynchronously(())

update: ('T -> 'T) -> Ref<'T> -> Flow<'env,'none,unit>

Updates the value of the reference using the supplied function. The update function of type 'T -> 'T. The to update. A flow that updates the value and returns unit. Ref.update (fun x -> x + 1) myRef

(+): ^T1 -> ^T2 -> ^T3

Overloaded addition operator The first parameter. The second parameter. The result of the operation. 2 + 2 // Evaluates to 4 "Hello " + "World" // Evaluates to "Hello World"

get: Ref<'T> -> Flow<'env,'none,'T>

Reads the current value of the reference. The to read from. A flow that returns the current value. let readInitialValue () = flow { let! reference = Ref.make 10 return! Ref.get reference }

Axial.Flow

run: 'env -> Flow<'env,'error,'value> -> Exit<'value,'error>

Runs the workflow and blocks until the final exit is available. The environment used by the workflow. The workflow to run. The final workflow exit. let exit = workflow |> Flow.run environment

Each run makes a fresh Ref, so running counted twice gives 1 both times.

Reading and Writing

Use Ref.get to read the current value and Ref.set to overwrite it.

Verified

let workWithRef (counter: Ref<int>) =
    flow {
        let! value = Ref.get counter
        do! Ref.set (value + 1) counter
        return value
    }

workWithRef: Ref<int> -> Flow<'a,'b,int>

counter: Ref<int>

Axial.State.Ref`1

Represents a handle to a mutable reference that can be updated atomically. The type of the value stored in the reference.

int

An abbreviation for the CLI type . Basic Types

flow: FlowBuilder

The universal flow { } computation expression.

value: int

Axial.State.RefModule

get: Ref<'T> -> Flow<'env,'none,'T>

Reads the current value of the reference. The to read from. A flow that returns the current value. let readInitialValue () = flow { let! reference = Ref.make 10 return! Ref.get reference }

set: 'T -> Ref<'T> -> Flow<'env,'none,unit>

Sets the value of the reference to the specified value. The new value to set. The to update. A flow that sets the value and returns unit. let replaceValue () = flow { let! reference = Ref.make 10 do! Ref.set 20 reference }

(+): ^T1 -> ^T2 -> ^T3

Overloaded addition operator The first parameter. The second parameter. The result of the operation. 2 + 2 // Evaluates to 4 "Hello " + "World" // Evaluates to "Hello World"

Requires & types

Requires: open Axial; open Axial.State (packages: Axial)

val workWithRef: Ref<int> -> Flow<'a,'b,int>

Atomic Updates

Use Ref.update or Ref.modify to update a value atomically when multiple fibers share it.

`Ref.update`

Updates the value using a transformation function.

Verified

let increment (counter: Ref<int>) =
    Ref.update (fun x -> x + 1) counter

increment: Ref<int> -> Flow<'a,'b,unit>

counter: Ref<int>

Axial.State.Ref`1

Represents a handle to a mutable reference that can be updated atomically. The type of the value stored in the reference.

int

An abbreviation for the CLI type . Basic Types

Axial.State.RefModule

update: ('T -> 'T) -> Ref<'T> -> Flow<'env,'none,unit>

Updates the value of the reference using the supplied function. The update function of type 'T -> 'T. The to update. A flow that updates the value and returns unit. Ref.update (fun x -> x + 1) myRef

x: int

(+): ^T1 -> ^T2 -> ^T3

Overloaded addition operator The first parameter. The second parameter. The result of the operation. 2 + 2 // Evaluates to 4 "Hello " + "World" // Evaluates to "Hello World"

Requires & types

Requires: open Axial.State (packages: Axial)

val increment: Ref<int> -> Flow<'a,'b,unit>

`Ref.modify`

Updates the value and returns a derived result (a common pattern for "get and increment").

Verified

let incrementAndGet (counter: Ref<int>) =
    Ref.modify (fun x -> 
        let next = x + 1
        next, next // (return value, new state)
    ) counter

incrementAndGet: Ref<int> -> Flow<'a,'b,int>

counter: Ref<int>

Axial.State.Ref`1

Represents a handle to a mutable reference that can be updated atomically. The type of the value stored in the reference.

int

An abbreviation for the CLI type . Basic Types

Axial.State.RefModule

modify: ('T -> 'v * 'T) -> Ref<'T> -> Flow<'env,'none,'v>

Updates the value of the reference using the supplied function and returns a derived value. The update function of type 'T -> 'v * 'T, returning the result before the next state. The to update. A flow that updates the value and returns the first part of the tuple returned by . Ref.modify (fun x -> "increased", x + 1) myRef

x: int

next: int

(+): ^T1 -> ^T2 -> ^T3

Overloaded addition operator The first parameter. The second parameter. The result of the operation. 2 + 2 // Evaluates to 4 "Hello " + "World" // Evaluates to "Hello World"

Requires & types

Requires: open Axial.State (packages: Axial)

val incrementAndGet: Ref<int> -> Flow<'a,'b,int>

The atomic family

Ref.getAndSet, Ref.getAndUpdate, and Ref.updateAndGet cover the common "get the previous/updated value while changing state" cases without writing a custom modify function:

Verified

let incrementAndGetWithHelper (counter: Ref<int>) =
    Ref.updateAndGet (fun x -> x + 1) counter

let snapshotAndReset (counter: Ref<int>) =
    Ref.getAndSet 0 counter

incrementAndGetWithHelper: Ref<int> -> Flow<'a,'b,int>

counter: Ref<int>

Axial.State.Ref`1

Represents a handle to a mutable reference that can be updated atomically. The type of the value stored in the reference.

int

An abbreviation for the CLI type . Basic Types

Axial.State.RefModule

updateAndGet: ('T -> 'T) -> Ref<'T> -> Flow<'env,'none,'T>

Updates the value using the supplied function and returns the value after the update. The update function of type 'T -> 'T. The to update. A flow that returns the updated value. Ref.updateAndGet (fun x -> x + 1) myRef

x: int

(+): ^T1 -> ^T2 -> ^T3

Overloaded addition operator The first parameter. The second parameter. The result of the operation. 2 + 2 // Evaluates to 4 "Hello " + "World" // Evaluates to "Hello World"

snapshotAndReset: Ref<int> -> Flow<'a,'b,int>

getAndSet: 'T -> Ref<'T> -> Flow<'env,'none,'T>

Sets the value of the reference and returns the value it held before the update. The new value to set. The to update. A flow that returns the previous value. let replaceAndReturnPrevious () = flow { let! reference = Ref.make 10 return! Ref.getAndSet 20 reference }

Requires & types

Requires: open Axial.State (packages: Axial)

val incrementAndGetWithHelper: Ref<int> -> Flow<'a,'b,int>

val snapshotAndReset: Ref<int> -> Flow<'a,'b,int>

Example: Shared Progress Tracker

Verified

let trackProgress (total: int) =
    flow {
        let! progress = Ref.make 0
        
        let doStep = Ref.updateAndGet (fun p -> p + 1) progress
            
        // Run several steps
        for _ in 1 .. total do
            do! doStep |> Flow.ignore
            
        return "Complete"
    }

trackProgress: int -> Flow<'a,'b,string>

total: int

int

An abbreviation for the CLI type . Basic Types

flow: FlowBuilder

The universal flow { } computation expression.

progress: Ref<int>

Axial.State.RefModule

make: 'T -> Flow<'env,'none,Ref<'T>>

Creates a new with the initial value. The initial value of the reference. A flow that creates and returns the reference. (Ref.make 10).RunSynchronously(())

doStep: Flow<'a,'b,int>

updateAndGet: ('T -> 'T) -> Ref<'T> -> Flow<'env,'none,'T>

p: int

(+): ^T1 -> ^T2 -> ^T3

Overloaded addition operator The first parameter. The second parameter. The result of the operation. 2 + 2 // Evaluates to 4 "Hello " + "World" // Evaluates to "Hello World"

(..): ^T -> ^T -> ^T seq

The standard overloaded range operator, e.g. [n..m] for lists, seq {n..m} for sequences The start value of the range. The end value of the range. The sequence spanning the range. [1..4] // Evaluates to [1; 2; 3; 4] [1.5..4.4] // Evaluates to [1.5; 2.5; 3.5] ['a'..'d'] // Evaluates to ['a'; 'b'; 'c'; 'd'] [|1..4|] // Evaluates to an array [|1; 2; 3; 4|] { 1..4 } // Evaluates to a sequence [1; 2; 3; 4])

(|>): 'T1 -> ('T1 -> 'U) -> 'U

Apply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6

Axial.Flow

ignore: Flow<'env,'error,'value> -> Flow<'env,'error,unit>

Maps the successful value of a synchronous flow to unit. The source flow. A flow that succeeds with unit instead of the original value. let flow = Flow.succeed 42 |> Flow.ignore

Requires & types

Requires: open Axial; open Axial.State (packages: Axial)

val trackProgress: int -> Flow<'a,'b,string>

API Reference

The full Ref signature list — make, get, set, update, modify, and the getAndSet / getAndUpdate / updateAndGet family — is in the Ref API reference.

The refs torture test runs every update operation from eight fibers at once and checks that no update is lost and no two see the same value.

Ref (Atomic References)

Why Use Ref?

Creating a Ref

Reading and Writing

Atomic Updates

`Ref.update`

`Ref.modify`

The atomic family

Example: Shared Progress Tracker

API Reference

Overview

Docs

API Reference