Pular para o conteúdo
Português (BR)

ControlAwareMailboxOptionsType

Este conteúdo não está disponível em sua língua ainda.

ControlAwareMailboxOptionsType<T> = object

Defined in: src/mailbox/ControlAwareMailboxOptions.ts:7

Plain options-object shape accepted by a ControlAwareMailbox.

T

readonly optional capacity?: number

Defined in: src/mailbox/ControlAwareMailboxOptions.ts:42

Maximum queued ordinary messages. Unset means unbounded, which is the default: a mailbox chosen so that some messages may overtake others has not thereby decided that any may be lost.

Control messages are not counted and never shed. Under a flood the ordinary class is what the bound protects memory from; a control message is the one the flood was delaying, so shedding it would turn the reason the mailbox was chosen into its loss.

It lives here rather than on ActorOptions because ActorOptionsValidator rejects withMailbox combined with withMailboxCapacity: a supplied mailbox brings its own bound.


readonly optional deadLetterDrops?: boolean

Defined in: src/mailbox/ControlAwareMailboxOptions.ts:70

Route every dropped envelope to system.deadLetters rather than only counting it (#773). Default false, for the reason BoundedMailboxOptionsType.deadLetterDrops gives: the drop runs on the sender’s stack, and a dead letter is a durable capture plus a synchronous publish.


readonly isControl: (message) => boolean

Defined in: src/mailbox/ControlAwareMailboxOptions.ts:27

Which messages are control messages — dequeued before every ordinary message, and never shed by the bound.

Only an answer of exactly true makes a message control. A throw, or any other answer, classes it ordinary, which is where it would have been on any other mailbox: the predicate runs synchronously inside the sender’s tell, and a sender is a bystander to the receiver’s mailbox configuration. PoisonPill and Kill reach the predicate too — ActorRef.stop() and .kill() post them as user messages, and neither has a field to match on — so a predicate written for the actor’s own protocol meets them on the framework’s own shutdown path. A throw is reported all the same: see onControlError.

Keep it to a check of the message’s shape. A message that is control overtakes everything ordinary already queued, its own sender’s earlier messages included, so a Terminated this predicate answers true for arrives ahead of the work that preceded the death.

T

boolean


readonly optional onControlError?: (cause, message) => void

Defined in: src/mailbox/ControlAwareMailboxOptions.ts:97

Optional hook fired each time isControl throws, after the message has been classed ordinary for it (#1431) — this mailbox’s counterpart of PriorityMailboxOptionsType.onPriorityError (#733).

Worth wiring, because the containment makes the failure quiet: a predicate that throws on every message — a method handed over without its this is the usual one — turns this mailbox into a plain FIFO queue, and every message still arrives. cause is what the predicate threw; message is the message it threw on, often PoisonPill or Kill, which stop() and kill() post as ordinary user messages.

Unset, the mailbox logs the first throw, at warn, and none after it: the predicate runs on every enqueue, and a line per message is a log nobody can read. The line names the error’s class and the message’s class, never the error’s text or the message itself — an exhaustive matcher’s error quotes the value it could not match, and a message is application data. It goes to the console, because a mailbox does not know which actor owns it; this hook is how to send it anywhere else. A hook that is given replaces that line.

Record and return. It runs on the sender’s stack, and one that throws puts back the escape the containment exists to prevent — the contract onDrop has too. An answer that is not true is not a failure and does not reach it: it classes the message ordinary, as documented.

unknown

T

void


readonly optional onDrop?: MailboxDropObserver<T>

Defined in: src/mailbox/ControlAwareMailboxOptions.ts:62

Optional hook fired each time a message is dropped by the overflow policy, with the policy that fired and the envelope that was discarded (#773) — under drop-head the ordinary message evicted to make room, not the arrival. Never fired for a control message, which is never dropped.

Yours alone: the cell reports to actor_mailbox_dropped_total through DropReportingMailbox.observeDrops, which runs alongside this rather than replacing it. Runs on the sender’s stack — record and return.


readonly optional overflow?: BoundedMailboxOverflow

Defined in: src/mailbox/ControlAwareMailboxOptions.ts:51

What a full ordinary class does with the next ordinary arrival — the three BoundedMailbox policies, which mean the same thing here because the ordinary class is a FIFO queue just like that one. Only meaningful together with capacity, and rejected without it. Default reject, as on every mailbox you construct yourself: naming a capacity says how much you will hold, not what you are willing to lose.