asyncmachine-go

README

Samples | Getting Started | Packages | Case Studies | Docs | Community | Status | Dev | FAQ | Changes

asyncmachine-go

[!NOTE] State machines communicate through states (mutations, checking and waiting).

Asyncmachine-go is an AOP Actor Model library for distributed workflows, built on top of a lightweight state machine. It has atomic transitions, RPC, logging, TUI debugger, metrics, tracing, and soon diagrams.

Use cases depend on the layer of the stack used, and range from goroutine synchronization and state synchronization to worker synchronization, bots, LLM agents, consensus algos, etc. Asyncmachine-go can precisely target a specific scenario in a non-opaque way, and bring structure to event-based systems. It takes care of most contexts, select statements, and panics.

Stack

PubSub

Workers

RPC

Handlers

Machine API

Relations

States

Samples

Minimal - an untyped definition of 2 states and 1 relation, then 1 mutation and a check.

import am "github.com/pancsta/asyncmachine-go/pkg/machine"
// ...
mach := am.New(nil, am.Struct{
    "Foo": {Require: am.S{"Bar"}},
    "Bar": {},
}, nil)
mach.Add1("Foo", nil)
mach.Is1("Foo") // false

Complicated - wait on a multi state (event) with 1s timeout, and mutate with typed args, on top of a state context.

// state ctx is a non-err ctx
ctx := client.Mach.NewStateCtx(ssC.WorkerReady)
// clock-based subscription
whenPayload := client.Mach.WhenTicks(ssC.WorkerPayload, 1, ctx)
// mutation
client.WorkerRpc.Worker.Add1(ssW.WorkRequested, Pass(&A{
    Input: 2}))
// WaitFor replaces select statements
err := amhelp.WaitForAll(ctx, time.Second,
    mach2.When1("Ready", nil),
    whenPayload)
// check cancellation
if ctx.Err() != nil {
    // state ctx expired
    return
}
// check error
if err != nil {
    // mutation
    client.Mach.AddErr(err, nil)
    return
}
// client/WorkerPayload and mach2/Ready activated

Handlers - AOP transition handlers.

func (h *Handlers) FooEnter(e *am.Event) bool {
    return true
}
func (h *Handlers) FooBar(e *am.Event) bool {
    return true
}
func (h *Handlers) FooState(e *am.Event) {
    h.foo = NewConn()
}
func (h *Handlers) FooEnd(e *am.Event) {
    h.foo.Close()
}

Schema - states of a node worker.

type WorkerStatesDef struct {
    ErrWork        string
    ErrWorkTimeout string
    ErrClient      string
    ErrSupervisor  string

    LocalRpcReady     string
    PublicRpcReady    string
    RpcReady          string
    SuperConnected    string
    ServeClient       string
    ClientConnected   string
    ClientSendPayload string
    SuperSendPayload  string

    Idle          string
    WorkRequested string
    Working       string
    WorkReady     string

    // inherit from rpc worker
    *ssrpc.WorkerStatesDef
}

All examples and benchmarks can be found in /examples.

Getting Started

/pkg/machine is a mandatory ready, while /pkg/node is the most interesting one. Examples in /examples and /docs/manual.md are good for a general grasp, while /docs/diagrams.md go deeper into implementation details. Reading tests is always a good idea.

Packages

• /pkg/helpers Useful functions when working with async state machines.
• /pkg/history History tracking and traversal.
• /pkg/machine State machine, the main package. Dependency free and semver compatible.
• /pkg/node Distributed worker pools with supervisors.
• /pkg/rpc Remote state machines, with the same API as local ones.
• /pkg/states Reusable state definitions and piping.
• /pkg/telemetry Telemetry exporters for metrics, traces, and logs.
• /pkg/pubsub Planned.
• /tools/cmd/am-dbg Multi-client TUI debugger.
• /tools/cmd/am-gen Generates states files and Grafana dashboards.
• /tools/cmd/am-vis Planned.

Case Studies

Bigger implementations worth reading:

• libp2p PubSub Simulator Sandbox simulator for libp2p-pubsub.
• libp2p PubSub Benchmark Benchmark of libp2p-pubsub ported to asyncmachine-go.
• am-dbg TUI Debugger Single state machine TUI app.

Documentation

• API
• diagrams | cookbook
• manual.md | manual.pdf
  • Machine and States
  • Changing State
  • Advanced Topics
  • Cheatsheet

Community

• GH discussions
• Matrix chat

Status

Under heavy development, status depends on each package. The bottom layers seem prod grade, the top ones are alpha or testing.

Development

• all PRs welcome
• before
  • ./scripts/dep-taskfile.sh
  • task install-deps
• after
  • task test
  • task format
  • task lint

FAQ

How does asyncmachine work?

It calls certain methods on a struct in a certain order (eg BarEnter, FooFoo, FooBar, BarState).

What is a "state" in asyncmachine?

State as in "status", not state as in "data". For example, not a JSON string, but "process RUNNING", or "car BROKEN".

Can asyncmachine be integrated with other frameworks?

Yes, because asyncmachine is more of a set of libraries following the same conventions, than an actual framework. It can integrate with anything via states-based APIs.

How does asyncmachine compare to Temporal?

Temporal is an all-in-one solution with data persistence, which is its limitation. Asyncmachine doesn't hold any data by itself and has progressive layers, making it usable in a wide variety of use cases (e.g. asyncmachine could do workflows for a desktop app).

How does asyncmachine compare to Ergo?

Ergo is a great framework, but leans on old ideas and has web-based tooling. It also isn't natively based on state machines. Asyncmachine provides productivity-focused TUI tooling and rich integrations, while having every component natively state-based (even the code generator).

Does aRPC auto sync data?

aRPC auto syncs only states (clock values). Mutations carry data in arguments, from client to server, while the SendPayload state passes payloads back to the client.

Does asyncmachine return data?

No, just yes/no/later (Executed, Canceled, Queued).

Does asyncmachine return errors?

No, but there's an error state (Exception). Optionally, there are also detailed error states (e.g. ErrNetwork).

Why asyncmachine avoids blocking?

The lack of blocking allows for immediate adjustment to incoming changes and is backed by solid cancellation support.

What does "clock-based" mean?

Each state has a counter of activations, and all state counters create "machine time".

What's the difference between states and events?

Same event happening many times will cause only 1 state activation, until the state becomes inactive.

How do I do X/Y/Z in asyncmachine?

Usually the answer is "make it a state".

Changes

• Changelog
• Breaking Changes
• Roadmap