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
block_id() = integer()
The ID number of a block, given as a zero-based positive integer.
block_size() = bytes()
The size of each block in bytes.
bytes() = integer()
abstract datatype: decoder()
abstract datatype: encoder()
error() = {error, reason()}
msg() = iolist()
A message being encoded or decoded.
msg_size() = bytes()
The size of a message in bytes.
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.
decode/3 | Decode a block. |
encode/2 | Encode a block. |
new_decoder/2 | Create a new Wirehair decoder. |
new_encoder/2 | Create a new Wirehair encoder. |
recover/1 | Retrieve the decoded message. |
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.
ok
, you can use the recover/1
function to retrieve the message itself.
See also: block_id(), new_decoder/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.
BlockId
.
See also: new_encoder/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(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().
Retrieve the decoded message.
This function can only be called oncedecode/3
has returned
ok
.
See also: msg(), decode/3, new_decoder/2.
Generated by EDoc