Module wirerlhair

Fountain code-based erasure encoder for error correction.

Description

Fountain code-based erasure encoder for error correction.

Wirehair produces a stream of error correction blocks from a data source using an erasure code. When enough of these blocks are received, the original data can be recovered.

As compared to other similar libraries, an unlimited number of error correction blocks can be produced, and much larger block counts are supported. Furthermore, it gets slower as O(N) in the amount of input data rather than O(N Log N) like the Leopard block code or O(N^2) like the Fecal fountain code, so it is well-suited for large data.

This is not an ideal MDS code, so sometimes it will fail to recover N original data packets from N symbol packets. It may take N + 1 or N + 2 or more. On average it takes about N + 0.02 packets to recover. Overall the overhead from the code inefficiency is low, compared to LDPC and many other fountain codes.

https://github.com/catid/wirehair

Data Types

block_id()

block_id() = integer()

The ID number of a block, given as a zero-based positive integer.

block_size()

block_size() = bytes()

The size of each block in bytes.

bytes()

bytes() = integer()

decoder()

abstract datatype: decoder()

encoder()

abstract datatype: encoder()

error()

error() = {error, reason()}

msg()

msg() = iolist()

A message being encoded or decoded.

msg_size()

msg_size() = bytes()

The size of a message in bytes.

reason()

reason() = invalid_input | bad_dense_seed | bad_peel_seed | msg_too_small | too_many_blocks | extra_insufficient | wirehair_generic | out_of_memory | unsupported_platform | unknown | wirehair_encoder_create | wirehair_decoder_create

Possible failure codes from Wirehair.

Function Index

decode/3Decode a block.
encode/2Encode a block.
new_decoder/2Create a new Wirehair decoder.
new_encoder/2Create a new Wirehair encoder.
recover/1Retrieve the decoded message.

Function Details

decode/3

decode(Decoder::decoder(), BlockId::block_id(), Block::iolist()) -> more_data | ok | {error, term()}

Decode a block.

The atom more_data will be returned until sufficient blocks have been received to recover the message.

Once this function returns ok, you can use the recover/1 function to retrieve the message itself.

See also: block_id(), new_decoder/2.

encode/2

encode(Encoder::encoder(), BlockId::block_id()) -> {ok, binary()} | error()

Encode a block.

The first BlockId < N blocks are the same as the input data.

The BlockId >= N blocks are error-correction data, generated on demand.

You can generate as many parity blocks as needed by repeatedly calling this function with increasing values of BlockId.

See also: new_encoder/2.

new_decoder/2

new_decoder(MsgSize::msg_size(), BlockSize::block_size()) -> {ok, decoder()} | error()

Create a new Wirehair decoder.

The final size of the message must be known in advance, as well as the block size.

See also: block_size(), msg_size().

new_encoder/2

new_encoder(Msg::msg(), BlockSize::block_size()) -> {ok, encoder()} | error()

Create a new Wirehair encoder.

Creates a new Wirehair encoder instance for a specific message. The block size must be chosen such that at least 2 blocks are used for the message and at most 64,000. The most efficient operation is achieved at around 1000 blocks per message.

See also: block_size(), msg().

recover/1

recover(Decoder::decoder()) -> {ok, msg()} | {error, term()}

Retrieve the decoded message.

This function can only be called once decode/3 has returned ok.

See also: msg(), decode/3, new_decoder/2.


Generated by EDoc