crossfire 2.0.2

channels for async and threads
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

# Crossfire

[![Build Status](https://github.com/frostyplanet/crossfire-rs/workflows/Rust/badge.svg)](
https://github.com/frostyplanet/crossfire-rs/actions)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](
https://github.com/qignstor/crossfire-rs#license)
[![Cargo](https://img.shields.io/crates/v/crossfire.svg)](
https://crates.io/crates/crossfire)
[![Documentation](https://docs.rs/crossfire/badge.svg)](
https://docs.rs/crossfire)
[![Rust 1.36+](https://img.shields.io/badge/rust-1.36+-lightgray.svg)](
https://www.rust-lang.org)

High-performance spsc/mpsc/mpmc channels.

It supports async context, or communicates between async-blocking context.

Implemented with lockless in mind, low level is based on crossbeam-channel.
For the concept, please refer to [wiki](https://github.com/frostyplanet/crossfire-rs/wiki).


## Stability and versions

Crossfire v1.0 has been released and used in production since 2022.12. Heavily tested on X86_64 and ARM.

V2.0 has refactored the codebase and API at 2025.6. By removing generic types of ChannelShared object in sender and receiver,
it's easier to remember and code.

V2.0.x branch will remain in maintenance mode. Further optimization might be in v2.x_beta
version until long run tests prove to be stable.

## Performance

We focus on optimization of async logic, outperforming other async capability channels
(flume, tokio::mpsc, etc) in most cases.

Due to context switching between sleep and wake, there is a certain
overhead on async context over crossbeam-channel which in blocking context.

Benchmark is written in criterion framework. You can run benchmark by:

```
cargo bench
```

More benchmark data is on [wiki](https://github.com/frostyplanet/crossfire-rs/wiki). Here are some of the results:

<img src="https://github.com/frostyplanet/crossfire-rs/wiki/images/benchmark-2025-06-27/mpmc_bound_size_100_async.png" alt="mpmc bounded size 100 async context">

<img src="https://github.com/frostyplanet/crossfire-rs/wiki/images/benchmark-2025-06-27/mpsc_unbounded_async.png" alt="mpsc unbounded async context">


## APIs

### modules and functions

There are 3 modules: [spsc], [mpsc], [mpmc], providing functions to allocate different types of channels.

For SP or SC, it's more memory efficient than MP or MC implementations, and sometimes slightly faster.

The return types in these 3 modules are different:

* [mpmc::bounded_async()]:  (tx async, rx async)

* [mpmc::bounded_tx_async_rx_blocking()]

* [mpmc::bounded_tx_blocking_rx_async()]

* [mpmc::unbounded_async()]


> **NOTE** :  For bounded channel, 0 size case is not supported yet. (Temporary rewrite as 1 size).

### Types

<table align="center" cellpadding="30">
<tr> <th rowspan="2"> Context </th><th colspan="2" align="center"> Sender (Producer) </th> <th colspan="2" align="center"> Receiver (Consumer) </th> </tr>
<tr> <td> Single </td> <td> Multiple </td><td> Single </td><td> Multiple </td></tr>
<tr><td rowspan="2"> <b>Blocking</b> </td>
<td colspan="2" align="center"> <a href="trait.BlockingTxTrait.html">BlockingTxTrait</a> </td>
<td colspan="2" align="center"> <a href="trait.BlockingRxTrait.html">BlockingRxTrait</a> </td></tr>
<tr>
<td align="center"> <a href="struct.Tx.html">Tx</a> </td>
<td align="center"> <a href="struct.MTx.html">MTx</a> </td>
<td align="center"> <a href="struct.Rx.html">Rx</a> </td>
<td align="center"> <a href="struct.MRx">MRx</a> </td> </tr>

<tr><td rowspan="2"><b>Async</b></td>
<td colspan="2" align="center"><a href="trait.AsyncTxTrait.html">AsyncTxTrait</a></td>
<td colspan="2" align="center"><a href="trait.AsyncRxTrait.html">AsyncRxTrait</a></td></tr>
<tr>
<td> <a href="struct.AsyncTx.html">AsyncTx</a> </td>
<td> <a href="struct.MAsyncTx.html">MAsyncTx</a> </td>
<td> <a href="struct.AsyncRx.html">AsyncRx</a> </td>
<td> <a href="struct.MAsyncRx.html">MAsyncRx</a> </td></tr>

</table>


> **NOTE**: For SP / SC version [AsyncTx] and [AsyncRx], although not designed to be not cloneable,
 send() recv() use immutable &self for convenient reason. Be careful do not use the SP/SC concurrently when put in Arc.

### Error types

Error types are re-exported from crossbeam-channel:  [TrySendError], [SendError], [TryRecvError], [RecvError]

### Async compatibility

Mainly tested on tokio-1.x.

In async context, future-select! can be used.  Cancelling is supported. You can combine
send() or recv() future with tokio::time::timeout.

While using MAsyncTx or MAsyncRx, there's memory overhead to pass along small size wakers
for pending async producer or consumer. Because we aim to be lockless,
when the sending/receiving futures are cancelled (like tokio::time::timeout()),
might trigger immediate cleanup if non-conflict conditions are met.
Otherwise will rely on lazy cleanup. (waker will be consumed by actual message send and recv).

Never the less, for close notification without sending anything,
I suggest that use `tokio::sync::oneshot` instead.

## Usage

Cargo.toml:
```toml
[dependencies]
crossfire = "2.0"
```
example:

```rust

extern crate crossfire;
use crossfire::*;

#[tokio::main]
async main() {
    let (tx, rx) = mpsc::bounded_async::<i32>(100);
    tokio::spawn(async move {
       for i in 0i32..10000 {
           let _ = tx.send(i).await;
           println!("sent {}", i);
       }
    });
    loop {
        if let Ok(_i) = rx.recv().await {
            println!("recv {}", _i);
        } else {
            println!("rx closed");
            break;
        }
    }
}

```