Raxol.Core.Runtime.Backpressure (Raxol Core v2.6.0)

Copy Markdown View Source

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 synchronous GenServer.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; the policy field 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} where decision is 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

decision()

@type decision() :: :cast | :call | :drop | :no_proc

policy()

@type policy() :: :call_when_full | :drop_when_full | :fail_when_full

result()

@type result() :: :ok | {:dropped, :overflow | :no_proc}

Functions

cast(target, message, opts)

@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).