Struct solana_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 lengths.

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 to data shards, and a mutable reference to parity shards.

They are useful as they do not need to borrow the data shards 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

The single variants do similar checks on the provided data shards and parity shards, and also do index check on i_data.

Return Error::InvalidIndex if i_data >= data_shard_count.

Encoding behaviour

For encode, encode_shards

You do not need to clear the parity shards beforehand, as the methods will overwrite them completely.

For encode_single_shard, encode_single_shard_sep, encode_single, encode_single_sep

Calling them with i_data being 0 will overwrite the parity shards completely. If you are using the methods correctly, then you do not need to clear the parity shards beforehand.

Variants of verifying methods

verify, verify_shards allocate a buffer on the heap of the same size as the parity shards, and encode the input once using the buffer to store the computed parity shards, then check if the provided parity shards match the computed ones.

verify_with_buffer, verify_shards_with_buffer allow you to provide the buffer to avoid making heap allocation(s) for the buffer in every call.

The with_buffer variants also guarantee that the buffer contains the correct parity shards if the result is Ok(_) (i.e. it does not matter whether the verification passed or not, as long as the result is not an error, the buffer will contain the correct parity shards after the call).

Following is a table of all the with_buffer variants

not with_buffer	with_buffer
verify_shards	verify_shards_with_buffer
verify	verify_with_buffer

The with_buffer variants also check the dimensions of the buffer and return Error::TooFewBufferShards, Error::TooManyBufferShards, Error::EmptyShard, or Error::IncorrectShardSize when applicable.

Methods

impl ReedSolomon

pub fn new(
    data_shards: usize,
    parity_shards: usize
) -> Result<ReedSolomon, Error>

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

Returns Error::TooFewDataShards if data_shards == 0.

Returns Error::TooFewParityShards if parity_shards == 0.

Returns Error::TooManyShards if data_shards + parity_shards > 256.

pub fn with_pparam(
    data_shards: usize,
    parity_shards: usize,
    pparam: ParallelParam
) -> Result<ReedSolomon, Error>

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

If pparam.bytes_per_encode == 0, it will be set to 1.

Returns Error::TooFewDataShards if data_shards == 0.

Returns Error::TooFewParityShards if parity_shards == 0.

Returns Error::TooManyShards if data_shards + parity_shards > 256.

pub fn data_shard_count(&self) -> usize

pub fn parity_shard_count(&self) -> usize

pub fn total_shard_count(&self) -> usize

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

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

Constructs the parity shards.

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

pub 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.

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

Checks if the parity shards are correct.

This is a wrapper of verify_shards_with_buffer.

pub fn verify_shards_with_buffer(
    &self,
    shards: &[Shard],
    buffer: &mut [Shard]
) -> Result<bool, Error>

Checks if the parity shards are correct.

This is a wrapper of verify_with_buffer.

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

Checks if the parity shards are correct.

This is a wrapper of verify_with_buffer.

pub fn verify_with_buffer(
    &self,
    slices: &[&[u8]],
    buffer: &mut [&mut [u8]]
) -> Result<bool, Error>

Checks if the parity shards are correct.

pub 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.

pub 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.

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

Reconstructs all shards.

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

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

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

Reconstructs only the data shards.

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

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

Trait Implementations

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<ReedSolomon> for ReedSolomon

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

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Debug for ReedSolomon

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

Formats the value using the given formatter.