Actor

Spawn a new actor process with default state.

The compiler's static Counter spawn and self spawn call sites lower directly to beamtalk_actor:safe_spawn/class_self_spawn (BT-3072) — this declaration is the documented, xref-visible source of behaviour for the dynamic dispatch path (workspace bindings, perform:), not the method actually invoked by those fast paths.

Examples

c := Counter spawn

Spawn a new actor process with initialization arguments.

See spawn for the static-vs-dynamic dispatch note (BT-3072).

Examples

c := Counter spawnWith: #{#count => 10}

Actors cannot be created with new — always raises (BT-217).

Actors are processes with identity and lifecycle, not immutable values; spawn starts the process, new does not make sense for them. Every actor subclass carries a compiled new/0 that raises this same error directly (required by the runtime's {new, Args} instantiation protocol, which calls a class's own compiled new/0 rather than dispatching through inherited class methods) — this declaration is the documented, xref-visible source of that behaviour.

Examples

Counter new   // => raises instantiation_error: "Use spawn instead"

Actors cannot be created with new: — always raises (BT-217).

Use spawnWith: to create an actor instance with initialization arguments. See new for why actors reject direct instantiation.

Examples

Counter new: #{#count => 10}   // => raises instantiation_error: "Use spawnWith: instead"

Atomically spawn a new actor and register it under name.

Uses gen_server:start_link({local, Name}, ...) under the hood so the name is established during process startup — no TOCTOU window between spawn and registerAs:. Prefer this over post-spawn registerAs: whenever the name is known up front.

Returns Result ok: actor on success, or Result error: with one of:

• name_registered — another process is already registered under name
• reserved_name — name is in the OTP kernel / stdlib blocklist
• type_error — name is not a Symbol

Examples

