A realtime-safe single-producer single-consumer (SPSC) ring buffer
A realtime-safe single-producer single-consumer (SPSC) ring buffer
A wait-free single-producer single-consumer (SPSC) ring buffer for Rust.
This crate can be used without the standard library (#![no_std])
by disabling the std feature (which is enabled by default),
but the alloc crate is needed nevertheless.
cargo add rtrbFor a list of breaking changes and for instructions how to upgrade between released versions, have a look at the changelog.
Measuring the performance of a data structure for inter-thread communication
can be quite brittle and the results depend on many factors.
A few benchmarks for performance comparisons between competing crates
are available at the sub-directory
performance-comparison/
and some results thereof are shown in
issue #39.
Like all benchmarks, they are deeply flawed and to be taken with a grain of salt.
You should make your own measurements that are relevant to your usage patterns.
Feel free to share your own results by commenting on that issue.
Creating the HTML docs (which will be available in target/doc/rtrb/index.html):
cargo docRunning the tests:
cargo testTesting the benchmarks (without actually benchmarking):
cargo test --benchesRunning the benchmarks (using the criterion crate;
results will be available in target/criterion/report/index.html):
cargo benchCreating flame graphs for the benchmarks; first a few preparations:
cargo install flamegraph
echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid
export CARGO_PROFILE_BENCH_DEBUG=trueThen, creating the flame graph (which will be saved to flamegraph.svg),
providing a benchmark (e.g. two_threads), a desired runtime and optionally
a benchmark function (e.g. large):
cargo flamegraph --bench two_threads -- --bench --profile-time 10 largeTo measure code coverage (including branch coverage), nightly Rust is required,
as well as cargo-llvm-cov:
rustup toolchain install nightly
cargo install cargo-llvm-covTest coverage data can be obtained and analyzed with this command:
cargo +nightly llvm-cov --branch --doctests --htmlThis runs the tests (incl. doctests) and creates an HTML report in target/llvm-cov/html/index.html.
Testing with Miri also needs nightly Rust:
cargo +nightly miri testThis Miri flag should also be tried:
MIRIFLAGS="-Zmiri-preemption-rate=0" cargo +nightly miri testRunning the tests with ThreadSanitizer requires nightly Rust as well:
RUSTFLAGS="-Z sanitizer=thread" cargo +nightly test --tests -Z build-std --target x86_64-unknown-linux-gnuYou might have to adapt the --target option to your system (see e.g. rustup show).
rustc VersionThis crate's minimum supported rustc version (MSRV) is 1.38.0.
The MSRV is not expected to be updated frequently, but if it is,
there will be (at least) a minor version bump.
The initial code has been ripped off of https://github.com/crossbeam-rs/crossbeam/pull/338, with permission of the PR author.
It has been isolated from the rest of crossbeam with git-filter-repo:
git-filter-repo --subdirectory-filter crossbeam-queue --path src/spsc.rs --path tests/spsc.rs --refs refs/heads/spscIf you don't like this crate, no problem, there are several alternatives for you to choose from. There are many varieties of ring buffers available, here we limit the selection to wait-free SPSC implementations:
gil::spsc)heapless::spsc)jack::Ringbuffer)magnetic::spsc module)nexus_queue::spsc module)npnc::bounded::spsc module)omango::queue::spsc::bounded())shmem_ipc::sharedring and shmem_ipc::ringbuf modules)smallring::spsc module)There are also implementations in other languages:
SharedArrayBuffer)If you know more alternatives for this list, please open an issue.
Licensed under either of
at your option.
Note that this crate contains a copy of the file cache_padded.rs from
https://github.com/crossbeam-rs/crossbeam.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
No open issues yet, or sync has not completed.