Struct reed_solomon_erasure::ReedSolomon

pub struct ReedSolomon { /* fields omitted */ }

Reed-Solomon erasure code encoder/decoder.

Common error handling

For encode, encode_shards, verify, verify_shards, reconstruct, reconstruct_data, reconstruct_shards, reconstruct_data_shards

Return Error::TooFewShards or Error::TooManyShards when the number of provided shards does not match the codec's one.

Return Error::EmptyShard when the first shard provided is of zero length.

Return Error::IncorrectShardSize when the provided shards are of different length.

For reconstruct, reconstruct_data, reconstruct_shards, reconstruct_data_shards

Return Error::TooFewShardsPresent when there are not enough shards for reconstruction.

Return Error::InvalidShardFlags when the number of flags does not match the total number of shards.

Variants of encoding methods

sep

Methods ending in _sep takes an immutable reference of data shard(s), and a mutable reference of parity shards.

They are useful as they do not need to borrow the data shard(s) mutably, and other work that only needs read-only access to data shards can be done in parallel/concurrently during the encoding.

Following is a table of all the sep variants

not sep	sep
encode_single_shard	encode_single_shard_sep
encode_shards	encode_shards_sep
encode_single	encode_single_sep
encode	encode_sep

The sep variants do similar checks on the provided data shards and parity shards.

Return Error::TooFewDataShards, Error::TooManyDataShards, Error::TooFewParityShards, or Error::TooManyParityShards when applicable.

single

Methods containing single facilitate shard by shard encoding, where the parity shards are partially constructed using one data shard at a time. See ShardByShard struct for more details on how shard by shard encoding can be useful.

They are prone to misuse, and it is recommended to use the ShardByShard bookkeeping struct instead for shard by shard encoding.

The ones that are also sep are ESPECIALLY prone to misuse. Only use them when you actually need the flexibility.

Following is a table of all the shard by shard variants

all shards at once	shard by shard
encode_shards	encode_single_shard
encode_shards_sep	encode_single_shard_sep
encode	encode_single
encode_sep	encode_single_sep

Methods

impl ReedSolomon

fn new(data_shards: usize, parity_shards: usize) -> ReedSolomon

Creates a new instance of Reed-Solomon erasure code encoder/decoder.

fn with_pparam(
    data_shards: usize,
    parity_shards: usize,
    pparam: ParallelParam
) -> ReedSolomon

Creates a new instance of Reed-Solomon erasure code encoder/decoder with custom ParallelParam.

fn data_shard_count(&self) -> usize

fn parity_shard_count(&self) -> usize

fn total_shard_count(&self) -> usize

fn encode_single_shard(
    &self,
    i_data: usize,
    shards: &mut [Shard]
) -> Result<(), Error>

Constructs the parity shards partially using only the data shard indexed by i_data.

The slots where the parity shards sit at will be overwritten.

This is a wrapper of encode_single.

Warning

You must apply this method on the data shards in strict sequential order(0..data shard count), otherwise the parity shards will be incorrect.

It is recommended to use the ShardByShard bookkeeping struct instead of this method directly.

fn encode_single_shard_sep(
    &self,
    i_data: usize,
    single_data: &Shard,
    parity: &mut [Shard]
) -> Result<(), Error>

Constructs the parity shards partially using only the data shard provided.

The data shard must match the index i_data.

The slots where the parity shards sit at will be overwritten.

This is a wrapper of encode_single_sep.

Warning

You must apply this method on the data shards in strict sequential order(0..data shard count), otherwise the parity shards will be incorrect.

It is recommended to use the ShardByShard bookkeeping struct instead of this method directly.

fn encode_shards(&self, shards: &mut [Shard]) -> Result<(), Error>

Constructs the parity shards.

The slots where the parity shards sit at will be overwritten.

This is a wrapper of encode.

fn encode_shards_sep(
    &self,
    data: &[Shard],
    parity: &mut [Shard]
) -> Result<(), Error>

Constructs the parity shards.

The slots where the parity shards sit at will be overwritten.

This is a wrapper of encode_sep.

fn encode_single(
    &self,
    i_data: usize,
    slices: &mut [&mut [u8]]
) -> Result<(), Error>

Constructs the parity shards partially using only the data shard indexed by i_data.

The slots where the parity shards sit at will be overwritten.

Warning

You must apply this method on the data shards in strict sequential order(0..data shard count), otherwise the parity shards will be incorrect.

It is recommended to use the ShardByShard bookkeeping struct instead of this method directly.

fn encode_single_sep(
    &self,
    i_data: usize,
    single_data: &[u8],
    parity: &mut [&mut [u8]]
) -> Result<(), Error>

Constructs the parity shards partially using only the data shard provided.

The data shard must match the index i_data.

The slots where the parity shards sit at will be overwritten.

Warning

You must apply this method on the data shards in strict sequential order(0..data shard count), otherwise the parity shards will be incorrect.

It is recommended to use the ShardByShard bookkeeping struct instead of this method directly.

fn encode(&self, slices: &mut [&mut [u8]]) -> Result<(), Error>

Constructs the parity shards.

The slots where the parity shards sit at will be overwritten.

fn encode_sep(
    &self,
    data: &[&[u8]],
    parity: &mut [&mut [u8]]
) -> Result<(), Error>

Constructs the parity shards.

The slots where the parity shards sit at will be overwritten.

fn verify_shards(&self, shards: &[Shard]) -> Result<bool, Error>

Checks if the parity shards are correct.

This is a wrapper of verify.

fn verify(&self, slices: &[&[u8]]) -> Result<bool, Error>

Checks if the parity shards are correct.

fn reconstruct(
    &self,
    slices: &mut [&mut [u8]],
    slice_present: &[bool]
) -> Result<(), Error>

Reconstructs all shards.

The shards marked not present are only overwritten when no error is detected.

This means if the method returns an Error, then nothing is touched.

reconstruct, reconstruct_data, reconstruct_shards, reconstruct_data_shards share the same core code base.

fn reconstruct_data(
    &self,
    slices: &mut [&mut [u8]],
    slice_present: &[bool]
) -> Result<(), Error>

Reconstructs only the data shards.

The shards marked not present are only overwritten when no error is detected.

This means if the method returns an Error, then nothing is touched.

reconstruct, reconstruct_data, reconstruct_shards, reconstruct_data_shards share the same core code base.

fn reconstruct_shards(&self, shards: &mut [Option<Shard>]) -> Result<(), Error>

Reconstructs all shards.

This fills in the missing shards with blank shards only if there are enough shards for reconstruction.

reconstruct, reconstruct_data, reconstruct_shards, reconstruct_data_shards share the same core code base.

fn reconstruct_data_shards(
    &self,
    shards: &mut [Option<Shard>]
) -> Result<(), Error>

Reconstructs only the data shards.

This fills in the missing shards with blank shards only if there are enough shards for reconstruction.

Note that the missing parity shards are filled in with blank shards even though they are not used.

reconstruct, reconstruct_data, reconstruct_shards, reconstruct_data_shards share the same core code base.

Trait Implementations

impl Debug for ReedSolomon

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Clone for ReedSolomon

fn clone(&self) -> ReedSolomon

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl PartialEq for ReedSolomon

fn eq(&self, rhs: &ReedSolomon) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.