hft-channel 0.2.1

SPMC broadcast channel for HFT and real-time systems
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

# SPMC broadcast channel for HFT and real-time systems

A lightweight, ultra-low-latency **single-producer / multi-consumer** broadcast channel designed for use in **high-frequency trading (HFT)** and other real-time systems.

Provides predictable performance, minimal contention, and carefully controlled memory access patterns.
Works for **thread-to-thread broadcasting** via local memory, or **inter-process communication** using shared memory.

[![Crates.io](https://img.shields.io/crates/v/hft-channel.svg)](https://crates.io/crates/hft-channel)
[![Documentation](https://docs.rs/hft-channel/badge.svg)](https://docs.rs/hft-channel)
[![License: LGPL-3.0-or-later](https://img.shields.io/badge/License-LGPL%203.0--or--later-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
[![Rust](https://img.shields.io/badge/rust-stable-brightgreen.svg)](https://www.rust-lang.org)

## Features

* **Lock-free** single-producer / multi-consumer broadcast channel
* **Seq_no protocol** ensures overwrite detection
* **Spin-wait receivers** for ultra-low latency
* **Cache-friendly** layout (CachePadded)
* Works **between threads**, or **between processes** via shared memory
* Zero allocations after initialization
* `no_std`-friendly design

## Spin-Wait Behavior

Receivers use **busy-waiting** (spin loops) to wait for the producer to
complete publishing the next message.

**Implications:**

* **Lowest possible latency** (no OS scheduling)
* A receiver consumes **one logical CPU core** while waiting
* Best when producer and receivers are on the **same NUMA node**
* Not ideal for scenarios where power efficiency matters
* No OS blocking (by design)

This design is intended for **HFT**, **trading engines**, **matching engines**, **real-time telemetry**, and other performance-critical workloads.

## Installation

```toml
[dependencies]
hft-channel = "0.1"
```

## Quick Example

```rust
use hft-channel::spmc_broadcast::channel;

let (tx, rx) = channel::<u64>("/test", 512);

let (_, payload) = tx.reserve();
*payload = 42;
tx.commit();

let (_, payload) = rx.recv();
```

## Design Overview

The channel tracks state as:

```
[ dirty (1 bit, MSB) | seq_no (63 bits) ]
```

Guarantees:

* At least **one slot is always dirty**
* Dirty slot = being written, reserved for writing
* Clean slot = readable and stable
* If receiver sees *seq_no changed*, the slot was overwritten

Pattern:

1. Sender marks **next reserved** slot dirty
2. Sender writes payload into **current reserved** slot
3. Sender clears dirty flag of current slot (= commit)
4. Receiver waits for `dirty == false`, then copies or peeks

## Benchmarks

```bash
RUSTFLAGS="-C target-cpu=native" cargo build --release --example bench
./target/release/examples/bench --help
./target/release/examples/bench broadcast -p 1000 -m 2
```

## Testing

```bash
cargo test
```

## License

Copyright © 2005–2025 IKH Software, Inc.

Licensed under **LGPL-3.0-or-later**.
See [`LICENSE`](LICENSE) or [https://www.gnu.org/licenses/lgpl-3.0.html](https://www.gnu.org/licenses/lgpl-3.0.html).

## Contributing

Contributions are welcome! Please open issues or pull requests on GitHub.

By submitting a contribution, you agree that it will be licensed under the
project’s **LGPL-3.0-or-later** license.