Crate zencodec_io

Expand description

Drivers that run a zencodec decoder over real input.

zencodec defines two decoder shapes that do no I/O of their own:

IncrementalDecode: resumable, driven by whoever holds the bytes (step offers them in place).
DecodeJob::push_decoder_from_source: pull-native, reading a DynReadAt.

This crate supplies the loops and adapters that connect either shape to a slice, a random-access source, a sequential stream, or an async runtime, so neither codecs nor applications write them:

input	resumable decoder	pull-native decoder
slice	`drive_from_slice`	`SliceReadAt`
`ReadAt` (file, object store, FFI callback)	`drive_from_read_at`	direct
`std::io::Read` stream (feature `std`)	`pump_read_to_sink`	`BufferedReadAt`
async runtime (feature `tokio`)	`tokio_io::decode_async`	`tokio_io::pull_decode_on_thread`

Cancellation and progress share one handle: every driver takes an Option<&dyn how_far::Pulse> (Pulse: Stop), checks it each step, tells it the row total once the header is known and advances it per strip. A caller with only a Stop passes how_far::StopOnly::borrowed.

Every driver checks each Need against the input it just offered and returns ProtocolViolation for a decoder that would otherwise spin.

The crate is no_std + alloc by default. The std feature adds the stream pump, file source and buffered stream adapter; tokio adds tokio_io (tokio::sync and tokio::io only; it never starts a runtime).

Modules§

destination: Actual writer access for synchronous image and container output. Actual forward-only and seek-back destinations for synchronous output. A wrapper binds access and the output origin to the retained writer.
row_encode: Owned row-source encoding with policy before final-destination effects.
storage: Compatibility path for shared allocation ownership.
tokio_io: Async drivers for tokio (and any executor): decode with no thread blocked on I/O and no async in codec code.

Structs§

BufferedReadAt: ReadAt over a sequential std::io::Read stream, buffered per a BufferPolicy.
CollectSink: A sink that collects every final row into one tightly packed image.
ControlledStepper: Drive a controlled decoder with crate::SliceCursor, crate::ReadAtCursor or an async cursor, returning mandatory boundaries to the adapter.
DriveOptions: Tuning for the drivers.
DriveStats: Counters from one drive.
EncodeWriteReport: What encode_to_writer did.
EncoderSink: DecodeRowSink that feeds an Encoder.
FileReadAt: ReadAt over a file, using positional reads on Unix and Windows and seek + read elsewhere. Unix reads leave a shared file cursor unchanged; Windows seek_read can update it. No implementation uses unsafe.
IoLimits: Limits on storage and requests owned by one input driver.
PolicyDecoder: Connect a controlled decoder to every existing slice, file and network driver. Decisions run only at actual suspensions, before native work resumes. The decoder remains terminal after a callback failure or caught unwind.
ReadAtCursor: Drives a stage over a random-access source.
ReadAtReader: Adapt a positional source to Read and Seek with an independent cursor.
ReadCursor: Drives a stage over a sequential stream.
SliceCursor: Drives a stage over bytes already in memory, without copying them.
Stepped: The result of one ByteStepper::step.
WorkQuota: Maximum codec steps in one uninterrupted async compute turn.

Enums§

BufferPolicy: How a BufferedReadAt retains bytes from a sequential stream.
ControlledEvent: A controlled decoder’s observable progress. A suspension is never completion.
DriveFailure: Failure of a drive over any ByteStepper.
EncodeWriteError: Failure of encode_to_writer.
EncoderSinkError: Failure of EncoderSink::finish.
InputError: Driver admission or allocation failure, separate from codec/source errors.
PolicyDecodeError: Native failure or traced application-policy failure during controlled decode.
ProtocolViolation: A decoder broke the IncrementalDecode protocol. Drivers report this instead of looping.
PumpFailure: Failure of a drive over a sequential std::io::Read stream.
StdSourceError: A source-contract refusal or the original standard-library I/O failure.
Step: What a step produced.
Yield: What a cursor’s next returns: an output, or the last one.

Traits§

ByteStepper: A stage that consumes bytes through the sans-I/O dialogue.

Functions§

coalesce_byte_ranges: Merge overlapping or near-adjacent ranges (gap <= max_gap) into one.
coalesce_into: coalesce_byte_ranges writing into out (cleared first), so a loop reuses one allocation.
drive_from_read_at: Run decoder over a random-access source.
drive_from_slice: Run decoder over an in-memory image without copying it.
encode_to_writerDeprecated: Encode pixels into w, sending bytes as the encoder produces them.
pump_read_to_sink: Pump a sequential stream into decoder, writing rows into sink.
write_pending: Write every byte enc has pending to w, then consume it. Returns how many bytes were written.
write_pending_animation: write_pending for an AnimationFrameEncoder: write the bytes of the frames pushed so far.

Type Aliases§

DriveError: Failure of an image drive: a DriveFailure whose stage error is the decoder’s StepError.
PumpError: Failure of pump_read_to_sink: a PumpFailure whose stage error is the decoder’s StepError.