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 and bring structure to event-based
systems. It takes care of most contexts, select statements, and panics.
| PubSub | ||||||||||||
| Workers | ||||||||||||
| RPC | ||||||||||||
| Handlers | ||||||||||||
| Machine API | ||||||||||||
| Relations | ||||||||||||
| States | ||||||||||||
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") // falseComplicated - 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 activatedHandlers - 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.
/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.
/pkg/helpersUseful functions when working with async state machines./pkg/historyHistory tracking and traversal./pkg/machineState machine, the main package. Dependency free and semver compatible./pkg/nodeDistributed worker pools with supervisors./pkg/rpcRemote state machines, with the same API as local ones./pkg/statesReusable state definitions and piping./pkg/telemetryTelemetry exporters for metrics, traces, and logs./pkg/pubsubPlanned./tools/cmd/am-dbgMulti-client TUI debugger./tools/cmd/am-genGenerates states files and Grafana dashboards./tools/cmd/am-visPlanned.
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.
Under heavy development, status depends on each package. The bottom layers seem prod grade, the top ones are alpha or testing.
- all PRs welcome
- before
./scripts/dep-taskfile.shtask install-deps
- after
task testtask formattask lint
It calls certain methods on a struct in a certain order (eg BarEnter, FooFoo, FooBar, BarState).
State as in "status", not state as in "data". For example, not a JSON string, but "process RUNNING", or "car BROKEN".
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).
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.
No, just yes/no/later (Executed, Canceled, Queued).
No, but there's an error state (Exception). Optionally, there are also detailed error states (e.g. ErrNetwork).
The lack of blocking allows for immediate adjustment to incoming changes and is backed by solid cancellation support.
Each state has a counter of activations, and all state counters create "machine time".
Same event happening in a series will cause 1 state activation, until the state becomes inactive.
Usually the answer is "make it a state".