ActorOptionsType
Это содержимое пока не доступно на вашем языке.
ActorOptionsType<
TMessage> =object
Defined in: src/ActorOptions.ts:46
Plain options-object shape accepted wherever an actor is spawned.
Type Parameters
Section titled “Type Parameters”TMessage
Section titled “TMessage”TMessage = unknown
Properties
Section titled “Properties”applicationOwned?
Section titled “applicationOwned?”
readonlyoptionalapplicationOwned?: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.
dispatcher?
Section titled “dispatcher?”
readonlyoptionaldispatcher?:Dispatcher
Defined in: src/ActorOptions.ts:55
Run this actor on a different dispatcher than the system’s.
displayName?
Section titled “displayName?”
readonlyoptionaldisplayName?: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.
entity?
Section titled “entity?”
readonlyoptionalentity?: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.
internal?
Section titled “internal?”
readonlyoptionalinternal?: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.
mailbox?
Section titled “mailbox?”
readonlyoptionalmailbox?: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.
mailboxCapacity?
Section titled “mailboxCapacity?”
readonlyoptionalmailboxCapacity?: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.
mailboxOverflow?
Section titled “mailboxOverflow?”
readonlyoptionalmailboxOverflow?: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.
supervisorStrategy?
Section titled “supervisorStrategy?”
readonlyoptionalsupervisorStrategy?: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.
throughput?
Section titled “throughput?”
readonlyoptionalthroughput?: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.
