reed_solomon_simd/
reed_solomon.rs

1use crate::{
2    engine::DefaultEngine,
3    rate::{DefaultRate, DefaultRateDecoder, DefaultRateEncoder, Rate, RateDecoder, RateEncoder},
4    DecoderResult, EncoderResult, Error,
5};
6
7// ======================================================================
8// ReedSolomonEncoder - PUBLIC
9
10/// Reed-Solomon encoder using [`DefaultEngine`] and [`DefaultRate`].
11///
12/// [`DefaultEngine`]: crate::engine::DefaultEngine
13pub struct ReedSolomonEncoder(DefaultRateEncoder<DefaultEngine>);
14
15impl ReedSolomonEncoder {
16    /// Adds one original shard to the encoder.
17    ///
18    /// Original shards have indexes `0..original_count` corresponding to the order
19    /// in which they are added and these same indexes must be used when decoding.
20    ///
21    /// See [basic usage](crate#basic-usage) for an example.
22    pub fn add_original_shard<T: AsRef<[u8]>>(&mut self, original_shard: T) -> Result<(), Error> {
23        self.0.add_original_shard(original_shard)
24    }
25
26    /// Encodes the added original shards returning [`EncoderResult`]
27    /// which contains the generated recovery shards.
28    ///
29    /// When returned [`EncoderResult`] is dropped the encoder is
30    /// automatically [`reset`] and ready for new round of encoding.
31    ///
32    /// See [basic usage](crate#basic-usage) for an example.
33    ///
34    /// [`reset`]: ReedSolomonEncoder::reset
35    pub fn encode(&mut self) -> Result<EncoderResult, Error> {
36        self.0.encode()
37    }
38
39    /// Creates new encoder with given configuration
40    /// and allocates required working space.
41    ///
42    /// See [basic usage](crate#basic-usage) for an example.
43    pub fn new(
44        original_count: usize,
45        recovery_count: usize,
46        shard_bytes: usize,
47    ) -> Result<Self, Error> {
48        Ok(Self(DefaultRateEncoder::new(
49            original_count,
50            recovery_count,
51            shard_bytes,
52            DefaultEngine::new(),
53            None,
54        )?))
55    }
56
57    /// Resets encoder to given configuration.
58    ///
59    /// - Added original shards are forgotten.
60    /// - Existing working space is re-used if it's large enough
61    ///   or re-allocated otherwise.
62    pub fn reset(
63        &mut self,
64        original_count: usize,
65        recovery_count: usize,
66        shard_bytes: usize,
67    ) -> Result<(), Error> {
68        self.0.reset(original_count, recovery_count, shard_bytes)
69    }
70
71    /// Returns `true` if given `original_count` / `recovery_count`
72    /// combination is supported.
73    ///
74    /// # Examples
75    ///
76    /// ```rust
77    /// use reed_solomon_simd::ReedSolomonEncoder;
78    ///
79    /// assert_eq!(ReedSolomonEncoder::supports(60_000, 4_000), true);
80    /// assert_eq!(ReedSolomonEncoder::supports(60_000, 5_000), false);
81    /// ```
82    pub fn supports(original_count: usize, recovery_count: usize) -> bool {
83        DefaultRate::<DefaultEngine>::supports(original_count, recovery_count)
84    }
85}
86
87// ======================================================================
88// ReedSolomonDecoder - PUBLIC
89
90/// Reed-Solomon decoder using [`DefaultEngine`] and [`DefaultRate`].
91///
92/// [`DefaultEngine`]: crate::engine::DefaultEngine
93pub struct ReedSolomonDecoder(DefaultRateDecoder<DefaultEngine>);
94
95impl ReedSolomonDecoder {
96    /// Adds one original shard to the decoder.
97    ///
98    /// - Shards can be added in any order.
99    /// - Index must be the same that was used in encoding.
100    ///
101    /// See [basic usage](crate#basic-usage) for an example.
102    pub fn add_original_shard<T: AsRef<[u8]>>(
103        &mut self,
104        index: usize,
105        original_shard: T,
106    ) -> Result<(), Error> {
107        self.0.add_original_shard(index, original_shard)
108    }
109
110    /// Adds one recovery shard to the decoder.
111    ///
112    /// - Shards can be added in any order.
113    /// - Index must be the same that was used in encoding.
114    ///
115    /// See [basic usage](crate#basic-usage) for an example.
116    pub fn add_recovery_shard<T: AsRef<[u8]>>(
117        &mut self,
118        index: usize,
119        recovery_shard: T,
120    ) -> Result<(), Error> {
121        self.0.add_recovery_shard(index, recovery_shard)
122    }
123
124    /// Decodes the added shards returning [`DecoderResult`]
125    /// which contains the restored original shards.
126    ///
127    /// When returned [`DecoderResult`] is dropped the decoder is
128    /// automatically [`reset`] and ready for new round of decoding.
129    ///
130    /// See [basic usage](crate#basic-usage) for an example.
131    ///
132    /// [`reset`]: ReedSolomonDecoder::reset
133    pub fn decode(&mut self) -> Result<DecoderResult, Error> {
134        self.0.decode()
135    }
136
137    /// Creates new decoder with given configuration
138    /// and allocates required working space.
139    ///
140    /// See [basic usage](crate#basic-usage) for an example.
141    pub fn new(
142        original_count: usize,
143        recovery_count: usize,
144        shard_bytes: usize,
145    ) -> Result<Self, Error> {
146        Ok(Self(DefaultRateDecoder::new(
147            original_count,
148            recovery_count,
149            shard_bytes,
150            DefaultEngine::new(),
151            None,
152        )?))
153    }
154
155    /// Resets decoder to given configuration.
156    ///
157    /// - Added shards are forgotten.
158    /// - Existing working space is re-used if it's large enough
159    ///   or re-allocated otherwise.
160    pub fn reset(
161        &mut self,
162        original_count: usize,
163        recovery_count: usize,
164        shard_bytes: usize,
165    ) -> Result<(), Error> {
166        self.0.reset(original_count, recovery_count, shard_bytes)
167    }
168
169    /// Returns `true` if given `original_count` / `recovery_count`
170    /// combination is supported.
171    ///
172    /// # Examples
173    ///
174    /// ```rust
175    /// use reed_solomon_simd::ReedSolomonDecoder;
176    ///
177    /// assert_eq!(ReedSolomonDecoder::supports(60_000, 4_000), true);
178    /// assert_eq!(ReedSolomonDecoder::supports(60_000, 5_000), false);
179    /// ```
180    pub fn supports(original_count: usize, recovery_count: usize) -> bool {
181        DefaultRate::<DefaultEngine>::supports(original_count, recovery_count)
182    }
183}
184
185// ======================================================================
186// TESTS
187
188#[cfg(test)]
189mod tests {
190    use std::collections::HashMap;
191
192    use fixedbitset::FixedBitSet;
193
194    use super::*;
195    use crate::test_util;
196
197    // ============================================================
198    // HELPERS
199
200    fn roundtrip(
201        encoder: &mut ReedSolomonEncoder,
202        decoder: &mut ReedSolomonDecoder,
203        original_count: usize,
204        recovery_hash: &str,
205        decoder_original: &[usize],
206        decoder_recovery: &[usize],
207        seed: u8,
208    ) {
209        let original = test_util::generate_original(original_count, 1024, seed);
210
211        for original in &original {
212            encoder.add_original_shard(original).unwrap();
213        }
214
215        let result = encoder.encode().unwrap();
216        let recovery: Vec<_> = result.recovery_iter().collect();
217
218        test_util::assert_hash(&recovery, recovery_hash);
219
220        let mut original_received = FixedBitSet::with_capacity(original_count);
221
222        for i in decoder_original {
223            decoder.add_original_shard(*i, &original[*i]).unwrap();
224            original_received.set(*i, true);
225        }
226
227        for i in decoder_recovery {
228            decoder.add_recovery_shard(*i, recovery[*i]).unwrap();
229        }
230
231        let result = decoder.decode().unwrap();
232        let restored: HashMap<_, _> = result.restored_original_iter().collect();
233
234        for i in 0..original_count {
235            if !original_received[i] {
236                assert_eq!(restored[&i], original[i]);
237            }
238        }
239    }
240
241    // ============================================================
242    // ROUNDTRIP - TWO ROUNDS
243
244    #[test]
245    fn roundtrip_two_rounds_reset_low_to_high() {
246        let mut encoder = ReedSolomonEncoder::new(2, 3, 1024).unwrap();
247        let mut decoder = ReedSolomonDecoder::new(2, 3, 1024).unwrap();
248
249        roundtrip(
250            &mut encoder,
251            &mut decoder,
252            2,
253            test_util::LOW_2_3,
254            &[],
255            &[0, 1],
256            123,
257        );
258
259        encoder.reset(3, 2, 1024).unwrap();
260        decoder.reset(3, 2, 1024).unwrap();
261
262        roundtrip(
263            &mut encoder,
264            &mut decoder,
265            3,
266            test_util::HIGH_3_2,
267            &[1],
268            &[0, 1],
269            132,
270        );
271    }
272
273    // ==================================================
274    // supports
275
276    #[test]
277    fn supports() {
278        assert!(ReedSolomonEncoder::supports(4096, 61440));
279        assert!(ReedSolomonEncoder::supports(61440, 4096));
280
281        assert!(ReedSolomonDecoder::supports(4096, 61440));
282        assert!(ReedSolomonDecoder::supports(61440, 4096));
283    }
284}
reed_solomon_simd/reed_solomon.rs

reed_solomon_simd/
reed_solomon.rs
