Ir al contenido
Español

Throttling

Esta página aún no está disponible en tu idioma.

Every actor drains its mailbox as fast as its dispatcher allows. Throttling puts a per-actor rate limit in front of that: a token bucket the runtime checks before dequeuing each user message. It is how you stop one actor from overwhelming a downstream service, a log sink, or a rate-limited API — without changing anything about the actors that send to it.

import { Actor } from 'actor-ts';
type SampleMessage = { kind: 'sample'; value: number };
class Ingest extends Actor<SampleMessage> {
override preStart(): void {
// At most 100 user messages a second, tolerating a burst of 20.
this.context.throttle({ qps: 100, burst: 20 });
}
override onReceive(message: SampleMessage): void {
// ... runs at the throttled rate
}
}

throttle can be called from anywhere the actor runs — preStart, a message handler, a behavior. Calling it again replaces the limiter; there is at most one throttle per actor.

The bucket holds up to burst tokens and refills at qps tokens per second. Dequeuing a user message costs one token. The bucket starts full, so an idle actor can absorb an immediate spike of up to burst messages before the limit bites; after that, messages flow at qps.

FieldMeaning
qpsRefill rate, tokens per second. Required, > 0. Infinity removes the throttle (see Clearing the throttle).
burstBucket capacity. Default: qps (one second of refill).
onExcessWhat to do when the bucket is empty — 'pause' (default) or 'drop'.
nowTime source; pass a deterministic clock in tests. Default: Date.now.

Because burst defaults to qps, a bare throttle({ qps: 100 }) smooths traffic to ~100/second while tolerating one second’s worth of variation.

When the bucket is empty — pause vs drop

Section titled “When the bucket is empty — pause vs drop”

onExcess decides the fate of a user message dequeued while the bucket has no tokens:

  • 'pause' (default) — natural backpressure. The message stays queued and the actor’s message pump parks until a token is due, then resumes. Every message is eventually processed; latency grows under load. The mailbox does the buffering.
  • 'drop' — the message is discarded (with a debug log). Useful for telemetry-style traffic where a stale sample is worse than a lost one.
import { Actor } from 'actor-ts';
type SampleMessage = { kind: 'sample'; value: number };
class Telemetry extends Actor<SampleMessage> {
override preStart(): void {
// Shed load rather than buffer it — a late metric is worthless.
this.context.throttle({ qps: 50, burst: 10, onExcess: 'drop' });
}
override onReceive(message: SampleMessage): void {
// ... only ~50 samples a second reach here; the rest are dropped
}
}

Two equivalent ways to remove an active throttle and return to full dispatch speed:

this.context.cancelThrottle();
// exactly equivalent:
this.context.throttle({ qps: Infinity });

{ qps: Infinity } is the “no limit” value: an unlimited rate has no bucket, so the runtime installs none. It is handy when the rate is computed — a single throttle({ qps: computeRate() }) call site can turn the limiter off by yielding Infinity, with no branching at the call site.

The throttle gates user messages only. These bypass it entirely:

  • System messages — create, terminate, supervision, timer fires. They run on the system queue, ahead of user messages, so a throttled actor still stops promptly and its timers still fire on schedule.
  • Death-watch notifications — a Terminated (or its watchWith replacement) consumes no token and is never the message an onExcess: 'drop' discards. A death is announced once, so the runtime never lets a throttle drop it.

That separation is what makes a throttle safe to set aggressively: it slows the actor’s work, never its lifecycle.

Like every options type in actor-ts, throttle options have a fluent builder that is interchangeable with the plain object:

import { Actor, ThrottleOptions } from 'actor-ts';
type SampleMessage = { kind: 'sample'; value: number };
class Ingest extends Actor<SampleMessage> {
override preStart(): void {
const throttleOptions = ThrottleOptions.create()
.withQps(100)
.withBurst(20)
.withOnExcess('drop');
this.context.throttle(throttleOptions);
}
override onReceive(message: SampleMessage): void {
// ...
}
}

Invalid options are rejected up front with an OptionsError that names the offending field, so a bad qps or burst fails at the throttle() call rather than later inside the runtime:

InputResult
qps: 0, qps: -5, qps: NaNOptionsError — qps must be a positive finite number or Infinity
qps: InfinityAccepted — clears the throttle
burst: 0, burst: -1OptionsError — burst must be a positive finite number
onExcess: 'explode'OptionsError — onExcess must be one of pause, drop

Called from inside an actor, that OptionsError travels through supervision like any other thrown error.

A pause-throttled mailbox is parked, not draining — so a system shutdown does not wait for it. A qps: 10 actor with a backlog would need backlog ÷ 10 seconds to drain, which no shutdown can wait out, so the drain treats a throttle-parked queue as quiet and dead-letters whatever is left. If that backlog matters at shutdown, cancelThrottle() first. The Troubleshooting guide lists this under “the system won’t drain”.

  • Mailboxes — where pause-mode backpressure buffers; bound it when a sender can outrun the actor.
  • Dispatchers — the throttle sits in front of the dispatcher that would otherwise run every queued message.
  • Death watch — why termination notifications are exempt from the throttle.

The ActorContext.throttle API reference covers the full signature and options.