Crate ufotofu 

Abstractions for asynchronously working with series of data (“streams” and “sinks”).

See the producer and consumer modules for thorough introductions to the designs. See the ufotofu website for a discussion of our motivating design choices — these crate docs stay focussed on the what, not the why.

Caveats

Ufotofu adheres to the principles of frugal async rust:

• The futures returned by async ufotofu methods are !Send, they cannot be run on multi-threaded executors.
• Dropping any method-returned future before polling it to completion will leave the original object in an undefined state; subsequent method calls may display arbitrary (but always safe) behaviour.
• Unwinding any panic may leave ufotofu values in an undefined state. Do not attempt to recover from panics when using ufotofu.

Module Overview

The two central modules are producer and consumer, they define the core abstractions of the crate.

The queues module provides the Queue trait for infallible in-memory queues with bulk push and pop operations, and some types implementing it. These power the buffered producer and consumer implementations of ufotofu.

The channels module provides ordered in-memory communication channels, which implement BulkProducer and BulkConsumer on their endpoints.

The codec module provides traits and functionality around asynchronous encoding and decoding. The codec_relative module provides analogous functionality for settings where encodings can make use of shared context between encoder and decoder.

The fuzz_testing_tutorial demonstrates the utility types for fuzz testing that ufotofu provides.

Actual I/O

The ufotofu abstractions are nice and all, but how do you actually do any I/O with ufotofu? The producer::compat::reader::reader_to_bulk_producer function turns any AsyncRead into a BulkProducer, and the consumer::compat::writer::writer_to_bulk_consumer function turns any AsyncWrite into a BulkConsumer (both functions require the compat_futures_io feature to be activated). This way, you can use established crates such as smol or tokio with ufotofu abstractions.

Compared to futures-rs

The traits of ufotofu roughly correspond to the traits of the futures crate in the following way:

ufotofu	futures-rs
Producer	Stream
BulkProducer	AsyncBufRead, but for arbitrary item and error types
Consumer	Sink
BulkConsumer	AsyncWrite (because there is no AsyncBufWrite), but for arbitrary item and error types

For an overview of the core design differences between ufotofu and the futures crate, see the ufotofu website: each listed design choice is a point of departure from how the futures crate does things.

Do note in particular that the traits of ufotofu are not dyn-compatible, and nothing in ufotofu is Send, cancel-safe, or exception-safe.

Re-exports

pub use producer::BulkProducer;

pub use producer::BulkProducerExt;

pub use producer::IntoBulkProducer;

pub use producer::IntoProducer;

pub use producer::Producer;

pub use producer::ProducerExt;

pub use consumer::BulkConsumer;

pub use consumer::BulkConsumerExt;

pub use consumer::Consumer;

pub use consumer::ConsumerExt;

pub use consumer::IntoBulkConsumer;

pub use consumer::IntoConsumer;

Modules

channels

In-memory FIFO queue communication primitives.

codec

Principled encoding and decoding of values.

codec_prelude

An additional “prelude” for crates using the codec and/or codec_relative modules of ufotofu.

codec_relative

Principled encoding and decoding of values, relative to a context shared by both the encoder and the decoder.

consumer

Consumers — values that asynchronously process a sequence of items.

fuzz_testing_tutorial

A tutorial about fuzz testing ufotofu-related code.

prelude

A “prelude” for crates using the ufotofu crate.

producer

Producers — values that asynchronously yield a sequence of items.

queues

In-memory queues for adding buffering to arbitrary producers and consumers.

Macros

consume

Conveniently consume the output of a Producer.

Structs

ConsumeAtLeastError

An error emitted when a consumer is tasked to consume at least some number of items, but it could only consume a lower number of items.

ProduceAtLeastError

An error emitted when a producer is tasked to produce at least some number of items, but it could only produce a lower number of items.

Enums

ExpectedFinalError

An error emitted when a function expects a final value, but gets a normal item instead.

PipeError

Everything that can go wrong when piping a producer into a consumer.

Functions

bulk_pipe

Efficiently pipes as many items as possible from a BulkProducer into a BulkConsumer, using BulkConsumerExt::bulk_consume. Then closes consumer with the final value emitted by the producer.

pipe

Pipes as many items as possible from a Producer into a Consumer. Then closes the consumer with the final value emitted by the producer.