From 9f62bff5fb7b2d7e2cef97c2243b03ffcf37ba87 Mon Sep 17 00:00:00 2001 From: glyph Date: Fri, 21 Jun 2024 15:26:47 +0100 Subject: [PATCH] restore crate-level docs to lib --- src/lib.rs | 50 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index 75c5de4..f53a3aa 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -4,7 +4,55 @@ #![feature(never_type)] #![feature(allocator_api)] #![feature(vec_push_within_capacity)] -#![doc = include_str!("../README.md")] + +//! # UFOTOFU +//! +//! Ufotofu provides APIs for lazily producing or consuming sequences of arbitrary length. Highlights of ufotofu include +//! +//! - consistent error handling semantics across all supported modes of sequence processing, +//! - meaningful subtyping relations between, for example, streams and readers, +//! - absence of needless specialization of error types or item types, +//! - fully analogous APIs for synchronous and asynchronous code, +//! - the ability to chain sequences of heterogenous types, and +//! - `nostd` support. +//! +//! You can read an in-depth discussion of the API designs [here](https://github.com/AljoschaMeyer/lazy_on_principle/blob/main/main.pdf). +//! +//! ## Core Abstractions +//! +//! Ufotofu is built around a small hierarchy of traits that describe how to produce or consume a sequence item by item. +//! +//! A [`Producer`](sync::Producer) provides the items of a sequence to some client code, similar to the [`futures::Stream`](https://docs.rs/futures/latest/futures/stream/trait.Stream.html) or the [`core::iter::Iterator`] traits. Client code can repeatedly request the next item, and receives either another item, an error, or a dedicated *final* item which may be of a different type than the repeated items. An *iterator* of `T`s corresponds to a *producer* of `T`s with final item type `()` and error type `!`. +//! +//! A [`Consumer`](sync::Consumer) accepts the items of a sequence from some client code, similar to the [`futures::Sink`](https://docs.rs/futures/latest/futures/sink/trait.Sink.html) traits. Client code can repeatedly add new items to the sequence, until it adds a single *final* item which may be of a different type than the repeated items. A final item type of `()` makes adding the final item equivalent to calling a conventional [`close`](https://docs.rs/futures/latest/futures/sink/trait.Sink.html#tymethod.poll_close) method. +//! +//! Producers and consumers are fully dual; the [pipe](sync::pipe) function writes as much data as possible from a producer into a consumer. +//! +//! Consumers often buffer items in an internal queue before performing side-effects on data in larger chunks, such as writing data to the network only once a full packet can be filled. The [`BufferedConsumer`](sync::BufferedConsumer) trait extends the [`Consumer`](sync::Consumer) trait to allow client code to trigger effectful flushing of internal buffers. Dually, the [`BufferedProducer`](sync::BufferedProducer) trait extends the [`Producer`](sync::Producer) trait to allow client code to trigger effectful prefetching of data into internal buffers. +//! +//! Finally, the [`BulkProducer`](sync::BulkProducer) and [`BulkConsumer`](sync::BulkConsumer) traits extend [`BufferedProducer`](sync::BufferedProducer) and [`BufferedConsumer`](sync::BufferedConsumer) respectively with the ability to operate on whole slices of items at a time, similar to [`std::io::Read`] and [`std::io::Write`]. The [bulk_pipe](sync::bulk_pipe) function leverages this ability to efficiently pipe data — unlike the standard library's [Read](std::io::Read) and [Write](std::io::Write) traits, this is possible without allocating an auxilliary buffer. +//! +//! ## Crate Organisation +//! +//! The ufotofu crate is split into three high-level modules: +//! +//! - [`sync`] provides APIs for synchronous, blocking abstractions (think [`core::iter::Iterator`]), +//! - [`local_nb`] provides [`Future`](core::future::Future)-based, non-blocking APIs (think [`futures::stream::Stream`](https://docs.rs/futures/latest/futures/stream/trait.Stream.html)) for *single-threaded* executors, and +//! - [`nb`] provides [`Future`](core::future::Future)-based, non-blocking APIs for *multi-threaded* executors. +//! +//! All three modules implement the same concepts; the only differences are whether functions are asynchronous, and, if so, whether futures implement [`Send`]. In particular, each module has its own version of the core traits for interacting with sequences. +//! +//! The [`nb`] module lacks most features of the [`sync`] and [`local_nb`] modules, but the core trait definitions are there, and we happily accept pull-requests. +//! +//! ## Feature Flags +//! +//! Ufotofu gates several features that are only interesting under certain circumstances behind feature flags. These API docs document *all* functionality, though, as if all feature flags were activated. +//! +//! All functionality that relies on the Rust standard library is gated behind the `std` feature flag (enabled by default). +//! +//! All functionality that performs dynamic memory allocations is gated behind the `alloc` feature flag (disabled by default). +//! +//! All functionality that aids in testing and development is gated behind the `dev` feature flag (disabled by default). #[cfg(feature = "std")] extern crate std;