zencodec_io/
lib.rs

1//! Drivers that run a zencodec decoder over real input.
2//!
3//! zencodec defines two decoder shapes that do no I/O of their own:
4//!
5//! - [`IncrementalDecode`](zencodec::decode::IncrementalDecode): resumable,
6//!   driven by whoever holds the bytes (`step` offers them in place).
7//! - [`DecodeJob::push_decoder_from_source`](zencodec::decode::DecodeJob::push_decoder_from_source):
8//!   pull-native, reading a [`DynReadAt`](zencodec::source::DynReadAt).
9//!
10//! This crate supplies the loops and adapters that connect either shape to
11//! a slice, a random-access source, a sequential stream, or an async
12//! runtime, so neither codecs nor applications write them:
13//!
14//! | input | resumable decoder | pull-native decoder |
15//! |---|---|---|
16//! | slice | [`drive_from_slice`] | [`SliceReadAt`](zencodec::source::SliceReadAt) |
17//! | `ReadAt` (file, object store, FFI callback) | [`drive_from_read_at`] | direct |
18//! | `std::io::Read` stream (feature `std`) | `pump_read_to_sink` | `BufferedReadAt` |
19//! | async runtime (feature `tokio`) | `tokio_io::decode_async` | `tokio_io::pull_decode_on_thread` |
20//!
21//! Cancellation and progress share one handle: every driver takes an
22//! `Option<&dyn how_far::Pulse>` (`Pulse: Stop`), checks it each step,
23//! tells it the row total once the header is known and advances it per
24//! strip. A caller with only a `Stop` passes `how_far::StopOnly::borrowed`.
25//!
26//! Every driver checks each `Need` against the input it just offered and
27//! returns [`ProtocolViolation`] for a decoder that would otherwise spin.
28//!
29//! The crate is `no_std + alloc` by default. The `std` feature adds the
30//! stream pump, file source and buffered stream adapter; `tokio` adds
31//! `tokio_io` (`tokio::sync` and `tokio::io` only; it never starts a
32//! runtime).
33
34#![no_std]
35#![forbid(unsafe_code)]
36#![warn(missing_docs)]
37
38extern crate alloc;
39#[cfg(feature = "std")]
40extern crate std;
41
42mod drive;
43mod encoder_sink;
44mod sinks;
45mod stepper;
46mod window;
47
48#[cfg(feature = "std")]
49mod buffered;
50#[cfg(feature = "std")]
51mod encode_write;
52#[cfg(feature = "std")]
53mod file;
54#[cfg(feature = "std")]
55mod pump;
56#[cfg(feature = "std")]
57mod read_at_reader;
58#[cfg(feature = "std")]
59pub mod row_encode;
60#[cfg(feature = "std")]
61mod std_source_error;
62#[cfg(feature = "tokio")]
63pub mod tokio_io;
64
65mod admission;
66pub use admission::{InputError, IoLimits};
67mod work_quota;
68pub use work_quota::WorkQuota;
69mod policy_decoder;
70pub use policy_decoder::{PolicyDecodeError, PolicyDecoder};
71mod controlled_stepper;
72pub use controlled_stepper::{ControlledEvent, ControlledStepper};
73pub mod storage;
74
75pub use drive::{
76    DriveError, DriveOptions, DriveStats, coalesce_byte_ranges, coalesce_into, drive_from_read_at,
77    drive_from_slice,
78};
79pub use encoder_sink::{EncoderSink, EncoderSinkError};
80pub use sinks::CollectSink;
81pub use stepper::{ByteStepper, DriveFailure, ReadAtCursor, SliceCursor, Step, Stepped, Yield};
82#[cfg(feature = "std")]
83pub use stepper::{PumpFailure, ReadCursor};
84pub use window::ProtocolViolation;
85
86#[cfg(feature = "std")]
87pub use buffered::{BufferPolicy, BufferedReadAt};
88#[cfg(feature = "std")]
89// Retain the deprecated convenience for existing callers.
90#[allow(deprecated)]
91pub use encode_write::{
92    EncodeWriteError, EncodeWriteReport, encode_to_writer, write_pending, write_pending_animation,
93};
94#[cfg(feature = "std")]
95pub use file::FileReadAt;
96#[cfg(feature = "std")]
97pub use pump::{PumpError, pump_read_to_sink};
98#[cfg(feature = "std")]
99pub use read_at_reader::ReadAtReader;
100#[cfg(feature = "std")]
101pub use std_source_error::StdSourceError;
102
103/// Actual writer access for synchronous image and container output.
104#[cfg(feature = "std")]
105pub mod destination;
zencodec_io/lib.rs

zencodec_io/
lib.rs
