Adaptive backpressure for hot-path GenServer.cast.
Probes the target mailbox depth via Process.info(pid, :message_queue_len)
and switches behaviour when the queue crosses a watermark. See
docs/adr/0013-event-dispatch-backpressure.md for the design rationale.
Policies
:call_when_full-- escalate to a synchronousGenServer.call/3, applying backpressure to the caller. Use when message loss is unacceptable (input dispatch, test determinism).:drop_when_full-- drop the message and return{:dropped, :overflow}. Use when the consumer naturally recovers from drops (frame batching, idempotent updates).:fail_when_full-- same return shape as:drop_when_full; thepolicyfield in telemetry metadata distinguishes "expected drop" from "explicit failure" for handler-side severity routing.
Telemetry
Emits [:raxol, :runtime, :backpressure] on every invocation.
- Measurements:
%{queue_len: non_neg_integer()} - Metadata:
%{label, policy, decision, target}wheredecisionis one of:cast,:call,:drop,:no_proc.
Examples
Backpressure.cast(MyDispatcher, {:dispatch, event},
label: :dispatcher_input,
policy: :call_when_full,
watermark: 1_000
)
Summary
Functions
Send message to target with backpressure-aware delivery.
Types
Functions
@spec cast(GenServer.server(), term(), keyword()) :: result()
Send message to target with backpressure-aware delivery.
Required opts: :label (atom for telemetry), :policy.
Optional opts: :watermark (default 1000),
:timeout (default 5000, only used for :call_when_full).