Struct ConsumerHandle 

pub struct ConsumerHandle { /* private fields */ }

Opaque handle that enforces per-consumer quotas on a shared Station.

Obtain via Station::register_consumer. The handle is Send + Sync and may be wrapped in an Arc for sharing across tasks.

Drop semantics

Dropping the ConsumerHandle drops the Vec<MultiplexRef> held internally. Each MultiplexRef::drop calls release_consumer on the underlying station, decrementing the per-SeriesKey refcount. When the last holder drops, the multiplexer shuts down — same path as dropping a SubscriptionHandle.

This is fully synchronous: MultiplexRef::drop performs only a fetch_sub + optional oneshot::send, both non-blocking.

Implementations

impl ConsumerHandle

pub async fn active_sub_count(&self) -> u32

Number of currently active subscriptions held by this consumer.

pub async fn rest_tokens_available(&self) -> u32

REST tokens available in the current window (without consuming). Returns u32::MAX when no REST quota is configured.

pub async fn subscribe( &self, set: SubscriptionSet, ) -> Result<SubscribeReport, QuotaError>

Subscribe with quota enforcement.

Pre-flight checks (whitelist, cap) run before any acquire_or_spawn call. If either fails, no subscriptions are made and an error is returned immediately.

If a stream fails mid-batch (StreamNotSupported), any refs acquired so far in this batch are rolled back via release_consumer before returning Err. The consumer’s active-sub counter never sees a partial increment.

The returned SubscribeReport’s handle still works for recv() — the multiplex broadcast keeps emitting as long as any consumer holds a ref. The underlying MultiplexRefs are moved into this ConsumerHandle, so dropping the ConsumerHandle releases ALL refs even if the caller still holds the SubscriptionHandle for event recv.

pub async fn rest_gate(&self) -> Result<Station, QuotaError>

Consume one REST token and return a Station view.

The caller uses the returned Station to call REST methods (e.g. hub().get_klines(...)). This token-handoff design avoids ~75 LOC of forwarding boilerplate and is immune to future additions of REST methods.

Returns Err(QuotaError::RestRateLimit { remaining_ms }) when the token bucket is empty.