pub enum Received {
Frame,
NeedsInput,
Ended,
}Expand description
What a drain call answered.
Returned by every receive_frame in this crate —
VideoStreamDecoder,
AudioStreamDecoder,
SubtitleDecoder,
AudioResampler, and their
future mirrors — so one vocabulary covers every
backend and every generic consumer.
§The drain loop
use mediadecode::{Received, decoder::AudioStreamDecoder};
/// Drains everything ready right now. Answers `true` once the
/// stream is over, so the caller knows not to feed it again.
fn drain<D: AudioStreamDecoder>(
decoder: &mut D,
dst: &mut Frame<D>,
mut on_frame: impl FnMut(&Frame<D>),
) -> Result<bool, D::Error> {
loop {
// `?` means what it says again: only a fault leaves here.
match decoder.receive_frame(dst)? {
Received::Frame => on_frame(dst),
Received::NeedsInput => return Ok(false),
Received::Ended => return Ok(true),
}
}
}The loop terminates by construction: the two non-frame arms both
return, and neither can be reached without the callee having decided
which one it is. Under the older convention — both conditions
arriving as unnamed Err variants — a caller that had already sent
end-of-stream could not tell “send me more” from “there is no more”,
and a drain that answered the first forever was an ordinary,
silent infinite loop.
Variants§
Frame
A frame was written into dst. Take it and call again.
NeedsInput
Nothing is ready. The session is waiting on input: send another packet (or frame, for a resampler), or signal end-of-stream and drain the tail.
Never returned after the stream has ended — that is
Ended’s job, and keeping the two apart is what
makes a drain loop terminate.
Ended
The stream is over and every buffered frame has been delivered.
Nothing but flush
changes this answer.