Actor

Inherits from Object

Actor — Base class for process-based objects.

Actor inherits from Object and adds process-based concurrency. Every actor runs in its own BEAM process and communicates via asynchronous messages. Use spawn instead of new to create actors.

Examples

Actor subclass: Counter
  state: count = 0
  increment => self.count := self.count + 1
  count => self.count

@see Value (for immutable data without a process) @see Supervisor (for static supervision trees) @see DynamicSupervisor (for dynamic supervision trees)

Class Methods

spawn Sealed source

Spawn a new actor process with default state.

Examples

c := Counter spawn

spawnWith: initArgs Sealed source

Spawn a new actor process with initialization arguments.

Examples

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

spawnAs: name Sealed source

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"]

spawnWith: initArgs as: name Sealed source

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

named: name Sealed source

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)

allRegistered Sealed source

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.

Examples

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

supervisionPolicy source

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)

isSupervisor source

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)

supervisionSpec source

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}

Instance Methods

registerAs: name Sealed source

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 Sealed source

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

registeredName Sealed source

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

Examples

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

isRegistered Sealed source

Whether this actor currently has a registered name.

Examples

counter isRegistered   // => true or false

withTimeout: ms source

Wrap this actor with a custom message timeout.

Returns a TimeoutProxy that forwards all messages to this actor using the given timeout (in milliseconds, 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

initialize source

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 := #()

terminate: _reason source

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 during graceful shutdown (stop). 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:.

Examples

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

delegate Sealed source

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.

Examples

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

pid Sealed source

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

monitor Sealed source

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

onExit: block Sealed source

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}
]

stop Sealed source

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

kill Sealed source

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

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

Examples

counter kill   // => ok

isAlive Sealed source

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

Inherited Methods

From Object

class

Return the class of the receiver.

Examples

42 class              // => Integer
"hello" class         // => String

isNil

Test if the receiver is nil. Returns false for all objects except nil.

Examples

42 isNil              // => false
nil isNil             // => true

notNil

Test if the receiver is not nil. Returns true for all objects except nil.

Examples

42 notNil             // => true
nil notNil            // => false

ifNil: _nilBlock

If the receiver is nil, evaluate nilBlock. Otherwise return self.

Examples

42 ifNil: [0]         // => 42
nil ifNil: [0]        // => 0

ifNotNil: notNilBlock

If the receiver is not nil, evaluate notNilBlock with self.

Examples

42 ifNotNil: [:v | v + 1]   // => 43
nil ifNotNil: [:v | v + 1]  // => nil

ifNil: _nilBlock ifNotNil: notNilBlock

If nil, evaluate nilBlock; otherwise evaluate notNilBlock with self.

Examples

42 ifNil: [0] ifNotNil: [:v | v + 1]    // => 43
nil ifNil: [0] ifNotNil: [:v | v + 1]   // => 0

ifNotNil: notNilBlock ifNil: _nilBlock

If not nil, evaluate notNilBlock with self; otherwise evaluate nilBlock.

Examples

42 ifNotNil: [:v | v + 1] ifNil: [0]    // => 43
nil ifNotNil: [:v | v + 1] ifNil: [0]   // => 0

printString

Return a developer-readable string representation.

Default implementation returns "a ClassName". Subclasses such as Integer, String, and List override this to return richer output.

Examples

42 printString            // => "42"

displayString

Return a user-facing string representation for display purposes.

Default implementation delegates to printString. Subclasses such as String and Symbol override this to return a more readable form without developer annotations (e.g. no surrounding quotes or # prefix).

Examples

42 displayString             // => "42"

inspect

Inspect the receiver.

Examples

42 inspect             // => "42"

yourself Sealed

Return the receiver itself. Useful for cascading side effects.

Examples

42 yourself            // => 42

hash

Return a hash value for the receiver.

Examples

42 hash

respondsTo: selector Sealed

Test if the receiver responds to the given selector.

Examples

42 respondsTo: #abs    // => true

fieldNames Sealed

Return the names of fields.

Examples

42 fieldNames             // => #()

fieldAt: name Sealed

Return the value of the named field.

Examples

object fieldAt: #name

fieldAt: name put: value Sealed

Set the value of the named field (returns new state).

Examples

object fieldAt: #name put: "Alice"

perform: selector Sealed

Send a unary message dynamically.

Examples

42 perform: #abs       // => 42

perform: selector withArguments: args Sealed

Send a message dynamically with arguments.

Examples

3 perform: #max: withArguments: #(5)   // => 5

subclassResponsibility

Raise an error indicating this method must be overridden by a subclass.

Examples

self subclassResponsibility

notImplemented

Raise an error indicating this method has not yet been implemented.

Use this for work-in-progress stubs. Distinct from subclassResponsibility, which signals an interface contract violation.

Examples

self notImplemented

show: aValue

Send aValue to the current transcript without a trailing newline.

Nil-safe: does nothing when no transcript is set (batch compile, tests).

Examples

42 show: "value: "

showCr: aValue

Send aValue to the current transcript followed by a newline.

Nil-safe: does nothing when no transcript is set (batch compile, tests).

Examples

42 showCr: "hello world"

isKindOf: aClass

Test if the receiver is an instance of aClass or any of its subclasses.

For class-object receivers, follows Smalltalk semantics: self class is the metaclass, so the check walks the parallel metaclass hierarchy. The parallel chain is grounded at ProtoObject class superclass == Class (ADR 0036), so the metaclass tower merges into the instance-side Class → Behaviour → Object → ProtoObject chain. As a result, Integer isKindOf: Object and Integer isKindOf: Class both return true.

Examples

42 isKindOf: Integer        // => true
42 isKindOf: Object         // => true
#foo isKindOf: Symbol       // => true
#foo isKindOf: String       // => false
Integer isKindOf: Number    // => false (metaclass chain, not instance chain)
Integer isKindOf: Number class  // => true  (Number class is in the parallel chain)
Integer isKindOf: Object    // => true (grounded — Object is reachable via the metaclass tower)
Integer isKindOf: Class     // => true (Integer class inherits from Class)

error: message

Raise an error with the given message.

Examples

self error: "something went wrong"

From ProtoObject

== other

Test value equality (Erlang ==).

Examples

42 == 42           // => true
"abc" == "abc"     // => true

/= other

Test value inequality (negation of ==).

Examples

1 /= 2             // => true
42 /= 42           // => false

class

Return the class of the receiver.

Examples

42 class            // => Integer
"hello" class       // => String

doesNotUnderstand: selector args: arguments

Handle messages the receiver does not understand. Override for custom dispatch.

Examples

42 unknownMessage   // => ERROR: does_not_understand

perform: selector withArguments: arguments

Send a message dynamically with an arguments list.

Examples

42 perform: #abs withArguments: #()   // => 42

performLocally: selector withArguments: arguments

Execute a class method in the caller's process, bypassing gen_server dispatch.

The caller takes responsibility for knowing the method does not mutate class state. Useful for long-running class methods that would otherwise block the class object's gen_server.

Limitations: only resolves methods defined directly on the target class module (does not walk the superclass chain). Class variables and self are not available to the method (nil and #{} are passed).

Examples

MyClass performLocally: #run:ctx: withArguments: #(input, ctx)

perform: selector withArguments: arguments timeout: timeoutMs

Send a message dynamically with an arguments list and explicit timeout.

The timeout (in milliseconds or #infinity) applies to the gen_server:call when the receiver is an actor. For value types, timeout is ignored.

Examples

actor perform: #query withArguments: #(sql) timeout: 30000