fibre

Crates.iofibre
lib.rsfibre
version0.5.0
created_at2025-06-06 06:17:49.650648+00
updated_at2025-06-23 02:47:48.425283+00
descriptionHigh-performance, safe, memory-efficient sync/async channels built for real-time, low-overhead communication in concurrent Rust applications.
homepagehttps://github.com/excsn/fibre
repositoryhttps://github.com/excsn/fibre
max_upload_size
id1702626
size547,006
Norm O (normano)

documentation

README

fibre

crates.io docs.rs License: MPL-2.0

fibre provides a suite of high-performance, memory-efficient sync/async channels for Rust. It is designed to offer the best possible performance for a given concurrency pattern by providing specialized channel implementations rather than a single, general-purpose one. This allows developers to solve concurrency problems with tools that are tailored for their specific needs, from blazing-fast SPSC queues to flexible MPMC channels.

⚠️ Current Status: Beta

fibre is in BETA. The API is generally stable, but minor breaking changes may occur before version 1.0 as feedback is incorporated and improvements are made.

Key Features

Comprehensive Channel Suite

Fibre offers a wide range of channel types, each optimized for a specific producer-consumer pattern:

  • spsc: A lock-free Single-Producer, Single-Consumer ring buffer, ideal for maximum throughput in 1-to-1 communication. Bounded. Requires T: Send.
  • mpsc: A lock-free Multi-Producer, Single-Consumer channel, perfect for scenarios where many tasks need to send work to a single processing task. Supports both bounded and unbounded modes. Requires T: Send.
  • spmc: A "broadcast" style Single-Producer, Multi-Consumer channel where each message is cloned and delivered to every active consumer. Bounded. Requires T: Send + Clone.
  • spmc::topic: A "publish-subscribe" variant of SPMC where the producer sends messages to named topics, and consumers subscribe to the topics they're interested in. The sender is non-blocking, dropping messages for slow consumers. Requires K: Send + Sync + Hash + Eq + Clone and T: Send + Clone.
  • mpmc: A flexible and robust Multi-Producer, Multi-Consumer channel for general-purpose use where producer and consumer counts are dynamic. Supports bounded (including rendezvous) and "unbounded" capacities. Requires T: Send.
  • oneshot: A channel for sending a single value once, perfect for futures and promise-style patterns. Requires T: Send.

Hybrid Sync/Async API

A standout feature is the ability to seamlessly mix synchronous and asynchronous code. You can create a synchronous Sender and an asynchronous AsyncReceiver (or any other combination) from the same SPSC, MPSC, SPMC, or MPMC channel. This is enabled by zero-cost to_sync() and to_async() conversion methods on the channel handles, providing maximum flexibility for integrating into different codebases and runtimes.

Consistent and Ergonomic API

One of the core design goals of fibre is API consistency. A developer should not have to re-learn methods for each channel type. All channels share a common set of methods with consistent semantics, allowing for predictable and ergonomic use.

API Parity Overview

The following tables summarize the consistent API surface across all channel senders and receivers.

Sender API

Method MPMC Sender MPSC Sender (B/U) SPMC Sender SPMC Topic Sender SPSC Sender Oneshot Sender
send()/send().await ✅ ✅ ✅ ✅ (non-blocking) ✅ ✅ (Consumes self)
try_send() ✅ ✅ ✅ N/A ✅ ✅ (send is try)
close() ✅ ✅ ✅ (&mut self) ✅ ✅ ✅
is_closed() ✅ ✅ ✅ ✅ ✅ ✅
len() ✅ ✅ ✅ ❌ ✅ N/A
is_empty() ✅ ✅ ✅ ❌ ✅ ❌
is_full() ✅ ✅ (bounded) ✅ ❌ ✅ N/A
capacity() ✅ ✅ (bounded) ✅ ❌ ✅ N/A
clone() ✅ ✅ ❌ ✅ ❌ ✅

Receiver API

Method MPMC Receiver MPSC Receiver (B/U) SPMC Receiver SPMC Topic Receiver SPSC Receiver Oneshot Receiver
recv()/recv().await ✅ ✅ ✅ ✅ ✅ ✅
try_recv() ✅ ✅ ✅ ✅ ✅ ✅
recv_timeout() ✅ ✅ ✅ ✅ ✅ (&mut self) N/A
subscribe/unsubscribe N/A N/A N/A ✅ N/A N/A
close() ✅ ✅ ✅ ✅ ✅ ✅
is_closed() ✅ ✅ ✅ ✅ ✅ ✅
len() ✅ ✅ ✅ ❌ ✅ N/A
is_empty() ✅ ✅ ✅ ✅ ✅ ❌
is_full() ✅ ✅ (bounded) ✅ ❌ ✅ N/A
capacity() ✅ ✅ (bounded) ✅ ✅ ✅ N/A
clone() ✅ ❌ ✅ ✅ ❌ ❌

Performance-Oriented Design

Performance is a primary goal. Fibre uses proven, high-performance algorithms for each channel type, including:

  • Lock-free ring buffers for SPSC.
  • Lock-free linked lists for MPSC.
  • A specialized ring buffer for SPMC that tracks individual consumer progress, ensuring backpressure from the slowest consumer.
  • A non-blocking, topic-based SPMC variant built on a concurrent hash map, copy-on-write lists, and individual mailboxes for high-performance pub/sub.
  • A fair, hybrid semaphore built on parking_lot::Mutex for MPMC and bounded MPSC channels.
  • Cache-line padding on critical atomic data to minimize false sharing and maximize throughput on multi-core systems.

Ergonomic and Safe

  • Explicit Lifecycle Control: All channel handles provide an idempotent close() method as an explicit alternative to drop, giving developers fine-grained control over the channel lifecycle.
  • Clear Error Handling & Drop Safety: Descriptive error types (TrySendError<T>, RecvError, CloseError) allow for value recovery and clear error reporting. Channels correctly signal disconnection when handles are dropped or explicitly closed, and any buffered items are properly deallocated.
  • Thread Safety: Each channel type enforces appropriate Send and Sync bounds, ensuring correct concurrent usage. For example, SPSC and MPSC consumer handles are !Sync as they are designed for single-threaded consumption.

Installation

Add Fibre to your project by including it in your Cargo.toml:

[dependencies]
fibre = "0.5.0" # Replace with the latest version

Or by using the command line:

cargo add fibre

There are no system prerequisites other than a standard Rust toolchain.

Getting Started

For a detailed guide, API overview, and code examples, please see the Usage Guide.

The full API reference is available on docs.rs.

License

This library is distributed under the terms of the Mozilla Public License Version 2.0 (MPL-2.0). You can find a copy of the license in the LICENSE file or at https://opensource.org/licenses/MPL-2.0.

Commit count: 63

cargo fmt