Documentation
¶
Overview ¶
Package actors owns Arcane's in-process actor runtime and its shared safety rails.
Index ¶
- Variables
- type Actor
- type AdmissionKey
- type Behavior
- type Binding
- type Context
- type Executor
- func (e *Executor) Done() <-chan struct{}
- func (e *Executor) Execute[T any](ctx context.Context, label string, work func(context.Context) (T, error), ...) (T, error)
- func (e *Executor) Stop(ctx context.Context) error
- func (e *Executor) Submit[T any](ctx context.Context, label string, work func(context.Context) (T, error), ...) (*Task[T], error)
- type Gate
- type Ingress
- type Lease
- type Message
- type NoPayload
- type Promise
- type Resource
- func (r *Resource[T]) Clear(ctx context.Context, label string) error
- func (r *Resource[T]) Do(ctx context.Context, label string, work func(context.Context, T) error) error
- func (r *Resource[T]) Restart(ctx context.Context, label string, build func(context.Context) (T, error)) error
- func (r *Resource[T]) Stop(ctx context.Context) error
- type Runner
- type Runtime
- type Signal
- type Snapshot
- type State
- type StateMap
- func (s *StateMap[K, V]) Apply(ctx context.Context, label string, ...) error
- func (s *StateMap[K, V]) ApplyTyped[R any](ctx context.Context, label string, ...) (R, error)
- func (s *StateMap[K, V]) Drain(ctx context.Context, label string) ([]V, error)
- func (s *StateMap[K, V]) Get(key K) (V, bool)
- func (s *StateMap[K, V]) Remove(ctx context.Context, label string, key K) (V, bool, error)
- func (s *StateMap[K, V]) RemoveWhere(ctx context.Context, label string, predicate func(K, V) bool) ([]V, error)
- func (s *StateMap[K, V]) Stop(ctx context.Context) error
- func (s *StateMap[K, V]) Store(ctx context.Context, label string, key K, value V) (V, bool, error)
- func (s *StateMap[K, V]) Values() []V
- type Task
- type Timer
- type Worker
Constants ¶
This section is empty.
Variables ¶
var ErrResourceStopped = errors.New("actor resource stopped")
ErrResourceStopped reports work submitted after terminal resource shutdown.
Functions ¶
This section is empty.
Types ¶
type Actor ¶
type Actor struct {
// contains filtered or unexported fields
}
Actor owns one Hollywood process, its ingress bindings, and all workers started from its behavior.
func NewActor ¶
func NewActor(ctx context.Context, runtime *Runtime, kind, id string, maxRestarts int32, producer func() Behavior, bindings ...Binding) (*Actor, error)
NewActor starts one application behavior on the shared actor runtime.
func (*Actor) Done ¶
func (a *Actor) Done() <-chan struct{}
Done closes after the actor and its workers stop.
type AdmissionKey ¶
AdmissionKey namespaces a string identifier shared by the application gate.
type Behavior ¶
type Behavior struct {
Initialize func(*Context)
Handle func(*Context, any)
Cleanup func(*Context)
}
Behavior defines the application behavior hosted by one shared actor.
type Binding ¶
type Binding interface {
// contains filtered or unexported methods
}
Binding connects an ingress to an actor for the duration of its lifetime.
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context exposes the operations available while handling one actor message without leaking Hollywood into actor consumers.
type Executor ¶
type Executor struct {
// contains filtered or unexported fields
}
Executor serializes heterogeneous blocking tasks through one actor mailbox. A task must not synchronously submit another task to the same Executor.
func NewExecutor ¶
func NewExecutor(ctx context.Context, runtime *Runtime, kind, id string, maxRestarts int32) (*Executor, error)
NewExecutor creates a serial task executor on the shared actor runtime.
func (*Executor) Done ¶
func (e *Executor) Done() <-chan struct{}
Done closes after the executor actor terminates.
func (*Executor) Execute ¶ added in v2.10.0
func (e *Executor) Execute[T any](ctx context.Context, label string, work func(context.Context) (T, error), after func(T, error)) (T, error)
Execute queues work, waits for its typed result, and runs after only once the result is available to the caller. Work and after are both panic-contained.
func (*Executor) Submit ¶ added in v2.10.0
func (e *Executor) Submit[T any](ctx context.Context, label string, work func(context.Context) (T, error), after func(T, error)) (*Task[T], error)
Submit queues work synchronously and returns a handle that can be awaited separately. This is useful for terminal cleanup that must stay queued even when the shutdown wait context expires.
type Gate ¶
type Gate[K comparable] struct { // contains filtered or unexported fields }
Gate admits at most one active lease for each key through one actor-owned map.
func NewGate ¶
func NewGate[K comparable](ctx context.Context, runtime *Runtime, kind, id string) (*Gate[K], error)
NewGate creates a keyed admission gate on the shared actor runtime.
type Ingress ¶
type Ingress[K comparable, V any] struct { // contains filtered or unexported fields }
Ingress coalesces concurrent producers into one pending mailbox signal while retaining the newest value. Bind may happen after Send, which lets services accept startup triggers before their actor exists.
func NewIngress ¶
func NewIngress[K comparable, V any](kind K) *Ingress[K, V]
NewIngress creates an unbound coalescing actor ingress.
func (*Ingress[K, V]) Acknowledge ¶
Acknowledge commits work through generation and replays a newer pending value.
func (*Ingress[K, V]) Begin ¶
Begin returns the newest value and its generation while retaining the work as pending until Acknowledge commits it.
func (*Ingress[K, V]) Latest ¶
func (i *Ingress[K, V]) Latest() V
Latest returns the newest value without changing admission state.
type Lease ¶
type Lease[K comparable] struct { // contains filtered or unexported fields }
Lease represents one admitted key. Release is idempotent and confirms that the actor processed the completion before returning.
type Message ¶
type Message[K comparable, V any] struct { Kind K Value V Err error // contains filtered or unexported fields }
Message is the shared typed envelope for actor commands, events, and replies. Worker completion handlers must call Acknowledge before returning.
func (Message[K, V]) Acknowledge ¶
func (m Message[K, V]) Acknowledge()
Acknowledge confirms that an actor processed a worker completion.
type NoPayload ¶
type NoPayload struct{}
NoPayload is used by typed actor messages that only carry a kind.
type Promise ¶
type Promise[T any] struct { // contains filtered or unexported fields }
Promise is an idempotent one-result completion primitive.
func NewPromise ¶
NewPromise creates a promise that accepts exactly one result.
type Resource ¶
type Resource[T comparable] struct { // contains filtered or unexported fields }
Resource serializes the lifecycle and use of one replaceable value through an actor executor. Its value is never accessed outside that mailbox, and its zero value represents the absence of a resource.
func NewResource ¶
func NewResource[T comparable](ctx context.Context, runtime *Runtime, kind, id string, maxRestarts int32, stop func(T) error) (*Resource[T], error)
NewResource creates an actor-owned replaceable resource.
func (*Resource[T]) Clear ¶
Clear stops and forgets the current value while keeping the resource reusable.
func (*Resource[T]) Do ¶
func (r *Resource[T]) Do(ctx context.Context, label string, work func(context.Context, T) error) error
Do serializes work with Restart and Stop. Work is skipped after terminal stop.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner owns one long-lived background function and joins it before stopping.
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime owns the shared Hollywood engine and observes actor failures.
func NewRuntime ¶
NewRuntime constructs the shared actor engine and registers its lifecycle monitor.
func (*Runtime) DeadLetterCount ¶
DeadLetterCount returns the number of undeliverable actor messages observed.
func (*Runtime) DuplicateIDCount ¶
DuplicateIDCount returns the number of duplicate actor registrations observed.
func (*Runtime) MaxRestartsExceededCount ¶
MaxRestartsExceededCount returns the number of permanently stopped actors observed.
func (*Runtime) RestartCount ¶
RestartCount returns the number of actor restarts observed.
type Signal ¶
type Signal[T any] struct { // contains filtered or unexported fields }
Signal delivers each published value once to every current subscriber. Subscribers run sequentially on the publishing goroutine.
type Snapshot ¶
type Snapshot[T any] struct { // contains filtered or unexported fields }
Snapshot publishes immutable copies of a value for lock-free readers.
type State ¶
type State[T any] struct { // contains filtered or unexported fields }
State serializes mutations through an actor and publishes immutable snapshots.
func NewState ¶
func NewState[T any](ctx context.Context, runtime *Runtime, kind, id string, maxRestarts int32, initial T, clone func(T) T) (*State[T], error)
NewState creates actor-owned state with a caller-defined snapshot clone.
func (*State[T]) Apply ¶
func (s *State[T]) Apply(ctx context.Context, label string, mutate func(context.Context, *T) error) error
Apply serializes one mutation and publishes the resulting state.
func (*State[T]) Done ¶
func (s *State[T]) Done() <-chan struct{}
Done closes after the state actor terminates.
type StateMap ¶
type StateMap[K comparable, V any] struct { // contains filtered or unexported fields }
StateMap owns mutable keyed state while publishing immutable snapshots for readers.
func NewActorStateMap ¶
func NewActorStateMap[K comparable, V any](ctx context.Context, runtime *Runtime, kind, id string, maxRestarts int32) (*StateMap[K, V], error)
NewActorStateMap creates a state map whose mutations use the shared actor runtime.
func NewStateMap ¶
func NewStateMap[K comparable, V any]() *StateMap[K, V]
NewStateMap creates a locally serialized state map for callers without an actor runtime.
func (*StateMap[K, V]) Apply ¶
func (s *StateMap[K, V]) Apply(ctx context.Context, label string, mutate func(map[K]V) (changed bool, err error)) error
Apply serializes a mutation and publishes it atomically when changed is true.
func (*StateMap[K, V]) ApplyTyped ¶ added in v2.10.0
func (s *StateMap[K, V]) ApplyTyped[R any]( ctx context.Context, label string, mutate func(map[K]V) (result R, changed bool, err error), ) (R, error)
ApplyTyped serializes a typed mutation and publishes its resulting state.
func (*StateMap[K, V]) Get ¶
Get reads one value from the latest immutable snapshot without entering the mailbox.
func (*StateMap[K, V]) RemoveWhere ¶
func (s *StateMap[K, V]) RemoveWhere(ctx context.Context, label string, predicate func(K, V) bool) ([]V, error)
RemoveWhere atomically removes every value selected by predicate.
type Task ¶
type Task[T any] struct { // contains filtered or unexported fields }
Task is one submitted executor operation whose result may be awaited with a context independent from the operation's own lifetime.
type Timer ¶
type Timer[K comparable] struct { // contains filtered or unexported fields }
Timer sends generation-fenced messages to an actor. It is actor-owned and must be stopped when the receiver handles actor.Stopped.
Source Files