Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update all README links #30

Merged
merged 1 commit into from
Jun 26, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 40 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,53 +18,69 @@ You can read an in-depth discussion of the API designs
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
A [`Producer`](https://docs.rs/ufotofu/latest/ufotofu/sync/trait.Producer.html) 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 `!`.
[`core::iter::Iterator`](https://doc.rust-lang.org/core/iter/trait.Iterator.html) 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
A [`Consumer`](https://docs.rs/ufotofu/latest/ufotofu/sync/trait.Consumer.html) 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.
Producers and consumers are fully dual; the [pipe](https://docs.rs/ufotofu/latest/ufotofu/sync/fn.pipe.html)
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
[`BufferedConsumer`](https://docs.rs/ufotofu/latest/ufotofu/sync/trait.BufferedConsumer.html) trait
extends the [`Consumer`](https://docs.rs/ufotofu/latest/ufotofu/sync/trait.Consumer.html) 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
[`BufferedProducer`](https://docs.rs/ufotofu/latest/ufotofu/sync/trait.BufferedProducer.html) trait
extends the [`Producer`](https://docs.rs/ufotofu/latest/ufotofu/sync/trait.Producer.html) 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)
Finally, the [`BulkProducer`](https://docs.rs/ufotofu/latest/ufotofu/sync/trait.BulkProducer.html)
and [`BulkConsumer`](https://docs.rs/ufotofu/latest/ufotofu/sync/trait.BulkConsumer.html) traits
extend [`BufferedProducer`](https://docs.rs/ufotofu/latest/ufotofu/sync/trait.BufferedProducer.html)
and [`BufferedConsumer`](https://docs.rs/ufotofu/latest/ufotofu/sync/trait.BufferedConsumer.html)
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.
[`std::io::Read`](https://doc.rust-lang.org/std/io/trait.Read.html) and
[`std::io::Write`](https://doc.rust-lang.org/std/io/trait.Write.html). The
[bulk_pipe](https://docs.rs/ufotofu/latest/ufotofu/sync/fn.bulk_pipe.html) function leverages this
ability to efficiently pipe data — unlike the standard library's
[Read](https://doc.rust-lang.org/std/io/trait.Read.html) and
[Write](https://doc.rust-lang.org/std/io/trait.Write.html) 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.
- [`sync`](https://docs.rs/ufotofu/latest/ufotofu/sync/index.html) provides APIs for synchronous,
blocking abstractions (think [`core::iter::Iterator`](https://doc.rust-lang.org/core/iter/trait.Iterator.html)),
- [`local_nb`](https://docs.rs/ufotofu/latest/ufotofu/local_nb/index.html) provides
[`Future`](https://doc.rust-lang.org/core/future/trait.Future.html)-based, non-blocking APIs (think
[`futures::stream::Stream`](https://docs.rs/futures/latest/futures/stream/trait.Stream.html))
for *single-threaded* executors, and
- [`nb`](https://docs.rs/ufotofu/latest/ufotofu/nb/index.html) provides
[`Future`](https://doc.rust-lang.org/core/future/trait.Future.html)-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.
asynchronous, and, if so, whether futures implement
[`Send`](https://doc.rust-lang.org/core/marker/trait.Send.html). 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
The [`nb`](https://docs.rs/ufotofu/latest/ufotofu/nb/index.html) module lacks most features of the
[`sync`](https://docs.rs/ufotofu/latest/ufotofu/sync/index.html) and
[`local_nb`](https://docs.rs/ufotofu/latest/ufotofu/local_nb/index.html) modules, but the core trait
definitions are there, and we happily accept pull-requests.

## Feature Flags
Expand Down