Struct Subscriber 

pub struct Subscriber { /* private fields */ }

A live subscription to a track, used to read its groups.

Created via Consumer::subscribe, or directly from a Producer for an in-process track. Carries this subscriber’s Subscription preferences, which feed the producer’s aggregate.

Local cursor vs wire preference

Group bounds exist at two levels, and setting one does not imply the other:

• Self::start_at / Self::end_at move this subscriber’s read cursor. They filter exactly what this handle returns and are invisible to the publisher.
• Subscription::group_start / Subscription::group_end, set via Self::update, are a request to the publisher. They’re aggregated across every live subscriber (earliest start, widest end), so they say what the publisher should send, not what this subscriber sees.

They stay separate because their scopes differ: a subscriber can’t filter by the aggregate, since another subscriber can widen it, and the publisher can’t honor a cursor it’s never told about. So setting only the cursor still transfers the skipped groups, and setting only the preference still returns groups another subscriber asked for. Set both to skip them and avoid the transfer.

Implementations

impl Subscriber

pub fn info(&self) -> &Info

The track’s Info, resolved when the subscription was established.

Free, unlike Consumer::info: subscribing already waited for the info (SUBSCRIBE_OK on the wire), so a subscriber always has it.

pub fn name(&self) -> &str

The track’s name, unique within its broadcast.

pub fn control(&self) -> SubscriberControl

Create a handle for updating this subscriber’s delivery preferences.

pub fn poll_recv_group( &mut self, waiter: &Waiter, ) -> Poll<Result<Option<Consumer>>>

Poll for the next group in arrival order, without blocking.

Returns every group exactly once in the order it landed on the wire, which may be out of sequence due to network reordering or loss. Use Self::poll_next_group if you only want groups whose sequence number is higher than any previously returned.

Returns Poll::Ready(Ok(Some(group))) when a group is available, Poll::Ready(Ok(None)) when the track is finished, Poll::Ready(Err(e)) when the track has been aborted, or Poll::Pending when no group is available yet.

pub async fn recv_group(&mut self) -> Result<Option<Consumer>>

Receive the next group in arrival order.

Every group is returned exactly once, in the order it landed on the wire, which may be out of sequence due to network reordering or loss. Use Self::next_group if you only want groups whose sequence number is higher than any previously returned.

pub fn poll_recv_datagram( &mut self, waiter: &Waiter, ) -> Poll<Result<Option<Datagram>>>

Poll for the next datagram in arrival order, without blocking.

Datagrams are a separate best-effort channel from groups (see Producer::append_datagram); they share only the sequence namespace. A consumer that falls too far behind silently loses the oldest datagrams. Returning a datagram advances Self::poll_next_group past that sequence.

Returns Poll::Ready(Ok(Some(datagram))) when one is available, Poll::Ready(Ok(None)) when the track is finished, Poll::Ready(Err(e)) when the track is aborted, or Poll::Pending when none is buffered yet.

pub async fn recv_datagram(&mut self) -> Result<Option<Datagram>>

Receive the next datagram in arrival order.

A best-effort channel parallel to Self::recv_group; the two share only the sequence namespace. To receive both concurrently from one subscriber, poll Self::poll_next_group (or Self::poll_recv_group) and Self::poll_recv_datagram together in a single poll closure (sequential &mut borrows), rather than awaiting the two recv futures at once.

pub fn poll_next_group( &mut self, waiter: &Waiter, ) -> Poll<Result<Option<Consumer>>>

Poll for the next group with a higher sequence number than any previously returned.

Late arrivals (sequence at or below the last returned) are silently skipped, so this produces a monotonically increasing sequence at the cost of dropping out-of-order groups. Use Self::poll_recv_group to see every group in arrival order instead.

Honors the cap set by Self::end_at: groups with sequence past the cap are left in the producer’s cache and become eligible again if the cap is raised or removed.

pub async fn next_group(&mut self) -> Result<Option<Consumer>>

Return the next group with a higher sequence number than any previously returned.

Late arrivals (sequence at or below the last returned) are silently skipped, so this produces a monotonically increasing sequence at the cost of dropping out-of-order groups. Use Self::recv_group to see every group in arrival order instead.

pub fn poll_read_frame( &mut self, waiter: &Waiter, ) -> Poll<Result<Option<Frame>>>

A helper that calls Self::poll_next_group and returns its first frame (timestamp and payload), skipping the rest of the group. Intended for single-frame groups (see Producer::write_frame).

pub async fn read_frame(&mut self) -> Result<Option<Frame>>

Read a single full frame (timestamp and payload) from the next group in sequence order.

See Self::poll_read_frame for semantics.

pub fn is_clone(&self, other: &Self) -> bool

Whether other was cloned from this subscriber (shares the same underlying state).

pub fn poll_finished(&mut self, waiter: &Waiter) -> Poll<Result<u64>>

Poll for the track’s declared final sequence, without blocking.

pub async fn finished(&mut self) -> Result<u64>

Block until the track declares its end, returning the exclusive final sequence (also the total group count), or the cause on an abort.

Resolves as soon as the boundary is known, which may be ahead of the live edge when the producer finished via Producer::finish_at. This reports the declared end, not that every group has arrived: drive Self::recv_group / Self::next_group until they yield None to observe the track fully drained.

pub fn start_at(&mut self, sequence: u64)

Start this subscriber’s read cursor at the given sequence.

A local filter, not a request: it doesn’t tell the publisher anything, so the skipped groups are still delivered and simply not returned. To ask the publisher to start there instead, set Subscription::group_start via Self::update. See Local cursor vs wire preference.

pub fn end_at(&mut self, sequence: impl Into<Option<u64>>)

Cap this subscriber’s read cursor at the given sequence (inclusive), or remove the cap entirely.

Accepts a bare u64 (cap), Some(u64), or None (uncap).

A local filter, not a request; Subscription::group_end is the wire-level counterpart. See Local cursor vs wire preference.

Affects Self::next_group only: groups beyond the cap stay in the producer’s cache rather than being skipped past, so a later call to Self::end_at with a higher value (or None) makes them available again. Lowering the cap below the consumer’s current cursor parks the consumer until the cap is raised.

pub fn subscription(&self) -> Subscription

This subscriber’s current preferences.

pub fn update(&mut self, subscription: Subscription) -> Result<()>

Replace this subscriber’s delivery preferences.

Stored verbatim; the publisher’s latency window is applied to the aggregate, not here (see Producer::subscription). Returns Error::Closed if the track already ended; the update is meaningless at that point and can usually be ignored.

pub fn latest(&self) -> Option<u64>

Return the latest sequence number in the track.