ActorContext
Este conteúdo não está disponível em sua língua ainda.
Defined in: src/ActorContext.ts:20
Runtime API given to every Actor. Access through this.context inside
an Actor subclass.
Type Parameters
Section titled “Type Parameters”TMessage
Section titled “TMessage”TMessage = unknown
Properties
Section titled “Properties”children
Section titled “children”
readonlychildren: readonlyActorRef<unknown>[]
Defined in: src/ActorContext.ts:47
Snapshot of direct children.
cluster
Section titled “cluster”
readonlycluster:Option<Cluster>
Defined in: src/ActorContext.ts:41
The Cluster this actor’s system joined, None on a local-only
system (#833). Ask this when the actor has to work either way —
it answers rather than throws.
Inside code that only ever runs clustered, prefer the this.cluster
getter on Actor: same object, no unwrapping.
entity
Section titled “entity”
readonlyentity:Option<EntityContext>
Defined in: src/ActorContext.ts:61
Sharding identity when ClusterSharding started this actor as an
entity, None for every other actor.
Set on the entity itself and nowhere else — an entity’s own children
get None — so Some here means “I am the entity”, not “I live
under one”. A child that needs the id gets it passed down.
Inside an entity, prefer the this.entityId / this.entity getters on
Actor: they answer the same question without the unwrapping,
because entity code already knows it is an entity.
readonlylog:Logger
Defined in: src/ActorContext.ts:67
Logger bound to this actor’s path, and to whatever
Actor.displayName() currently resolves to.
parent
Section titled “parent”Defined in: src/ActorContext.ts:44
Parent actor, or None for the root guardian.
readonlypath:ActorPath
Defined in: src/ActorContext.ts:25
The ActorPath of this actor.
readonlyself:ActorRef<TMessage>
Defined in: src/ActorContext.ts:22
A reference to this actor.
sender
Section titled “sender”Defined in: src/ActorContext.ts:28
The sender of the message currently being processed, or None.
stashSize
Section titled “stashSize”
readonlystashSize:number
Defined in: src/ActorContext.ts:236
Number of currently-stashed messages.
system
Section titled “system”
readonlysystem:ActorSystem
Defined in: src/ActorContext.ts:31
The enclosing ActorSystem.
timers
Section titled “timers”
readonlytimers:TimerScheduler<TMessage>
Defined in: src/ActorContext.ts:269
Per-actor scheduling facade. Timers are identified by user-supplied string keys and are automatically cancelled when the actor stops.
Methods
Section titled “Methods”actorSelection()
Section titled “actorSelection()”actorSelection(
path):ActorSelection
Defined in: src/ActorContext.ts:123
Build an ActorSelection that resolves a full-path lookup. Delegates to
the enclosing ActorSystem — same semantics as system.actorSelection.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”become()
Section titled “become()”become(
behavior,discardOld?):void
Defined in: src/ActorContext.ts:193
Replace the current behaviour. When discardOld is false, the previous
behaviour is pushed onto a stack and can be restored via unbecome().
Parameters
Section titled “Parameters”behavior
Section titled “behavior”Receive<TMessage>
discardOld?
Section titled “discardOld?”boolean
Returns
Section titled “Returns”void
cancelReceiveTimeout()
Section titled “cancelReceiveTimeout()”cancelReceiveTimeout():
void
Defined in: src/ActorContext.ts:205
Disable the receive timeout.
Returns
Section titled “Returns”void
cancelThrottle()
Section titled “cancelThrottle()”cancelThrottle():
void
Defined in: src/ActorContext.ts:297
Remove any active throttle, restoring unlimited dequeue rate.
Returns
Section titled “Returns”void
child()
Section titled “child()”Defined in: src/ActorContext.ts:117
Look up a direct child by name. None if no such child exists.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”disableExplainPlan()
Section titled “disableExplainPlan()”disableExplainPlan():
void
Defined in: src/ActorContext.ts:258
Stop recording and discard what was recorded.
Returns
Section titled “Returns”void
enableExplainPlan()
Section titled “enableExplainPlan()”enableExplainPlan(
options?):void
Defined in: src/ActorContext.ts:255
Start recording this actor’s recent message handlings — type, sender, mailbox wait, handling time and outcome — for the DevTools explain plan or for reading back in code.
Opt-in per actor because it is not free: recording every message on every actor would cost more than many of the handlers being measured. Enabling it also starts timestamping this actor’s incoming envelopes, which is what makes the mailbox-wait figure possible.
override preStart(): void { this.context.enableExplainPlan({ capacity: 100 });}Parameters
Section titled “Parameters”options?
Section titled “options?”capacity?
Section titled “capacity?”number
Returns
Section titled “Returns”void
explainPlan()
Section titled “explainPlan()”explainPlan(): readonly
MessageExplain[]
Defined in: src/ActorContext.ts:261
Recorded handlings, oldest first. Empty while recording is off.
Returns
Section titled “Returns”readonly MessageExplain[]
offload()
Section titled “offload()”offload<
TArgs,TResult>(task,args,options?):Promise<TResult>
Defined in: src/ActorContext.ts:311
Run a pure function on a worker thread and get its result back
(#1558) — the system’s default OffloadPool, built from
actor-ts.offload-pool.* on first use. task names an export of a
module (defineOffloadTask), because a function cannot cross a thread;
args are structured-cloned, and so is the result.
The result is a later message: the handler that started the run has
returned by the time it arrives, so feed it back to yourself
(pipeTo, a tell to self) rather than touching state from the
continuation as if it were still the same turn.
Type Parameters
Section titled “Type Parameters”TArgs extends readonly unknown[]
TResult
Section titled “TResult”TResult
Parameters
Section titled “Parameters”OffloadTask<TArgs, TResult>
TArgs
options?
Section titled “options?”Returns
Section titled “Returns”Promise<TResult>
setDisplayName()
Section titled “setDisplayName()”setDisplayName(
name):void
Defined in: src/ActorContext.ts:84
Name this actor in log lines and in the DevTools tree from inside the
running actor (#891) — for a name that only becomes known at runtime
(after recovery, after the first message), and for Behaviors actors,
which have no subclass to override Actor.displayName() on:
Behaviors.setup<Command>((context) => { context.setDisplayName(`User(${userId})`); return Behaviors.receive(...);});Takes effect on the very next record, and outranks both
ActorOptions.withDisplayName(...) and the method. Purely cosmetic — the
path stays the identity everywhere that routes or correlates.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”void
setReceiveTimeout()
Section titled “setReceiveTimeout()”setReceiveTimeout(
ms):void
Defined in: src/ActorContext.ts:202
Fire a ReceiveTimeout message when no user message has been received in
ms. Pass 0 to disable.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”void
spawn()
Section titled “spawn()”spawn<
T>(actor,name,options?):ActorRef<T>
Defined in: src/ActorContext.ts:91
Spawn a child actor under this one with a deterministic caller-supplied name. The name must be unique among siblings. For an auto-generated name, see spawnAnonymous.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”string
options?
Section titled “options?”ActorOptions<T>
Returns
Section titled “Returns”ActorRef<T>
spawnAnonymous()
Section titled “spawnAnonymous()”spawnAnonymous<
T>(actor,options?):ActorRef<T>
Defined in: src/ActorContext.ts:99
Spawn a child actor under this one with an auto-generated name. Useful for one-shot helpers and other transient children where the caller doesn’t need a stable path. For a deterministic name, see spawn.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”options?
Section titled “options?”ActorOptions<T>
Returns
Section titled “Returns”ActorRef<T>
spawnTyped()
Section titled “spawnTyped()”spawnTyped<
T>(behavior,name):ActorRef<T>
Defined in: src/ActorContext.ts:108
Spawn a typed-Behavior child with a deterministic name — the
Behavior-DSL counterpart to spawn. Wraps the Behavior
in typedActor internally so callers don’t have to.
const child = this.context.spawnTyped(counter(0), 'counter');Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”behavior
Section titled “behavior”Behavior<T>
string
Returns
Section titled “Returns”ActorRef<T>
spawnTypedAnonymous()
Section titled “spawnTypedAnonymous()”spawnTypedAnonymous<
T>(behavior):ActorRef<T>
Defined in: src/ActorContext.ts:114
Anonymous variant of spawnTyped — the Behavior-DSL counterpart to spawnAnonymous.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”behavior
Section titled “behavior”Behavior<T>
Returns
Section titled “Returns”ActorRef<T>
stash()
Section titled “stash()”stash():
void
Defined in: src/ActorContext.ts:227
Buffer the message currently being handled. It is reinserted into the
mailbox when unstashAll() is called. Throws if called outside a
user-message handler or if the stash is full.
A death-watch notification is the one message whose round trip is not
symmetric, and it is worth knowing which half you are on before you park
one (#1098). A registration is consumed by the death it describes, so it
is already gone when the replay arrives. Under watchWith that
costs nothing — what gets parked is the domain message the behavior was
handed, and it comes back as the ordinary user message it always was.
Under a plain watch the parked message is the Terminated, and
the cell has nothing left to recognise it by: it becomes a dead letter
instead of a second delivery. So park a death you mean to come back to
only when you registered it with watchWith; otherwise handle it where it
arrives, or record what you need from it before stashing something of your
own.
Returns
Section titled “Returns”void
stop()
Section titled “stop()”stop(
ref):void
Defined in: src/ActorContext.ts:126
Ask the runtime to stop the given actor. Equivalent to ref.stop().
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
stopSelf()
Section titled “stopSelf()”stopSelf():
void
Defined in: src/ActorContext.ts:129
Stop this actor itself.
Returns
Section titled “Returns”void
throttle()
Section titled “throttle()”throttle(
options):void
Defined in: src/ActorContext.ts:294
Throttle this actor’s user-message processing to a token-bucket rate (#83). Every dequeue from the user mailbox consumes one token; when the bucket is empty the cell behaves per ThrottleOnExcess. System commands (create, terminate, supervision, …) are NOT throttled — they run on the system queue, ahead of user messages, so timer fires and lifecycle events stay responsive.
A death-watch Terminated is on the user queue and is exempt all the
same: it consumes no token and is never the message an onExcess: 'drop'
discards, because the framework announces a death once (#729). Before
that exemption this JSDoc claimed the exemption anyway and the code did
the opposite.
Calling throttle again replaces the existing limiter; pass
{ qps: Infinity } or call cancelThrottle to remove one.
Cluster-aware variants (split a budget across cluster-router routees, etc.) are out of scope here — this is per-actor only.
Parameters
Section titled “Parameters”options
Section titled “options”Returns
Section titled “Returns”void
unbecome()
Section titled “unbecome()”unbecome():
void
Defined in: src/ActorContext.ts:196
Pop the behaviour stack, restoring the previous behaviour.
Returns
Section titled “Returns”void
unstashAll()
Section titled “unstashAll()”unstashAll():
void
Defined in: src/ActorContext.ts:233
Prepend every stashed message back onto the user mailbox in the order they were stashed. The buffer is empty afterwards.
Returns
Section titled “Returns”void
unwatch()
Section titled “unwatch()”unwatch(
ref):ActorRef
Defined in: src/ActorContext.ts:187
Stop watching — whether registered via watch or watchWith.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”watch()
Section titled “watch()”watch(
ref):ActorRef
Defined in: src/ActorContext.ts:150
Start death-watching an actor. A Terminated message is sent when it
stops.
It arrives on this actor’s ordinary user queue, behind every tell already
waiting there, and it cannot be lost on the way: a mailbox bound and a
throttle({ onExcess: 'drop' }) both step over it, because the framework
sends it once and has no way to send it again (#729). A watcher that
cannot be reached at all — it has already stopped — gets a dead letter, so
the loss is visible rather than silent.
A RemoteActorRef is watched across the cluster (#918): the far node
reports the stop, answers a path it cannot resolve at once with
existenceConfirmed = false, and a node that is downed or removed
surfaces as addressTerminated = true, synthesised from membership. On a
system that has not joined a cluster, or for a ref shape the framework
cannot watch, the call records the subject and warns that no
Terminated can come — it never fails silently.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”watchWith()
Section titled “watchWith()”watchWith(
ref,message):ActorRef
Defined in: src/ActorContext.ts:184
Death-watch ref, but deliver message instead of Terminated(ref).
Terminated answers “did that one die?”, which forces every watcher to
carry the signal in its protocol and to re-derive the meaning of the death
from Terminated.actor. A watcher that watches several kinds of actor —
workers, a connection, a peer — ends up with one handler branching on ref
identity. watchWith moves that decision to registration time, so each
death arrives as the domain message the watcher already handles:
this.context.watchWith(worker, { kind: 'workerLost', name });this.context.watchWith(connection, { kind: 'connectionLost' });message must belong to this actor’s own protocol — it is delivered to
onReceive like any other user message, not as a signal. “Like any other”
covers ordering and nothing else: it is queued behind whatever is already
there, and it is exempt from this actor’s mailbox bound and throttle for
the same reason the Terminated it replaces is (#729) — a death is
announced once.
It is also what stash parks. The behavior is handed message, so
parking it parks a protocol message, and it replays on unstashAll() like
any other (#1098). That is the one thing a plain watch cannot
offer: there the parked message is the signal itself, and the registration
that would admit it a second time was retired by the first delivery.
Last call wins: watchWith on an already-watched ref replaces whatever the
previous watch/watchWith registered, and a later plain watch drops the
custom message again. The registration is consumed by the death it
describes — watching the same name again after a restart is a new
subject and needs a new call.
Parameters
Section titled “Parameters”message
Section titled “message”TMessage
