rustfs_erasure_codec/core/
options.rs

1/// Selects the codec algorithm family for encoding and reconstruction.
2///
3/// - [`Classic`](CodecFamily::Classic): Standard Reed-Solomon over GF(2^8) using
4///   Vandermonde/Cauchy matrix multiplication. Supports all shard counts up to
5///   `Field::ORDER`, incremental `update`, and `encode_single`.
6///
7/// - [`LeopardGF8`](CodecFamily::LeopardGF8): FFT-based Leopard codec over GF(2^8).
8///   Uses Fermat-number FFT with Forney syndrome decoding. Requires shard lengths
9///   that are multiples of 64 bytes. Does **not** support `encode_single` or `update`.
10///   Supports up to 256 total shards (data + parity).
11///
12/// - [`LeopardGF16`](CodecFamily::LeopardGF16): FFT-based Leopard codec over GF(2^16).
13///   Supports up to 65536 total shards (data + parity).
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
15pub enum CodecFamily {
16    Classic,
17    LeopardGF8,
18    LeopardGF16,
19}
20
21/// Selects the encoding matrix construction strategy for [`CodecFamily::Classic`].
22///
23/// This option is ignored for Leopard families (they use FFT-based encoding).
24///
25/// - [`Vandermonde`](MatrixMode::Vandermonde): Standard Vandermonde matrix.
26/// - [`Cauchy`](MatrixMode::Cauchy): Cauchy matrix construction.
27/// - [`JerasureLike`](MatrixMode::JerasureLike): Jerasure-compatible matrix layout.
28/// - [`Custom`](MatrixMode::Custom): User-supplied matrix via
29///   [`ReedSolomon::with_custom_matrix`](crate::ReedSolomon::with_custom_matrix).
30#[derive(Debug, Clone, Copy, PartialEq, Eq)]
31pub enum MatrixMode {
32    Vandermonde,
33    Cauchy,
34    JerasureLike,
35    Custom,
36}
37
38/// Configuration options for constructing a [`ReedSolomon`](crate::ReedSolomon) codec.
39///
40/// Use `CodecOptions::default()` for sensible defaults, or the builder methods:
41///
42/// ```ignore
43/// use rustfs_erasure_codec::core::{CodecOptions, CodecFamily};
44///
45/// let opts = CodecOptions::builder()
46///     .codec_family(CodecFamily::LeopardGF8)
47///     .fast_one_parity(true)
48///     .build();
49/// ```
50#[derive(Debug, Clone, Copy, PartialEq, Eq)]
51pub struct CodecOptions {
52    /// When `true` and parity shard count is 1, use XOR-only fast path instead of
53    /// full matrix multiplication. Default: `false`.
54    pub fast_one_parity: bool,
55    /// When `true`, cache the inverted decode matrix for repeated reconstruction
56    /// with the same erasure pattern. Default: `true`.
57    pub inversion_cache: bool,
58    /// Capacity of the inversion cache (LRU). `0` means automatic sizing based on
59    /// shard counts. Default: `0`.
60    pub inversion_cache_capacity: usize,
61    /// The codec algorithm family to use. Default: [`CodecFamily::Classic`].
62    pub codec_family: CodecFamily,
63    /// The matrix construction strategy (only used for [`CodecFamily::Classic`]).
64    /// Default: [`MatrixMode::Vandermonde`].
65    pub matrix_mode: MatrixMode,
66    /// Maximum number of parallel jobs for encode/decode operations.
67    /// `0` means automatic (uses `available_parallelism()`). Default: `0`.
68    pub max_parallel_jobs: usize,
69}
70
71impl Default for CodecOptions {
72    fn default() -> Self {
73        Self {
74            fast_one_parity: false,
75            inversion_cache: true,
76            inversion_cache_capacity: 0,
77            codec_family: CodecFamily::Classic,
78            matrix_mode: MatrixMode::Vandermonde,
79            max_parallel_jobs: 0,
80        }
81    }
82}
83
84/// Builder for [`CodecOptions`].
85///
86/// Created via [`CodecOptions::builder()`]. All methods chain; call [`build()`](CodecOptionsBuilder::build) to obtain the final `CodecOptions`.
87#[derive(Debug, Clone, Copy)]
88pub struct CodecOptionsBuilder {
89    options: CodecOptions,
90}
91
92impl CodecOptions {
93    /// Create a new builder with default options.
94    pub fn builder() -> CodecOptionsBuilder {
95        CodecOptionsBuilder {
96            options: CodecOptions::default(),
97        }
98    }
99}
100
101impl CodecOptionsBuilder {
102    /// Set the codec algorithm family.
103    pub fn codec_family(mut self, family: CodecFamily) -> Self {
104        self.options.codec_family = family;
105        self
106    }
107
108    /// Set the matrix construction strategy.
109    pub fn matrix_mode(mut self, mode: MatrixMode) -> Self {
110        self.options.matrix_mode = mode;
111        self
112    }
113
114    /// Enable or disable the XOR-only fast path for single parity shards.
115    pub fn fast_one_parity(mut self, enabled: bool) -> Self {
116        self.options.fast_one_parity = enabled;
117        self
118    }
119
120    /// Enable or disable the inversion cache.
121    pub fn inversion_cache(mut self, enabled: bool) -> Self {
122        self.options.inversion_cache = enabled;
123        self
124    }
125
126    /// Set the inversion cache capacity. `0` for automatic sizing.
127    pub fn inversion_cache_capacity(mut self, capacity: usize) -> Self {
128        self.options.inversion_cache_capacity = capacity;
129        self
130    }
131
132    /// Set the maximum number of parallel jobs. `0` for automatic.
133    pub fn max_parallel_jobs(mut self, jobs: usize) -> Self {
134        self.options.max_parallel_jobs = jobs;
135        self
136    }
137
138    /// Build the final [`CodecOptions`].
139    pub fn build(self) -> CodecOptions {
140        self.options
141    }
142}
rustfs_erasure_codec/core/options.rs

rustfs_erasure_codec/core/
options.rs
