English | 中文
Actorx Distributed is a distributed actor framework for Go built on Actorx and NATS. It lets applications access stateful actors across processes by type and business ID, creating instances on demand.
Actorx handles actor execution within each process, NATS carries messages between processes, and JetStream KV coordinates instance ownership. Actors support Send, Call and Stream for one-way messages, request/reply and streaming results.
A distributed counter stores a count and returns the new total after each Add message. The snippets below show the main APIs; see the Counter example for a complete runnable program with generated bindings, error handling and shutdown.
import (
"github.com/go-aie/actorx"
"github.com/go-aie/actorx-dist"
)
type Add struct {
N int `json:"n"`
}
//actorx:actor
type Counter struct {
count int
}
func (c *Counter) Add(_ actorx.Context, msg Add) (int, error) {
c.count += msg.N
return c.count, nil
}
var CounterSpec = actorxdist.ActorSpec[*Counter]{
Type: "counter",
New: func(actorxdist.ActorKey) *Counter {
return &Counter{}
},
}Counter defines the behavior; CounterSpec declares its type and constructor. A provider registers the spec and keeps running to handle requests. On shutdown, Runtime.Close removes its registrations and waits for its actors to exit:
ctx := context.Background()
rt, _ := actorxdist.NewRuntime(ctx)
defer rt.Close(ctx)
_, _ = rt.Register(ctx, CounterSpec)A separate consumer creates its own Runtime and calls the counter by type and ID, without registering any actors:
rt, _ := actorxdist.NewRuntime(ctx)
defer rt.Close(ctx)
addr, _ := rt.Addr("counter", "orders-42")
n, _ := addr.Call[int](ctx, Add{N: 5})
fmt.Println(n) // 5 for a new counterAddr("counter", "orders-42") creates a logical address without starting an actor. The first Send, Call or Stream finds or activates the instance; the framework ensures unique ownership for each type and ID.
State lives in provider memory and disappears on instance exit. Unreachable owners are not replaced automatically; see explicit recovery after forced exit.
Start with Counter for environment setup, run commands, expected output and shutdown. All examples can share the same NATS service.
| Example | What it teaches |
|---|---|
| Counter (start here) | Cross-process calls, retained state and multiple providers. |
| Click | Button calls Counter to compose actors across processes. |
| Chat | Cross-process Stream and incremental output with a slow consumer. |
| Guide | Contents |
|---|---|
| Concepts | Logical objects, activation generations, addresses and contexts. |
| Call semantics | Send/Call/Stream, deadlines, errors and capacity. |
| Lifecycle | Stop/Wait, object lifetime and cleanup responsibility. |
| Deployment | Configuration, permissions, contract upgrades and explicit recovery. |
| Cross-language access | HTTP/SSE Call/Stream, Python providers and consumers, and the remote protocol. |
For implementation details, see architecture, wire contract and limits, the Registry protocol, and the NATS reference for namespaces, subjects and permissions.