Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hawkw/thingbuf

in-place allocation-reusing queues for Rust
https://github.com/hawkw/thingbuf

Last synced: 7 days ago
JSON representation

in-place allocation-reusing queues for Rust

Awesome Lists containing this project

README 

        
# thingbuf



> "I'm at the buffer pool. I'm at the MPSC channel. I'm at the combination MPSC

> channel and buffer pool."



[![crates.io][crates-badge]][crates-url]

[![Documentation][docs-badge]][docs-url]

[![Documentation (HEAD)][docs-main-badge]][docs-main-url]

[![MIT licensed][mit-badge]][mit-url]

[![Test Status][tests-badge]][tests-url]

[![Sponsor @hawkw on GitHub Sponsors][sponsor-badge]][sponsor-url]



[crates-badge]: https://img.shields.io/crates/v/thingbuf.svg

[crates-url]: https://crates.io/crates/thingbuf

[docs-badge]: https://docs.rs/thingbuf/badge.svg

[docs-url]: https://docs.rs/thingbuf

[docs-main-badge]: https://img.shields.io/netlify/f2cde148-79c2-4e3f-ab2b-285dff1b9fdf?label=docs%20%28main%20branch%29

[docs-main-url]: https://thingbuf.elizas.website

[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg

[mit-url]: ../LICENSE

[tests-badge]: https://github.com/hawkw/thingbuf/actions/workflows/ci.yml/badge.svg?branch=main

[tests-url]: https://github.com/hawkw/thingbuf/actions/workflows/ci.yml

[sponsor-badge]: https://img.shields.io/badge/sponsor-%F0%9F%A4%8D-ff69b4

[sponsor-url]: https://github.com/sponsors/hawkw



## What Is It?



`thingbuf` is a lock-free array-based concurrent ring buffer that allows access

to slots in the buffer by reference. It's also [asynchronous][`thingbuf::mpsc`]

and [blocking][`thingbuf::mpsc::blocking`] bounded MPSC channels implemented using

the ring buffer.



### When Should I Use It?



- **If you want a high-throughput bounded MPSC channel** that allocates only on

  channel creation. Some MPSC channels have good throughput. Some other MPSC

  channels won't allocate memory per-waiter. [`thingbuf::mpsc`] has both.

  [`thingbuf::mpsc`] is a competitive choice for a general-purpose

  MPSC channel in most use cases.



  Both [asynchronous][`thingbuf::mpsc`] and [blocking][`thingbuf::mpsc::blocking`]

  MPSC channels are available, so `thingbuf` can be used in place

  of asynchronous channels like [`futures::channel::mpsc`] *and* blocking

  channels like [`std::sync::mpsc::sync_channel`].



- **If you can't allocate** or **you need to build with `#![no_std]`** because

  you're working on embedded systems or other bare-metal software. Thingbuf

  provides a [statically-allocated MPSC channel][static-mpsc] and a

  [statically-allocated lock-free queue][static-queue]. These can be placed in a

  `static` initializer and used without requiring any runtime allocations.



- **You want to use the same MPSC channel with and without `std`** . Thingbuf's

  asynchronous MPSC channel provides an identical API and feature set regardless

  of whether or not the "std" feature flag is enabled. If you're writing a library that

  needs to conditionally support `#![no_std]`, and you need an asynchronous MPSC

  channel, it might be easier to use [`thingbuf::mpsc`] in both cases, rather

  than switching between separate `std` and `#![no_std]` channel

  implementations.



### When *Shouldn't* I Use It?



It's equally important to discuss when `thingbuf` should *not* be used. Here are

some cases where you might be better off considering other options:



- **You need a really, really, absurdly high bound and you're not going to be

  near it most of the time**. If you want to set a very, very high bound on a

  bounded MPSC channel, and the channel will typically never be anywhere near

  that full, [`thingbuf::mpsc`] might *not* be the best choice.



  Thingbuf's channels will allocate an array with length equal to the capacity

  as soon as they're constructed. This improves performance by avoiding

  additional allocations, but if you need to set very high bounds, you might

  prefer a channel implementation that only allocates memory for messages as

  it's needed (such as [`tokio::sync::mpsc`]).



- **You need a blocking channel with a `select` operation**.

  I'm probably not going to implement it. I _may_ accept a PR if you raise it.



  If you need a synchronous channel with this kind of functionality,

  [`crossbeam-channel`] is probably a good choice.



- **You want an unbounded channel**. I'm not going to write an unbounded

  channel. Unbounded channels are evil.



## Terminology



This crate's API and documentation makes a distinction between the terms "queue"

and "channel". The term _queue_ will refer to the [queue abstract data

type][q-adt] in general — any first-in, first-out data structure is a

queue.



The term _channel_ will refer to a subtype of concurrent queue that also

functions as a synchronization primitive. A channel is a queue which can be

shared between multiple threads or asynchronous tasks, and which allows those

threads or tasks to wait for elements to be added or removed from the queue.



In the Rust standard library, the [`std::collections::VecDeque`] type

is an example of a queue that is not a channel: it is a first-in, first-out data

structure, but it cannot be concurrently enqueued to and dequeued from by

multiple threads or tasks. In comparison, the types in the [`std::sync::mpsc`]

module provide a prototypical example of channels, as they serve as

synchronization primitives for cross-thread communication.



[q-adt]: https://en.wikipedia.org/wiki/Queue_(abstract_data_type)

[`std::collections::VecDeque`]: https://doc.rust-lang.org/stable/std/collections/struct.VecDeque.html

[`std::sync::mpsc`]: https://doc.rust-lang.org/stable/std/sync/mpsc/index.html



## Usage



To get started using `thingbuf`, add the following to your `Cargo.toml`:



```toml

[dependencies]

thingbuf = "0.1"

```



By default, `thingbuf` depends on the Rust standard library, in order to

implement APIs such as synchronous (blocking) channels. In `#![no_std]`

projects, the `std` feature flag must be disabled:



```toml

[dependencies]

thingbuf = { version = "0.1", default-features = false }

```



With the `std` feature disabled, `thingbuf` will depend only on `libcore`. This

means that APIs that require dynamic memory allocation will not be enabled.

Statically allocated [channels][static-mpsc] and [queues][static-queue] are

available for code without a memory allocator, if the `static` feature flag is

enabled:



```toml

[dependencies]

thingbuf = { version = "0.1", default-features = false, features = ["static"] }

```



However, if a memory allocator _is_ available, `#![no_std]` code can also enable

the `alloc` feature flag to depend on `liballoc`:



```toml

[dependencies]

thingbuf = { version = "0.1", default-features = false, features = ["alloc"] }

```



### Crate Feature Flags



- **std** (_Enabled by default_): Enables features that require the Rust

  standard library, such as

  synchronous (blocking) channels. This implicitly enables the "alloc" feature

  flag.

- **alloc**: Enables features that require `liballoc` (but not `libstd`). This

  enables `thingbuf` queues and asynchronous channels where the size of the

  channel is determined at runtime.

- **static** (_Disabled by default, requires Rust 1.59+_): Enables the static

  (const-generic-based) `thingbuf` queues and channels. These can be used

  without dynamic memory allocation when the size of a queue or channel is known

  at compile-time.



### Compiler Support



`thingbuf` is built against the latest stable release. The minimum supported

version is Rust 1.57. The current `thingbuf` version is not guaranteed to build on Rust

versions earlier than the minimum supported version.



Some feature flags may require newer Rust releases. For example, the "static"

feature flag requries Rust 1.60+.



## FAQs



- **Q: Why did you make this?**



  **A:** For [`tracing`], I wanted to be able to send formatted log lines to a

  dedicated worker thread that writes them to a file. Right now, we do this

  using [`crossbeam-channel`]. However, this has the sad disadvantage that we have

  to allocate `String`s, send them through the channel to the writer, and

  immediately drop them. It would be nice to do this while reusing those

  allocations. Thus...`StringBuf`.



- **Q: Is it lock-free?**



  **A:** Extremely.



- **Q: Why is there only a bounded variant?**



  **A:** Because unbounded queues are of the Devil.



- **Q: Isn't this just a giant memory leak?**



  **A:** If you use it wrong, yes.



- **Q: Why is it called that?**



  **A:** Originally, I imagined it as a kind of ring buffer, so (as a pun on

  "ringbuf"), I called it "stringbuf". Then, I realized you could do this with

  more than just strings. In fact, it can be generalized to arbitrary...things.

  So, "thingbuf".



[`thingbuf::mpsc`]: https://docs.rs/thingbuf/0.1/thingbuf/mpsc/index.html

[`thingbuf::mpsc::blocking`]: https://docs.rs/thingbuf/0.1/thingbuf/mpsc/blocking/index.html

[static-queue]: https://docs.rs/thingbuf/0.1/thingbuf/struct.StaticThingBuf.html

[static-mpsc]: https://docs.rs/thingbuf/0.1./thingbuf/mpsc/struct.StaticChannel.html

[`futures::channel::mpsc`]: https://docs.rs/futures/latest/futures/channel/mpsc/index.html

[`std::sync::mpsc::sync_channel`]: https://doc.rust-lang.org/stable/std/sync/mpsc/fn.sync_channel.html

[`tokio::sync::mpsc`]: https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html

[`tracing`]: https://crates.io/crates/tracing

[`crossbeam-channel`]: https://crates.io/crates/crossbeam-channel