ClassBuilder

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

Return the class of the receiver.

Examples

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

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

Examples

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

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

Examples

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

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

_nilBlock is never evaluated on this Object-level definition (only UndefinedObject's override calls it, with Block(R) -> R), so R is unconstrained here — parameterizing it still documents the zero-arg shape without implying this branch produces R (BT-2834).

Examples

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

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

Left as a bare Block deliberately (BT-2834): notNilBlock is invoked one-arg with self and its result becomes the method's own result, so a precise signature needs a Self-in-Block(...) type-arg form (Block(Self, R) -> R) with no precedent elsewhere in stdlib. The type checker doesn't consult this declared signature for ifNotNil: anyway — it narrows the block's parameter from the receiver's own type via infer_args_for_if_not_nil in inference.rs (BT-2046), independent of this stdlib declaration.

Examples

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

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

Bare Block params here (unlike UndefinedObject's Block(R) -> R override, BT-2824) are intentional, not an oversight: the type checker never consults this declared signature for these two selectors — it reads the block arguments' actual inferred return types directly (if_nil_branch_union_ret_ty in inference.rs, BT-2047) since a bare -> R here can't express "whatever the block returns" without a Self-in-Block(...) type-arg form with no precedent elsewhere in stdlib.

Examples

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

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

See ifNil:ifNotNil: above — the bare Block params are intentional.

Examples

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

Return the developer-readable (Debug) string representation.

printString is the Debug protocol (ADR 0094): the self-describing, structural form used by the REPL, logs, and by any other printString that nests this object. It is the REPL default — evaluating an expression shows its printString.

This default returns the bare class name (no a/an article — the old "a ClassName" form was dropped in ADR 0094). Value overrides it with the structural ClassName(field: value, ...) form, actors render as Actor(ClassName, pid), supervisors as Supervisor(ClassName, pid) / DynamicSupervisor(ClassName, pid), and primitive types (Integer, String, List, …) override it with their own richer output. Authors rarely override printString directly — the default is derived.

Examples

42 printString            // => "42"

Return the user-facing (Display) string representation.

displayString is the Display protocol (ADR 0094): the human-facing form. It is the hook the language pulls during string interpolation — every {...} segment renders via the value's displayString. Developers rarely call it directly; they override it when a value has a natural human rendering (e.g. Money → $10.50, where printString would still show the Debug form).

It defaults to printString, so most types need no override. String and Symbol demonstrate the split: "hi" printString → "\"hi\"" (quoted, Debug) while "hi" displayString → "hi" (plain, Display); likewise #foo drops its # prefix under displayString.

displayString is not part of the Printable protocol (deferred per ADR 0094 §5).

Examples

42 displayString             // => "42"

Open a navigable Inspector cursor on the receiver.

ADR 0095 Phase 3 (BT-2504). inspect is repurposed from -> String (the ADR-0094 deferral) to the verb that produces an Inspector — a live, immutable cursor for drilling into the object (Inspector on: self). anObject inspect is the shorthand; Inspector on: anObject is the explicit spelling. The cursor exposes fields/at:/path/refresh/ printString (an indented text tree) and asDictionaries (the MCP/browser wire form); see Inspector.

This is a breaking change: code that used inspect for its old String result must switch to printString (the structural Debug string, ADR 0094) — a transitional lint flags inspect used directly in ++/ string position.

Examples

42 inspect kind                  // => #value
(Point x: 3 y: 4) inspect fields size   // => 2
(Point x: 3 y: 4) printString    // => "Point(x: 3, y: 4)"  (the old inspect string)

Return the receiver itself. Useful for cascading side effects.

Examples

42 yourself            // => 42

Return a hash value for the receiver.

Examples

42 hash

Test value equality — the overridable counterpart to =:=.

Defaults to =:= (Erlang structural term equality), so for most classes the two agree. Unlike =:=, this is an ordinary message send, so a class whose logical value is not its representation can override it: a persistent structure whose shape depends on construction history, a timestamp that should compare by instant rather than by wall-clock fields, or a type with a normalising form. =:=, =/=, == and /= are lowered straight to Erlang BIFs (ADR 0002) and cannot be overridden — the compiler rejects any attempt (BT-2997).

What honours it

The linear scans: includes: on Collection, List, Array and Dictionary (which searches values), plus List>>indexOf: and TestCase>>assert:equals:.

Contract

An override must agree with =:= wherever =:= holds — a =:= b must imply a equals: b. It may only make more values equal, never fewer. The scans above rely on this: each tries raw =:= first and dispatches only on a miss, so a fast-path hit is always a genuine equals: hit.

Caveat

Set, Dictionary keys, and List>>unique decide identity in the VM with raw =:=, never through this method — keying and deduplication need an order or a hash that a user-defined equals: cannot supply. A class that overrides equals: still deduplicates by representation when used as a key or element. Normalise the representation if that matters.

Examples

42 equals: 42           // => true
42 equals: 42.0         // => false (defaults to strict `=:=`)
"ab" equals: "ab"       // => true

Test if the receiver responds to the given selector.

Examples

42 respondsTo: #abs    // => true

Return the names of fields.

Examples

42 fieldNames             // => #()

Return the value of the named field.

Left without a declared return type deliberately (BT-2834 pattern, see Block>>value): the field's actual value can be any type, and callers routinely send it further messages ((self fieldAt: #x) + 1) that a fixed -> Object would statically reject.

Examples

object fieldAt: #name

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

Examples

object fieldAt: #name put: "Alice"

Test whether the receiver has the named field. Never raises — the non-raising counterpart to fieldAt:, in particular for a late slot (ADR 0124): fieldAt: raises UninitializedStateError reading an unassigned late slot, hasField: is the question to ask first.

Examples

c := CodexClient start: "/tmp/ws" config: cfg onEvent: nil
c hasField: #proc      // => false — declared `late`, not yet assigned
c launch
c hasField: #proc      // => true
42 hasField: #anything // => false — primitives have no fields

Return a late field to the unassigned state (ADR 0124), so it can be assigned again (e.g. re-acquiring a resource). Joins fieldAt:/ fieldAt:put:/fieldNames in ADR 0035's field-prefixed reflection family. Returns self.

Examples

c clearField: #proc
c hasField: #proc       // => false — relaunchable

Send a unary message dynamically.

Left without a declared return type deliberately (BT-2834 pattern, see fieldAt: above): the invoked method's return type is unknown statically, and a fixed -> Object would block legitimate chained sends on the real (narrower) result.

Examples

42 perform: #abs       // => 42

Send a message dynamically with arguments.

See perform: above for why no return type is declared.

Examples

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

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

Examples

self subclassResponsibility

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

Send aValue to Transcript without a trailing newline.

Outside an interactive workspace this is a Logger notice (ADR 0129 §5).

Examples

42 show: "value: "

Send aValue to Transcript followed by a newline.

Outside an interactive workspace this is a Logger notice (ADR 0129 §5).

Examples

42 showCr: "hello world"

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)

Raise an error with the given message.

Examples

self error: "something went wrong"

Delegate message dispatch to the backing Erlang module (ADR 0101, BT-2720).

This method is a sentinel — a plain Object has no backing Erlang module, so calling delegate raises an Error at runtime. Stateless Objects declared with native: have their self delegate method bodies rewritten by the compiler's codegen phase to call the backing module directly, so the sentinel is never reached on a native: class.

Unlike Actor's delegate (visible only to Actor subclasses), this Object-base sentinel is visible to every class, so delegate is a reserved selector on the Object protocol.

Examples

42 delegate   // => ERROR: delegate called on a non-native Object

Test value equality (Erlang ==, non-strict — 1 == 1.0 is true).

Examples

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

Test value inequality (negation of ==).

Examples

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

Test strict value equality (Erlang =:= — 1 =:= 1.0 is false, unlike ==).

Every object supports this at runtime (it lowers directly to Erlang's =:= operator regardless of receiver type, ADR 0002) — declared here, once, so it is visible in method listings/completions/respondsTo: for every class, not just the handful (Integer, String, ...) that separately redeclare it with a narrower, class-typed other for documentation purposes.

Examples

1 =:= 1             // => true
1 =:= 1.0           // => false (strict — different types)
(Dictionary new) =:= #{}   // => true

Test strict value inequality (negation of =:=).

Examples

1 =/= 1.0           // => true (strict — different types)
1 =/= 1             // => false

Return the class of the receiver.

Examples

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

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

No declared return type (BT-2834 pattern, see Object>>fieldAt:): a custom override can return any type, and callers chain further sends on the result that a fixed -> Object would statically reject.

Examples

42 unknownMessage   // => ERROR: does_not_understand

Send a message dynamically with an arguments list.

Examples

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

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)

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