fec_rs/lib.rs
1//! A pure Rust Reed-Solomon erasure coding library with runtime SIMD acceleration.
2//!
3//! # Features
4//!
5//! - **Pure Rust** — No C/C++ dependencies or FFI. Everything is implemented in safe Rust
6//! (with targeted `unsafe` for SIMD intrinsics).
7//! - **Runtime SIMD detection** — Automatically uses the fastest available instruction set
8//! via `std::is_x86_feature_detected!`. A single binary works on all x86_64 systems.
9//! - **GF(2^8)** — Operates over the Galois field GF(2^8) with generating polynomial 29 (0x1D),
10//! compatible with the Moonlight streaming protocol.
11//! - **Shard-by-shard encoding** — Incremental encoding via `ShardByShard` for streaming use cases.
12//! - **Reconstruction** — Reconstruct missing data and/or parity shards from any sufficient subset.
13//!
14//! # SIMD Acceleration
15//!
16//! On x86_64, the library automatically detects CPU features at runtime and uses
17//! the best available instruction set:
18//!
19//! - **GFNI + AVX2** — Single-instruction GF multiply on 32 bytes (Intel Alder Lake+, AMD Zen 4+)
20//! - **AVX2** — VPSHUFB split-table nibble lookup on 32 bytes
21//! - **GFNI + SSE** — Single-instruction GF multiply on 16 bytes
22//! - **SSSE3** — VPSHUFB split-table nibble lookup on 16 bytes
23//! - **Scalar** — Lookup table fallback
24//!
25//! # Parallel Encoding
26//!
27//! Enable the `parallel` feature for optional rayon-based parallel encoding:
28//!
29//! ```toml
30//! fec-rs = { version = "0.1", features = ["parallel"] }
31//! ```
32//!
33//! When enabled, large encode workloads automatically distribute parity shard
34//! computation across threads. Small workloads use the sequential path to avoid
35//! overhead.
36//!
37//! # Usage
38//!
39//! ```
40//! use fec_rs::ReedSolomon;
41//!
42//! let rs = ReedSolomon::new(4, 2).unwrap();
43//!
44//! let mut shards: Vec<Vec<u8>> = vec![
45//! vec![0, 1, 2, 3],
46//! vec![4, 5, 6, 7],
47//! vec![8, 9, 10, 11],
48//! vec![12, 13, 14, 15],
49//! vec![0, 0, 0, 0], // parity shard 1
50//! vec![0, 0, 0, 0], // parity shard 2
51//! ];
52//!
53//! // Encode parity
54//! rs.encode(&mut shards).unwrap();
55//!
56//! // Verify
57//! assert!(rs.verify(&shards).unwrap());
58//!
59//! // Simulate loss of shard 0
60//! let mut recovery: Vec<Option<Vec<u8>>> = shards.into_iter().map(Some).collect();
61//! recovery[0] = None;
62//!
63//! // Reconstruct
64//! rs.reconstruct(&mut recovery).unwrap();
65//! ```
66
67mod errors;
68pub mod galois;
69mod matrix;
70mod reed_solomon;
71
72pub use errors::{Error, SBSError};
73pub use reed_solomon::{ReconstructShard, ReedSolomon, ShardByShard};