# API Reference: `fibre`
## 1. Core Concepts
`fibre` is a library of high-performance, memory-efficient, and flexible channels for concurrent programming in Rust. It provides specialized implementations for common producer/consumer patterns.
* **Specialized Channels**: The library offers distinct channel types, each optimized for a specific concurrency pattern to ensure maximum performance and low overhead:
* `spsc`: **S**ingle-**P**roducer, **S**ingle-**C**onsumer. The fastest channel for 1-to-1 communication, implemented with a lock-free ring buffer.
* `mpsc`: **M**ulti-**P**roducer, **S**ingle-**C**onsumer. Ideal for collecting work from many sources into one processor. Supports both bounded and unbounded modes.
* `spmc`: **S**ingle-**P**roducer, **M**ulti-**C**onsumer. A "broadcast" or "fan-out" channel where one producer sends cloned messages to many consumers.
* `mpmc`: **M**ulti-**P**roducer, **M**ulti-**C**onsumer. The most flexible channel for many-to-many communication, supporting both bounded and unbounded modes.
* `oneshot`: A channel for sending a single value, exactly once.
* **Hybrid Sync/Async Model**: A core feature of `fibre` is the seamless interoperability between synchronous (`std::thread`) and asynchronous (`tokio`) code. All `Sender` and `Receiver` handles provide `to_sync()` or `to_async()` methods that perform a zero-cost conversion. This allows, for example, a synchronous thread to send data to an asynchronous task on the same channel.
* **Sender and Receiver Handles**: Interaction with channels is done through `Sender` and `Receiver` handles. These handles control access and lifetime. When all `Sender` handles for a channel are dropped, it becomes "disconnected." When all `Receiver` handles are dropped, it becomes "closed." Handle cloning semantics vary by channel type (e.g., `mpmc::Sender` is `Clone`, but `spsc::Sender` is not).
* **Stream API**: All asynchronous receivers that can yield multiple items (`mpmc`, `mpsc`, `spmc`, `spsc`) implement the `futures::Stream` trait, allowing them to be used with the rich combinator library from `futures-util`.
## 2. Error Handling
`fibre` uses a consistent set of error types to signal the outcome of channel operations.
### `TrySendError<T>`
Returned by non-blocking `try_send` methods.
* **Enum Variants**:
* `Full(T)`: The channel is full and cannot accept an item.
* `Closed(T)`: The channel is closed because the receiver(s) have dropped.
* `Sent(T)`: (Oneshot only) A value has already been sent on this channel.
* **Methods**:
* `pub fn into_inner(self) -> T`: Consumes the error to recover the unsent item.
### `SendError`
Returned by blocking or `async` `send` methods.
* **Enum Variants**:
* `Closed`: The channel is closed because the receiver(s) have dropped.
* `Sent`: (Oneshot only) A value has already been sent.
### `TryRecvError`
Returned by non-blocking `try_recv` methods.
* **Enum Variants**:
* `Empty`: The channel is currently empty but still active.
* `Disconnected`: The channel is empty and all senders have dropped.
### `RecvError`
Returned by blocking or `async` `recv` methods.
* **Enum Variants**:
* `Disconnected`: The channel is empty and all senders have dropped.
### `RecvErrorTimeout`
Returned by `recv_timeout` methods.
* **Enum Variants**:
* `Disconnected`: The channel became disconnected during the wait.
* `Timeout`: The timeout elapsed before an item could be received.
### `CloseError`
A unit-like struct returned when `close()` is called on an already-closed handle.
## 3. Module `fibre::oneshot`
A channel for sending a single value from one of potentially many senders to a single receiver.
### Functions
* `pub fn oneshot<T>() -> (Sender<T>, Receiver<T>)`
### Struct `Sender<T>`
The sending side of a oneshot channel. Can be cloned. `send` consumes the handle.
* **Methods**:
* `pub fn send(self, value: T) -> Result<(), TrySendError<T>>`
* `pub fn close(&self) -> Result<(), CloseError>`
* `pub fn is_closed(&self) -> bool`
* `pub fn is_sent(&self) -> bool`
### Struct `Receiver<T>`
The receiving side of a oneshot channel. Cannot be cloned.
* **Methods**:
* `pub fn recv(&self) -> ReceiveFuture<'_, T>`
* `pub fn try_recv(&self) -> Result<T, TryRecvError>`
* `pub fn close(&self) -> Result<(), CloseError>`
* `pub fn is_closed(&self) -> bool`
## 4. Module `fibre::spsc`
A high-performance, lock-free, bounded channel for one producer and one consumer.
### Functions
* `pub fn bounded_sync<T: Send>(capacity: usize) -> (BoundedSyncSender<T>, BoundedSyncReceiver<T>)`
* `pub fn bounded_async<T: Send>(capacity: usize) -> (AsyncBoundedSpscSender<T>, AsyncBoundedSpscReceiver<T>)`
### Struct `BoundedSyncSender<T>`
The synchronous, non-cloneable sending handle.
* **Methods**:
* `pub fn to_async(self) -> AsyncBoundedSpscSender<T>`
* `pub fn try_send(&self, item: T) -> Result<(), TrySendError<T>>`
* `pub fn send(&self, mut item: T) -> Result<(), SendError>`
* `pub fn close(&self) -> Result<(), CloseError>`
* `pub fn is_closed(&self) -> bool`
* `pub fn capacity(&self) -> usize`
* `pub fn len(&self) -> usize`
* `pub fn is_empty(&self) -> bool`
* `pub fn is_full(&self) -> bool`
### Struct `BoundedSyncReceiver<T>`
The synchronous, non-cloneable receiving handle.
* **Methods**:
* `pub fn to_async(self) -> AsyncBoundedSpscReceiver<T>`
* `pub fn try_recv(&self) -> Result<T, TryRecvError>`
* `pub fn recv(&self) -> Result<T, RecvError>`
* `pub fn recv_timeout(&mut self, timeout: std::time::Duration) -> Result<T, RecvErrorTimeout>`
* `pub fn close(&self) -> Result<(), CloseError>`
* `is_closed`, `capacity`, `len`, `is_empty`, `is_full`
### Struct `AsyncBoundedSpscSender<T>`
The asynchronous, non-cloneable sending handle.
* **Methods**:
* `pub fn to_sync(self) -> BoundedSyncSender<T>`
* `pub fn send(&self, item: T) -> SendFuture<'_, T>`
* `try_send`, `close`, `is_closed`, `capacity`, `len`, `is_empty`, `is_full`
### Struct `AsyncBoundedSpscReceiver<T>`
The asynchronous, non-cloneable receiving handle. Implements `futures::Stream`.
* **Methods**:
* `pub fn to_sync(self) -> BoundedSyncReceiver<T>`
* `pub fn recv(&self) -> ReceiveFuture<'_, T>`
* `try_recv`, `close`, `is_closed`, `capacity`, `len`, `is_empty`, `is_full`
## 5. Module `fibre::mpsc`
An optimized channel for multiple producers and one consumer.
*Note: The `mpsc` module exports unbounded channel types directly (e.g., `mpsc::Sender`). Bounded types are available via `mpsc::bounded_sync::Sender` and `mpsc::bounded_async::AsyncSender`.*
### Functions
* `pub fn unbounded<T: Send>() -> (Sender<T>, Receiver<T>)`
* `pub fn unbounded_async<T: Send>() -> (AsyncSender<T>, AsyncReceiver<T>)`
* `pub fn bounded<T: Send>(capacity: usize) -> (bounded_sync::Sender<T>, bounded_sync::Receiver<T>)`
* `pub fn bounded_async<T: Send>(capacity: usize) -> (bounded_async::AsyncSender<T>, bounded_async::AsyncReceiver<T>)`
### Unbounded MPSC Types
* **Struct `Sender<T: Send>`**: A cloneable, sync handle for the unbounded channel.
* `send(&self, value: T) -> Result<(), SendError>`: Non-blocking send.
* Methods: `try_send`, `is_closed`, `close`, `len`, `is_empty`, `to_async`.
* **Struct `Receiver<T: Send>`**: A non-cloneable, sync handle.
* `recv(&self) -> Result<T, RecvError>`: Blocks if empty.
* Methods: `try_recv`, `is_closed`, `close`, `len`, `is_empty`, `to_async`.
* **Struct `AsyncSender<T: Send>`**: A cloneable, async handle.
* `send(&self, value: T) -> SendFuture<'_, T>`: Non-blocking future.
* Methods: `try_send`, `is_closed`, `close`, `len`, `is_empty`, `to_sync`.
* **Struct `AsyncReceiver<T: Send>`**: A non-cloneable, async handle. Implements `futures::Stream`.
* `recv(&self) -> RecvFuture<'_, T>`: Returns a future that waits for an item.
* Methods: `try_recv`, `is_closed`, `close`, `len`, `is_empty`, `to_sync`.
### Bounded MPSC Types
* **Struct `bounded_sync::Sender<T: Send>`**: A cloneable, sync handle for the bounded channel.
* `send(&self, value: T) -> Result<(), SendError>`: Blocks if full.
* Methods: `try_send`, `clone`, `is_closed`, `len`, `is_empty`, `capacity`, `is_full`, `to_async`.
* **Struct `bounded_sync::Receiver<T: Send>`**: A non-cloneable, sync handle.
* `recv(&self) -> Result<T, RecvError>`: Blocks if empty.
* Methods: `try_recv`, `is_closed`, `len`, `is_empty`, `capacity`, `is_full`, `to_async`.
* **Struct `bounded_async::AsyncSender<T: Send>`**: A cloneable, async handle.
* `send(&self, value: T) -> SendFuture<'_, T>`: Returns a future that waits for capacity.
* Methods: `try_send`, `clone`, `is_closed`, `len`, `is_empty`, `capacity`, `is_full`, `to_sync`.
* **Struct `bounded_async::AsyncReceiver<T: Send>`**: A non-cloneable, async handle. Implements `futures::Stream`.
* `recv(&self) -> RecvFuture<'_, T>`: Returns a future that waits for an item.
* Methods: `try_recv`, `is_closed`, `len`, `is_empty`, `capacity`, `is_full`, `to_sync`.
## 6. Module `fibre::spmc`
A broadcast-style channel for one producer and multiple consumers. `T` must be `Send + Clone`.
### Functions
* `pub fn bounded<T: Send + Clone>(capacity: usize) -> (Sender<T>, Receiver<T>)`
* `pub fn bounded_async<T: Send + Clone>(capacity: usize) -> (AsyncSender<T>, AsyncReceiver<T>)`
### Struct `Sender<T: Send + Clone>`
The synchronous, non-cloneable sending handle.
* **Methods**:
* `send(&self, value: T) -> Result<(), SendError>`: Blocks if any consumer's buffer is full.
* `try_send(&self, value: T) -> Result<(), TrySendError<T>>`
* `close(&mut self) -> Result<(), CloseError>`
* `to_async`, `is_closed`, `capacity`, `len`, `is_empty`, `is_full`.
### Struct `Receiver<T: Send + Clone>`
The synchronous, cloneable receiving handle.
* **Methods**:
* `recv(&self) -> Result<T, RecvError>`: Blocks if this consumer's buffer is empty.
* `try_recv(&self) -> Result<T, TryRecvError>`
* `close(&self) -> Result<(), CloseError>`
* `to_async`, `is_closed`, `capacity`, `len`, `is_empty`, `is_full`.
### Struct `AsyncSender<T: Send + Clone>`
The asynchronous, non-cloneable sending handle.
* **Methods**:
* `send(&self, value: T) -> SendFuture<'_, T>`
* `try_send`, `close`, `to_sync`, `is_closed`, `capacity`, `len`, `is_empty`, `is_full`.
### Struct `AsyncReceiver<T: Send + Clone>`
The asynchronous, cloneable receiving handle. Implements `futures::Stream`.
* **Methods**:
* `recv(&self) -> RecvFuture<'_, T>`
* `try_recv`, `close`, `to_sync`, `is_closed`, `capacity`, `len`, `is_empty`, `is_full`.
## 7. Module `fibre::mpmc`
A flexible, lock-based channel for many producers and many consumers.
### Functions
* `pub fn bounded<T: Send>(capacity: usize) -> (Sender<T>, Receiver<T>)`
* `pub fn bounded_async<T: Send>(capacity: usize) -> (AsyncSender<T>, AsyncReceiver<T>)`
* `pub fn unbounded<T: Send>() -> (Sender<T>, Receiver<T>)`
* `pub fn unbounded_async<T: Send>() -> (AsyncSender<T>, AsyncReceiver<T>)`
### Struct `Sender<T: Send>`
The synchronous, cloneable sending handle.
* **Methods**:
* `send(&self, item: T) -> Result<(), SendError>`: Blocks if the channel is full.
* `try_send(&self, item: T) -> Result<(), TrySendError<T>>`
* `close(&self) -> Result<(), CloseError>`
* `to_async`, `is_closed`, `capacity`, `len`, `is_empty`, `is_full`.
### Struct `Receiver<T: Send>`
The synchronous, cloneable receiving handle.
* **Methods**:
* `recv(&self) -> Result<T, RecvError>`: Blocks if the channel is empty.
* `try_recv(&self) -> Result<T, TryRecvError>`
* `close(&self) -> Result<(), CloseError>`
* `to_async`, `is_closed`, `capacity`, `len`, `is_empty`, `is_full`.
### Struct `AsyncSender<T: Send>`
The asynchronous, cloneable sending handle.
* **Methods**:
* `send(&self, item: T) -> SendFuture<'_, T>`
* `try_send`, `close`, `to_sync`, `is_closed`, `capacity`, `len`, `is_empty`, `is_full`.
### Struct `AsyncReceiver<T: Send>`
The asynchronous, cloneable receiving handle. Implements `futures::Stream`.
* **Methods**:
* `recv(&self) -> RecvFuture<'_, T>`
* `try_recv`, `close`, `to_sync`, `is_closed`, `capacity`, `len`, `is_empty`, `is_full`.