c := (Counter spawnAs: #counter) unwrap
(Counter spawnAs: #counter) onError: [:e | Logger warn: "name taken"]

Atomically spawn a new actor with init args and register it under name.

Same contract as spawnAs: plus the initialisation arguments passed to the actor's init/1 callback.

Examples

c := (Counter spawnWith: #{#count => 10} as: #counter) unwrap

Look up a registered actor by name, checked against the receiver class.

Returns Result ok: actor when a process is registered under name and its class is the receiver (or any subclass). Self resolves to the receiver class at the call site, so subclasses inherit a typed lookup:

Counter named: #counter           // => Result(Counter, Error)
Actor named: #anything            // => Result(Actor, Error)

Error cases:

• name_not_registered — nothing registered under name
• wrong_class — registered, but not a (subclass of) the receiver class
• type_error — name is not a Symbol

Examples

engine := (WorkflowEngine named: #workflowEngine) unwrap
(Logger named: #counter) // => Result error: (beamtalk_error wrong_class)

Atomically spawn a new actor and register it under name, in the requested cluster scope.

scope: #local behaves identically to spawnAs: — genuinely atomic: a losing race never runs initialize at all (OTP reserves the local name as part of the process start itself). scope: #global registers with OTP's global module instead — the name is unique across the whole connected cluster and resolves the same way from every node, via global:whereis_name/1 on each send rather than a per-node lookup — but is NOT atomic in the same way: global has no custom-resolver variant of an atomic "start-and-register", so the actor is started (and initialize runs to completion) before the name is registered. If that registration then loses the race, the already-initialized actor is torn down and name_registered is returned — but any side effect initialize already performed (I/O, messaging another actor, etc.) already happened, even though the caller sees the same clean failure #local would give without ever running initialize. Idempotent initialize overrides are unaffected; one with externally-visible side effects should account for this under scope: #global.

Returns Result ok: actor on success, or Result error: with one of:

• name_registered — another process is already registered under name in that scope
• reserved_name — name is in the OTP kernel / stdlib blocklist
• type_error — name is not a Symbol, or scope is neither #local nor #global

Examples

leader := (Scheduler spawnAs: #scheduler scope: #global) unwrap
// on any node in the cluster:
s := (Scheduler named: #scheduler scope: #global) unwrap

Atomically spawn a new actor with init args and register it under name, in the requested cluster scope.

Same contract as spawnAs:scope: plus the initialisation arguments passed to the actor's init/1 callback. initArgs goes through the same wire encoder as every other cross-node argument (ADR 0126 §5.1) — no second encode path.

Examples

c := (Counter spawnWith: #{#count => 10} as: #counter scope: #global) unwrap

Look up an actor by name in the requested cluster scope, checked against the receiver class.

scope: #local behaves identically to named: (this node's local registry). scope: #global checks OTP's cluster-wide global registry instead — the same name resolves to the same actor from every connected node.

Error cases: as named:, plus type_error when scope is neither #local nor #global.

Examples

s := (Scheduler named: #scheduler scope: #global) unwrap

Return every currently-registered Beamtalk actor as Actor proxies.

Filters out raw Erlang-registered processes (kernel, logger, user FFI registrations) — only actors carrying the '$beamtalk_actor' marker appear. Each returned proxy carries its real class, so Actor allRegistered first class returns the concrete subclass, not Actor.

Intended for tooling and REPL discovery; production code should use Actor named: to address known names directly.

This lists only name-registered actors. To list every live actor (named or not) use Node current actors; every registered actor is also in that set.

Examples

Actor allRegistered  // => #(an Actor(Counter), an Actor(Logger))

Spawn a new actor process on node, with default state.

Same contract as spawn, except the actor process starts on node instead of here — initialize, reserved-name checks, and ActorSpawned all fire there. See "Remote spawn and lookup" above for the idempotency and linking caveats.

Error cases:

• node_down — node is unreachable
• class_not_found — the class is not loaded on node

Examples

worker := (Node named: #'worker@localhost') unwrap
c := (Counter spawnOn: worker) unwrap
c node          // => Node(worker@localhost)

Atomically spawn a new actor on node and register it under name there.

Same contract as spawnAs:, except the actor process (and its registration) both happen on node instead of here. See "Remote spawn and lookup" above for the idempotency and linking caveats.

Error cases: as spawnAs:, plus node_down (node is unreachable) and class_not_found (the class is not loaded on node).

Examples

worker := (Node named: #'worker@localhost') unwrap
(Counter spawnAs: #hits on: worker) unwrap

Spawn a new actor process on node, with initialization arguments.

Same contract as spawnWith:, except the actor process starts on node instead of here. initArgs is wire-encoded (ADR 0126 §5.1) before crossing the node boundary — a Value nested inside it is enveloped and version-checked like any other cross-node argument; a HandleScoped value (e.g. Ets) is rejected here, in the sender, before the erpc call. See "Remote spawn and lookup" above for the idempotency and linking caveats.

Error cases: as spawnOn:, plus not_serialisable (initArgs contains a node-scoped handle).

Examples

worker := (Node named: #'worker@localhost') unwrap
c := (Counter spawnWith: #{#count => 10} on: worker) unwrap

Atomically spawn a new actor with init args on node and register it under name there.

Same contract as spawnAs:on: plus the initialisation arguments passed to the actor's init/1 callback — see spawnWith:on: for the wire-encoding note.

Examples

worker := (Node named: #'worker@localhost') unwrap
(Counter spawnWith: #{#count => 10} as: #hits on: worker) unwrap

Look up a registered actor by name on node, checked against the receiver class.

Same contract as named:, checked against node's registry instead of this node's. The returned reference is node-qualified: it keeps resolving against node regardless of which node later sends to it.

Error cases: as named:, plus node_down (node is unreachable).

Examples

worker := (Node named: #'worker@localhost') unwrap
hits := (Counter named: #hits on: worker) unwrap
hits increment   // => 1 — sent to worker, not resolved locally

Return every currently-registered Beamtalk actor on node as Actor proxies.

Same contract as allRegistered, listing node's registered actors instead of this node's. Unlike the local, network-free allRegistered, this answers a Result — reaching another node is an expected-failure operation (ADR 0060).

Like allRegistered, this lists only name-registered actors. To list every live actor on node (named or not) use node actors.

Examples

worker := (Node named: #'worker@localhost') unwrap
(Actor allRegisteredOn: worker) unwrap  // => #(an Actor(Counter), ...)

Default OTP restart policy for this actor class.

Returns #temporary by default — the actor is not automatically restarted on crash. Override in subclasses to declare a different default:

• #permanent — always restart (e.g., a database pool)
• #transient — restart only on abnormal exit (e.g., a request handler)
• #temporary — never restart (the default)

Examples

Actor supervisionPolicy           // => #temporary
DatabasePool supervisionPolicy    // => #permanent (if overridden)

Whether this class is a supervisor.

Returns false for Actor subclasses. Supervisor and DynamicSupervisor subclasses override this to return true. Used by SupervisionSpec childSpec to determine OTP type (#worker vs #supervisor) and shutdown timeout.

Examples

Counter isSupervisor   // => false
WebApp isSupervisor    // => true (if WebApp subclasses Supervisor)

Return a SupervisionSpec for this actor class with default settings.

Creates a SupervisionSpec with actorClass set to the receiver and restart set from supervisionPolicy. Use the fluent with*: API to override per-child settings:

Examples

DatabasePool supervisionSpec
    // => SupervisionSpec with actorClass: DatabasePool, restart: #temporary

DatabasePool supervisionSpec withId: #primary withArgs: #{#role => #primary}

Register this (already-spawned) actor under name.

Non-atomic with respect to spawn: another process may claim name between the actor's spawn and this call. Prefer class spawnAs: when the name is known at spawn time.

On success returns Result ok: self so calls can be chained:

(counter registerAs: #c) onSuccess: [:c | c increment]

Unregister this actor's name, if any. Idempotent.

Returns #ok even when the actor has no registered name or the name has already been released. When a real failure occurs (reserved name, type error, etc.) the error is raised — consistent with other teardown methods like stop and kill.

When an actor process exits, Erlang automatically releases its registered name; callers do not need to call unregister from terminate:.

Examples

counter unregister   // => #ok

Internal FFI seam (ADR 0101 Part 4): release this actor's registered name. Keeps unregister pure Beamtalk. Returns bare ok, which the FFI boundary auto-converts to Result ok: nil (ADR 0076/0121).

Return the Symbol this actor is registered under, or nil if unnamed.

Examples

counter registeredName   // => #counter (or nil)

Whether this actor currently has a registered name.

Examples

counter isRegistered   // => true or false

Wrap this actor with a custom message timeout.

Returns a TimeoutProxy that forwards all messages to this actor using the given timeout (milliseconds, a Duration, or #infinity) for gen_server:call. The default OTP timeout is 5000ms.

The proxy is a separate actor process — call stop on it when done.

Examples

slowDb := db withTimeout: 30000
slowDb query: sql              // forwarded with 30s timeout
slowDb stop                    // stop the proxy when done
patient := db withTimeout: (Duration seconds: 30)
patient stop

Optional lifecycle hook called automatically after spawn.

Override in subclasses to perform setup that goes beyond state: defaults, such as opening resources or computing derived state. Called synchronously before the spawned object is returned to the caller.

If initialize raises an error, the spawn fails with a catchable InstantiationError. Under a supervisor, the child start fails and the supervisor applies its restart strategy.

Examples

Actor subclass: Stack
  state: items = nil
  initialize => self.items := #()

Optional lifecycle hook called when the actor is shutting down.

Override in subclasses to perform cleanup such as closing resources, flushing buffers, or notifying dependents. Called synchronously on:

• graceful shutdown (stop)
• a supervisor's direct aSupervisor terminate: aClass
• a supervisor-initiated shutdown of this actor as part of a rest_for_one / one_for_all restart cascade (this actor did not crash itself — a sibling did — but the supervisor tears it down too)

The reason parameter is an Object — it may be a Symbol like #normal for graceful stop, but OTP can also pass compound terms like {shutdown, term} for non-atom shutdown reasons.

Not called when the actor is forcefully killed (kill). If terminate: raises an error, shutdown proceeds anyway. Actor state (self.field) is accessible during terminate:.

BT-3596: overriding terminate: makes this actor's class (and any subclass) trap exits (process_flag(trap_exit, true)), which is what lets OTP deliver a supervisor's shutdown signal as a message instead of killing the process before terminate: can run. A class that never overrides terminate: keeps the plain link semantics it always had.

Examples

Actor subclass: Logger
  state: logFile = nil
  terminate: reason =>
    self.logFile isNil ifFalse: [self.logFile close]

Delegate message dispatch to the backing Erlang module.

This method is a sentinel — non-native Actors do not have a backing Erlang module, so calling delegate raises an Error at runtime. Native Actors (declared with native: in ClassBuilder) override this intrinsic via the compiler's codegen phase.

Deliberately left without a declared return type (BT-2862): the type checker special-cases an unannotated self delegate body to stay Dynamic, since a native override's real return type depends on whichever backing module it delegates to.

Examples

counter delegate   // => ERROR: delegate called on a non-native Actor

Return the raw Erlang PID backing this actor.

Useful for FFI interop where an Erlang function expects a raw pid.

Examples

rawPid := counter pid
rawPid class           // => Pid

The Node this actor lives on (ADR 0126 §2).

Answered by the actor itself, so a TimeoutProxy reports its target's node rather than its own (ADR 0126 §6).

Examples

counter node               // => Node(nonode@nohost)
counter node isCurrent     // => true

Whether this actor lives on a different node from the caller (ADR 0126 §2).

The runtime answers a send of isRemote in the caller's process — asking the actor for its node and comparing it with the caller's node — because the actor itself can only ever see its own node. This body only runs for a self-send, where the caller is the actor, so it is always false there.

Examples

counter isRemote           // => false

Create an Erlang monitor on this actor's process.

Returns a Reference that can be used to cancel the monitor via demonitor. The caller will receive a DOWN message if the actor exits.

Examples

ref := counter monitor
ref class              // => Reference
ref demonitor          // cancel the monitor

Register a callback to be invoked when this actor exits.

Monitors the actor and calls block value: reason when the actor process terminates. Returns #ok immediately. The block is called asynchronously from a lightweight watcher process.

Examples

worker onExit: [:reason |
  Logger info: "worker exited" metadata: #{"reason" => reason displayString}
]

Gracefully stop this actor (gen_server:stop).

Idempotent: stopping an already-stopped actor succeeds silently. Raises an error if the actor times out during shutdown.

Examples

counter stop   // => ok

Forcefully kill this actor (exit(Pid, kill)).

Unlike stop, kill cannot be trapped by the actor process.

Examples

counter kill   // => ok

Check if this actor's process is still alive.

WARNING: isAlive check-then-act is inherently racy. The actor could die between the isAlive check and a subsequent message send. Use monitors for robust lifecycle management.

Examples

counter isAlive   // => true or false