Struct Consumer

Source

pub struct Consumer { /* private fields */ }

Expand description

Consume a group, frame-by-frame.

Implementations§

Source §

impl Consumer

Source

pub fn keep_alive(&self)

Mark the group as still being read, so a slow drain doesn’t expire it.

Self::read_frames stamps the group’s cache access once per batch, which bounds frames rather than elapsed time. A reader that takes longer than the track’s latency_max to work through one batch (a publisher writing to a flow-controlled peer, say) calls this between frames, or the rest of the group is expired out from under it mid-serve. Self::read_frame stamps on every call and needs no help.

Cheap and idempotent within a coarse clock tick, so calling it per frame is fine.

Source

pub fn timescale(&self) -> Timescale

The parent track’s timescale.

Source

pub fn frame_count(&self) -> usize

The number of frames written so far (completed plus any in-flight), independent of how many this consumer has read. The final total once the group is finished.

Source

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

Advance the read cursor to sequence, skipping every frame below it.

Skipped frames are never returned, and an eviction confined to them is not a gap: reads resume at the cursor instead of failing with Error::Lagged. An eviction at or above the cursor still fails, because the caller asked for that frame. The cursor only moves forward; a sequence at or below it is a no-op.

Source

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

Return a consumer for the next frame for chunked reading.

Source

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

Poll for the next frame, without blocking.

Returns None if the group is finished and the index is out of range.

Source

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

Read the next frame (timestamp and payload) all at once, without blocking.

Use Self::read_frames to pull a whole batch under one lock; a group of small frames drains several times faster that way.

Source

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

Read the next frame (timestamp and payload) all at once.

Source

pub fn poll_read_frames<const N: usize>( &mut self, waiter: &Waiter, out: &mut Buffer<N>, ) -> Poll<Result<usize>>

Fill out with every frame that is ready, up to its capacity, without blocking.

Returns how many frames were written; they’re in frame::Buffer::filled. The buffer’s previous batch is dropped first, so one buffer serves a whole group.

This is a short read: it returns as soon as anything is ready rather than waiting for out to fill, so a partial batch does not mean the group ended. Only a count of 0 does (and only for a non-zero capacity).

One stamp covers the whole batch, so a slow drain calls Self::keep_alive between frames.

Source

pub async fn read_frames<'a, const N: usize>( &mut self, out: &'a mut Buffer<N>, ) -> Result<&'a mut [Frame]>

Fill out with every frame that is ready, blocking until at least one is or the group ends. Returns the batch, empty only at the end of the group.

See Self::poll_read_frames for the short-read semantics.

Source

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

Poll until the group terminates, returning this cursor’s next frame index.

Source

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

Block until the group terminates, returning this cursor’s next frame index.

This answers for the cursor, not the group: a reader that drained every frame gets the clean end even if the group was aborted afterwards to release its cache, while one that stopped short gets that abort. A prior Self::skip_to contributes to the index even though those frames were not read. Use Self::frame_count for the producer’s total.