コンテンツにスキップ
日本語

ActorOptionsType

このコンテンツはまだ日本語訳がありません。

ActorOptionsType<TMessage> = object

Defined in: src/ActorOptions.ts:46

Plain options-object shape accepted wherever an actor is spawned.

TMessage = unknown

readonly optional applicationOwned?: boolean

Defined in: src/ActorOptions.ts:177

This actor’s class came from the application, even though the framework spawned it (#862).

Two populations are like this, and both are large: a sharded entity, whose parent chain is ShardRegion → Shard under /system, and a cluster singleton, spawned by its manager there. Where an actor sits in the tree therefore does not answer “whose actor is this” — which is the question system-wide application policy has to ask, because that policy exists to let an operator reach code they cannot edit. Two such policies exist: actor-ts.mailbox.default.capacity and the per-path actor-ts.deployment entries (#868), whose /system keys reach exactly these two populations.

Children inherit it: an entity’s children are the application’s too. The framework’s own actors under /system never carry it, and must not — a bounded mailbox on a coordinator or a gossip actor sheds messages that hold a cluster invariant together.

ClusterSharding and ClusterSingleton set this themselves. It is public for the same reason entity is — a test bench that spawns an entity without a cluster behind it — and setting it on an actor already under /user changes nothing.


readonly optional dispatcher?: Dispatcher

Defined in: src/ActorOptions.ts:55

Run this actor on a different dispatcher than the system’s.


readonly optional displayName?: string

Defined in: src/ActorOptions.ts:188

Human-readable name for log lines and the DevTools tree (#891) — the spawn-site counterpart to overriding Actor.displayName(), for a framework-constructed actor with no subclass of your own: a Behaviors actor, a sharded entity, a singleton.

Outranks the method, exactly as supervisorStrategy outranks Actor.supervisorStrategy(). Purely cosmetic — the path stays the identity everywhere that routes or correlates.


readonly optional entity?: EntityContext

Defined in: src/ActorOptions.ts:198

Spawn this actor as a sharded entity with the given identity, readable back off this.entityId / this.context.entity.

ClusterSharding sets this itself for every entity a shard creates. It is public for the test bench: an entity that derives its persistenceId from this.entityId is otherwise unspawnable without a cluster standing behind it.


readonly optional internal?: boolean

Defined in: src/ActorOptions.ts:153

This actor belongs to the tooling, not to the application.

Whole-system instrumentation skips it, which is what keeps a debugger from observing itself: DevTools’ own hub publishes the spans it just recorded, so tracing it feeds its own output back in. Children inherit the mark — a tooling actor’s children are tooling.


readonly optional mailbox?: MailboxFactory<TMessage>

Defined in: src/ActorOptions.ts:144

Custom mailbox — PriorityMailbox, ControlAwareMailbox (control messages dequeued ahead of the rest, #1431), a BoundedMailbox configured beyond what mailboxCapacity / mailboxOverflow express, or a Mailbox subclass of your own. Omit for the default unbounded FIFO queue.

Drops still reach actor_mailbox_dropped_total: the cell registers its observer on whatever you return, provided the mailbox implements DropReportingMailbox (all three built-in variants do, through DroppingMailbox). Any onDrop of your own keeps firing alongside it.


readonly optional mailboxCapacity?: number

Defined in: src/ActorOptions.ts:114

Bound this actor’s mailbox at mailboxCapacity queued user messages. Unset falls through to the mailbox-capacity of the actor-ts.deployment entry matching the actor’s path (#868) — where 0 means unbounded whatever the global bound says — then to actor-ts.mailbox.default.capacity, which is 0, meaning no global bound, and then to unbounded, which is the shipped answer. So setting one of the three is the act that introduces message loss, and mailboxOverflow decides which message is lost. Cannot be combined with mailbox, which brings its own bound.

What it never loses is anything the framework posts through ActorCell.postSignalEnvelope. That door — not the message that goes through it — is the rule: since #729 it stamps Envelope.undroppable and routes to Mailbox.enqueueSignal, a lane no overflow policy can shed. Four senders use it, from five call sites: a death-watch Terminated, posted by ActorCell._notifyWatcher for a local death and by ActorCell.onWatchNotify for one another node reported (#918); the websocket-accept command that hands an upgraded socket to its hub (#717); the close a WebsocketConnection sends its own actor (#985); and the DistributedDataChanged a DistributedData replicator posts to an actor subscribed to one of its keys (#1468). So bounding a watcher costs it backlog and not the deaths it is watching for, bounding a hub cannot orphan a socket it has already accepted, bounding a connection cannot turn a closeAll into a socket that stays open, and bounding a subscriber cannot leave its subscription waiting for ever on a notification it was never handed.

Exempt is not early (#1431). The door decides that an envelope survives the bound, never where it lands, so each of the five still queues behind the backlog it arrives after — which is what keeps death watch and reply-then-close in order. An actor whose control traffic must overtake its backlog says so with mailbox and a ControlAwareMailbox. The WebSocket hub is the one exception, and it needs no spawn option: it names its control messages through the internal Actor._controlMessages() hook, and the cell gives it a ControlAwareMailbox holding the bound this field (or a layer under it) set — shape 5 of ActorCell._createMailbox.


readonly optional mailboxOverflow?: BoundedMailboxOverflow

Defined in: src/ActorOptions.ts:131

What a full mailbox does with an arriving message. Only meaningful together with mailboxCapacity — an unbounded mailbox is never full — so setting it alone is rejected rather than silently ignored. Falls through to the mailbox-overflow of the actor-ts.deployment entry matching the actor’s path (#868), then to actor-ts.mailbox.default.overflow, then to DEFAULT_MAILBOX_OVERFLOW.

The rejection stands even where a configured bound exists (#862): the validator has no Config and must not grow one, so it cannot tell an intended override of a global or per-path bound from the no-op the rule was written for. Restate the capacity alongside the policy to reshape a configured bound for one actor, or set the policy in the same entry or block as the capacity.


readonly optional supervisorStrategy?: SupervisorStrategy

Defined in: src/ActorOptions.ts:53

How the parent handles this actor’s failures. Distinct from the supervisorStrategy() override inside the actor class, which governs its children. Set here, a single child opts out of its parent’s policy without affecting its siblings.


readonly optional throughput?: number

Defined in: src/ActorOptions.ts:74

User messages this actor handles per dispatcher turn before it yields (#409). Unset falls through to the actor-ts.deployment entry matching the actor’s path (#868), then to actor-ts.actor.throughput, then to the built-in default — so this is the highest-precedence layer, not a replacement for the configured ones.

Raise it for an actor that is a throughput bottleneck and whose handler is short; the scheduling round trip it amortises costs more than such a handler does. Lower it toward 1 for an actor whose handler is slow enough that a full batch would keep timers and I/O waiting — the batch runs to its budget without yielding, so the budget is the latency other work can see.

A batch always ends early on anything that changes the actor’s situation: an empty mailbox, a suspend or stop, and a throttle bucket that runs out mid-batch.