Skip to content

About

Distributed Actor framework for Go built on Actorx and NATS.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

20 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Actorx Distributed

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.

Get started

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 counter

Addr("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.

Examples

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.

Learn more

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.

About

Distributed Actor framework for Go built on Actorx and NATS.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages