ArgyleConcepts.FSharp.Actor 1.0.0

ArgyleConcepts.FSharp.Actor

An Elm-style (Model–View–Update) actor for F# on .NET, built on System.Threading.Channels and task { }.

A single loop owns the model and processes one message at a time. Update is a pure function from a message and the current model to a new model, the commands to start, and the external messages to emit. Side effects run as commands or subscriptions, never inside Update, so the loop never blocks on I/O.

• Commands start in order but are not awaited by the loop. Each returns the messages it produced, which are queued when it completes. Commands can therefore finish, and report back, out of order.
• Subscriptions are long-running sources, keyed by name, that the model calls for. After every update the actor starts sources whose key is new and cancels sources whose key has gone.
• External messages are emitted on an IAsyncEnumerable returned by Actor.start. The stream completes when the actor stops, or faults with the exception when the actor fails.
• Status decides from the model whether the actor keeps running, stops cleanly, or fails.
• Shutdown is graceful: Actor.stop closes the mailbox, already-queued messages are still processed, and in-flight work is given ShutdownTimeout to finish before the actor's token is cancelled. Actor.stopAndDrain also waits for work that outlives that timeout.

Install

dotnet add package ArgyleConcepts.FSharp.Actor

Targets .NET 8 and .NET 10.

Example

open System
open System.Threading
open System.Threading.Tasks
open ArgyleConcepts.FSharp.Actor

type Msg =
    | Increment
    | Saved of int
    | SaveFailed of exn
    | Tick

type Cmd = Save of int

type Event =
    | CountChanged of int
    | Persisted of int

type Model = { Count: int; Saved: int; Ticking: bool }

let update msg model =
    match msg with
    | Increment ->
        let count = model.Count + 1
        { model with Count = count }, [ Save count ], [ CountChanged count ]
    | Saved count -> { model with Saved = model.Saved + 1 }, [], [ Persisted count ]
    | SaveFailed _ -> model, [], []
    | Tick -> model, [], []

let execute (ct: CancellationToken) cmd : Task<Msg list> =
    task {
        match cmd with
        | Save count ->
            do! Task.Delay(10, ct)
            return [ Saved count ]
    }

let ticker: Subscription<Msg> =
    { Key = "ticker"
      Start =
        fun post ct ->
            task {
                while not ct.IsCancellationRequested && post Tick do
                    do! Task.Delay(TimeSpan.FromSeconds 1.0, ct)
            } }

let actor, events =
    Actor.start
        CancellationToken.None
        { Init = { Count = 0; Saved = 0; Ticking = true }, [], []
          Update = update
          Execute = execute
          OnCommandFailure = SaveFailed
          Subscribe = fun model -> if model.Ticking then [ ticker ] else []
          Status = fun model -> if model.Saved = 3 then ActorStatus.Stopped else ActorStatus.Running
          ShutdownTimeout = Actor.defaultShutdownTimeout }

for _ in 1..3 do
    Actor.post actor Increment |> ignore

task {
    let enumerator = events.GetAsyncEnumerator()
    let mutable more = true

    while more do
        let! next = enumerator.MoveNextAsync()

        if next then printfn "%A" enumerator.Current else more <- false

    do! Actor.completion actor
}
|> _.Wait()

API

Pull request validation

FSharp.Actor PR Validation uses azure-pipelines.yml to validate GitHub pull requests into main through Azure Pipelines in the ArgyleConceptsLLC Azure DevOps organization. It does not run on pushes or publish packages. To reproduce it locally, run from the repository root:

dotnet restore ArgyleConcepts.FSharp.Actor.slnx
dotnet tool restore
dotnet build ArgyleConcepts.FSharp.Actor.slnx --configuration Release --no-restore
dotnet fsi eng/fsharp-analysis/Run.fsx
dotnet test --solution ArgyleConcepts.FSharp.Actor.slnx --configuration Release --no-build --no-restore
dotnet fantomas check .
bash eng/verify-packages.sh

eng/verify-packages.sh packs the library, checks the package metadata, symbols and SourceLink mappings against the current commit, and runs a fresh consumer against the packed package.

Releasing

ArgylePackageVersion in Directory.Build.props is the package version. FSharp.Actor Release uses azure-release.yml and is run manually. By default it validates and retains the package and symbols as the packages artifact without publishing. A run on main with Publish verified packages to NuGet.org enabled pushes that artifact to NuGet.org through the shared fsharp-minimalapi-nuget environment and fsharp-minimalapi-nuget-release variable group. After publishing, tag the packaged commit with the version and create a GitHub release.

License

MIT