Crate congestion 

Pluggable congestion control for the RCP tool family.

This crate exposes a Controller trait that encapsulates a congestion-control algorithm — consuming operation-completion Samples and emitting concurrency / rate Decisions. The trait is intentionally small and synchronous so algorithms can be implemented and tested without any I/O, async runtime, or wall-clock dependence.

Three concentric layers are envisioned for integration with the rcp / rrm / rlink / filegen tools:

1. Algorithm — the Controller trait and its implementations; pure.
2. Control loop — plumbing that collects samples from the hot path, drives the controller on a fixed tick, and publishes decisions. Lives outside this crate (in throttle or a thin adapter) and is not part of Phase 1.
3. Enforcement — the existing throttle token buckets and semaphores, with their limits driven by the control loop.

Built-in controllers

• NoopController — never limits. Default when congestion control is disabled.
• FixedController — honors a static concurrency/rate budget. Mirrors the existing manual --ops-throttle / --iops-throttle knobs and is the regression baseline for adaptive algorithms.
• RatioController — adaptive controller that tracks queueing-delay inflation by comparing two windowed latency percentiles (current vs baseline) and adjusts the concurrency cap to stay at the onset of inflation. Inspired by TCP Vegas.

Additional adaptive variants (for example BBR-style) can be layered on the same trait without changes to the enforcement or control-loop layers.

Testing

The sim module provides a deterministic single-bottleneck simulator that drives any Controller through a configured scenario and returns a trace of samples and decisions. See the module docs for the model.

Modules

format

Binary log file format for auto-meta recordings.

sim

Deterministic, event-driven simulator for evaluating Controllers.

testing

Test utilities for asserting on emitted samples.

Structs

ControlUnit

A single resource’s control task.

ControllerSnapshot

Read-only view of a controller’s internal state, intended for the progress bar and other observability surfaces.

Decision

Absolute limits emitted by a controller for the enforcement layer to apply.

FixedController

Controller that always emits the same configured Decision.

HistogramAccumulator

Per-controller HDR latency accumulator.

NoopController

Controller that always emits Decision::UNLIMITED.

Probe

A measurement-in-progress for a single operation.

RatioConfig

Tunable parameters for RatioController.

RatioController

Adaptive controller driven by a two-window latency-percentile ratio.

RoutingSink

A SampleSink that fans samples out to per-resource bounded MPSC channels, typically each drained by one ControlUnit.

RoutingSinkBuilder

Incrementally opt resources into the routing sink. Each *_receiver call registers a channel for the corresponding ResourceKind and returns the receiver the caller must hand to a ControlUnit.

Sample

A single observation of an operation’s behavior, fed to a Controller.

Enums

MetadataOp

Which metadata syscall is being measured.

Outcome

The outcome of a single measured operation.

ResourceKind

Which resource a probe is measuring.

Side

Which side of an operation a probe is on.

Constants

DEFAULT_TICK_INTERVAL

Default cadence at which a control unit calls on_tick.

HDR_HIGHEST_TRACKABLE_MICROS

Maximum value representable in the histogram, in microseconds (1 hour).

HDR_LOWEST_DISCERNIBLE_MICROS

Minimum value representable in the histogram, in microseconds.

HDR_SIGNIFICANT_FIGURES

Significant figures of precision tracked by the histogram.

N_META_OPS

Number of MetadataOp variants. Keep in sync when adding variants.

N_META_RESOURCES

Number of distinct (Side, MetadataOp) controllers.

N_SIDES

Number of Side variants.

Traits

Controller

A pluggable congestion-control algorithm.

SampleSink

Consumer of completed operation samples.

Functions

clear_sample_sink

Remove the current sink, if any. After this call, probes are no-ops again.

install_sample_sink

Install the process-wide SampleSink. Replaces any prior sink.