# class decoder¶

Scope: kodo_rlnc

In header: #include <decoder.hpp>

## Brief description¶

A complete RLNC decoder including a Payload API.

## Member types (public)¶

 class factory

## Description¶

This decoder provides the following features:

• Linear block decoder using Gauss-Jordan elimination.
• Recoding functionality using the previously received symbols
• Support for multiple coding vector formats: this stack uses the payload_reader which specifies the possible formats.

## Member Function Description¶

uint32_t block_size ()

Returns:
the block size i.e. the total size in bytes that this coder operates on. Users may use the bytes_used() function provided in the symbol storage layers to see how many of those bytes are then used.

uint32_t bytes_used ()

Returns:
the number of bytes used

uint32_t coefficient_vector_size ()

Returns:
The number of bytes needed to store the symbol coefficients.

void generate (uint8_t * coefficients)

Fills the input buffer with symbol coefficients used for either encoding or decoding a symbol.

Parameter coefficients:
Pointer to the memory where the coefficients should be stored. The coefficient buffer should have at least layer::coefficient_vector_size() capacity.

void generate_partial (uint8_t * coefficients)

The generate partial function must only generate non-zero symbol coefficients for symbols which have been set in the Symbol Storage Layer. The primary use-case for generate_partial(uint8_t*) is to allow encoding to start prior to having all original source symbols available. Fills the input buffer with symbol coefficients used for either encoding or decoding a symbol.

Parameter coefficients:
Pointer to the memory where the coefficients should be stored. The coefficient buffer should have at least layer::coefficient_vector_size() capacity.

bool has_generate ()

Returns whether the coder implements generate() .

Returns:
True if the function is available otherwise false

bool has_generate_partial ()

Returns whether the coder implements generate_partial() .

Returns:
True if the function is available otherwise false

bool has_is_partially_complete ()

Returns whether the coder implements is_partially_complete() .

Returns:
True if the function is available otherwise false

Returns whether the coder implements read_payloads() .

Returns:
True if the function is available otherwise false

Returns whether the coder implements read_symbols() .

Returns:
True if the function is available otherwise false

bool has_remote_rank ()

Returns whether the coder implements remote_rank() .

Returns:
True if the function is available otherwise false

bool has_set_seed ()

Returns whether the coder implements set_seed() .

Returns:
True if the function is available otherwise false

bool has_symbol_decoding_status_updater ()

Returns whether the coder has a symbol_decoding_status_updater which can be used to accurately track the status of each symbol during the decoding process (this can impact the performance).

Returns:
True if the function is available otherwise false

bool has_trace_support ()

Returns whether the coder has support for tracing.

Returns:
True if tracing is available otherwise false

Returns whether the coder implements write_payload() .

Returns:
True if the function is available otherwise false

uint32_t id_size ()

Can be reimplemented by a Symbol ID layer.

Returns:
the size in bytes required for the symbol id buffer.

void initialize (factory & the_factory)

Initializes the coder and ensures the object is in a clean state. A coder may be initialized many times.

Parameter the_factory:
The factory used to build the codec layer. Provides access to cached data and factory functions.

bool is_complete ()

Check whether decoding is complete. This happens when the decoding matrix has full rank.

Returns:
true if decoding is complete.

bool is_every_symbol_initialized ()

Returns:
True if all symbols in the storage layer are initialized. Initialized means that a symbol’s memory is available and has been explicitly set by the user through a layer::set_const_symbol() , layer::set_const_symbols() , layer::set_mutable_symbol() or layer::set_mutable_symbols() call. Any symbol which is initialized is also available.

bool is_partially_complete ()

Check if some symbols in the decoder are fully decoded even though the full data block has not been sent.

Returns:
True if the decoding matrix should be partially decoded.

bool is_status_updater_enabled ()

Returns:
True if the status updater is enabled, otherwise false.

bool is_symbol_initialized (uint32_t index)

Parameter index:
The index of the symbol to check
Returns:
True if the specific symbol is initialized. Initialized means that a symbol’s memory is available and it has been explicitly set by layer::set_const_symbol() , layer::set_const_symbols() , layer::set_mutable_symbol() or layer::set_mutable_symbols() . Any symbol which is initialized is also available.

bool is_symbol_missing (uint32_t index)

Parameter index:
Index of the symbol whose state should be checked.
Returns:
True if the symbol is missing otherwise false.

bool is_symbol_partially_decoded (uint32_t index)

Parameter index:
Index of the symbol whose state should be checked.
Returns:
True if the symbol has been partially decoded otherwise false.

bool is_symbol_pivot (uint32_t index)

The symbol pivot indicates whether a symbol is present in the encoding/decoding matrix (it could be partially or fully decoded). A coefficient generator may use this information when generating coding coefficients.

Returns:
True if the symbol is available.

bool is_symbol_uncoded (uint32_t index)

Returns whether the symbol is uncoded or not. This may return false for symbols that are actually uncoded - but never true for symbols that are not uncoded. As with the layer::symbols_uncoded() function the reason for this is that some algorithms do not, for performance reasons, keep track of the exact status of the decoding matrix.

Parameter index:
Index of the symbol to check.
Returns:
True if the symbol is uncoded, and otherwise false.

bool is_trace_enabled ()

Returns whether a tracing is enabled for the coder.

Returns:
True if tracing is enabled otherwise false

uint8_t * mutable_symbol (uint32_t index)

Parameter index:
the index number of the symbol
Returns:
Returns a pointer to the symbol data. The size of the symbol data is provided by the symbol_size() function.

Returns:
the required payload buffer size in bytes

uint32_t rank ()

The rank of an encoder states how many symbols are available for encoding. The rank of a decoder indicates how many symbols have been partially or fully decoded. This number is also equivalent to the number of pivot elements we have in the decoding matrix.

Returns:
the rank of the encoder/decoder

void read_id (uint8_t * symbol_id, uint8_t ** coefficients)

Can be reimplemented by a Symbol ID layer.

Parameter symbol_id:
Contains the symbol id for an encoded symbol.
Parameter coefficients:
Pointer to pointer of the symbol coefficients. After the call to read_id the coefficients pointer will point to memory storing all coding coefficients corresponding to the symbol id read from the symbol_id buffer. Note, the buffer returned may be change by the calling code. The implementation should therefore ensure that this will not cause problems e.g. by returning a pointer to a internal buffered copy of the coefficients.

Reads an encoded symbol stored in the payload buffer.

Parameter payload:
The buffer storing the payload of an encoded symbol. The payload buffer may be changed by this function, so it cannot be reused. If the payload is needed multiple times, then make sure to keep a copy of the original payload.

Reads multiple payloads that are stored in the provided buffers. These buffers should have a size of layer::payload_size() bytes. The decoder state is only modified if full decoding is possible with the provided payloads. This function cannot be called if the decoder has any partially decoded symbols in the decoding matrix. But the decoder may have previously defined uncoded symbols that will be used by read_payloads during the decoding process. The underlying implementation is optimized for processing a small number of larger symbols, which is typical in a storage scenario. Consequently, this function should not be used in network scenarios where the symbol size is only a few kilobytes. For the binary8 field, the symbol size should be a multiple of 32 bytes, because the underlying SIMD optimizations operate on data chunks of that size.

Parameter payloads:
Array of pointers to the payload buffers. These buffers will not be changed during decoding, so it is safe to use them multiple times.
Parameter payload_count:
The number of payloads that should be processed.
Returns:
true if full decoding was possible with the provided payloads

void read_symbol (uint8_t * symbol_data, uint8_t * coefficients)

Decodes an encoded symbol according to the coding coefficients.

Both buffers may be modified during this call. The reason for this is that the decoder will directly operate on the provided memory for performance reasons.

Parameter symbol_data:
Buffer representing an encoded symbol.
Parameter coefficients:
The coding coefficients used to create the encoded symbol

bool read_symbols (uint8_t ** coded_symbols, uint8_t ** constants, uint32_t symbol_count)

Decodes several coded symbols according to the provided coding coefficients. The decoder state is only modified if full decoding is possible with the provided symbols. This function cannot be called if the decoder has any partially decoded symbols in the decoding matrix. But the decoder may have previously defined uncoded symbols that will be used by read_symbols during the decoding process. The underlying implementation is optimized for processing a small number of larger symbols, which is typical in a storage scenario. Consequently, this function should not be used in network scenarios where the symbol size is only a few kilobytes. For the binary8 field, the symbol size should be a multiple of 32 bytes, because the underlying SIMD optimizations operate on data chunks of that size.

Parameter coded_symbols:
Array of pointers to the coded symbol buffers. The size of each buffer should be symbol_size() . These buffers will not be changed during decoding, so it is safe to use them multiple times.
Parameter constants:
Array of pointers to the rows of coding coefficients. The size of each buffer should be coefficient_vector_size() .
Parameter symbol_count:
The number of symbols that should be processed.
Returns:
true if full decoding was possible with the provided symbols

void read_uncoded_symbol (uint8_t * symbol_data, uint32_t index)

The decode function for systematic symbols, i.e. a specific uncoded symbols.

Parameter symbol_data:
Buffer containing the systematic symbol’s data.
Parameter index:
The index of the systematic symbol in the decoding matrix.

uint32_t remote_rank ()

Returns:
The rank of the “remote” entity e.g. a decoder

void set_bytes_used (uint32_t bytes_used)

Sets the number of bytes used

Parameter bytes_used:
number of bytes used of the total coders block size

void set_is_complete_callback (const std::function< void()> & callback)

Sets the callback to be invoked once decoding is complete

Parameter callback:
The callback that we should invoke when layer::is_complete() changes state to true

void set_mutable_symbol (uint32_t index, const storage::mutable_storage & symbol)

Sets the data storage for a mutable symbol.

Parameter index:
the index of the symbol in the coding block
Parameter symbol:
the actual data of that symbol

void set_mutable_symbols (const storage::mutable_storage & symbol_storage)

Sets the storage for the source symbols. This will specify all symbols also in the case of partial data. If this is not desired then the symbols should be specified individually. This also means that it is the responsibility of the user to communicate how many of the bytes transmitted are application data.

Parameter symbol_storage:
A storage::mutable_storage container initialized with the buffer to be use as encoding / decoding buffer.

void set_seed (uint32_t seed_value)

Set the seed of the coefficient generator used. Note that not all generators provide the set_seed() function. E.g. a layer using a Vandermonde matrix as source for the symbol coefficients will not implement the set_seed() function.

Parameter seed_value:
The seed value for the generator.

void set_status_updater_off ()

Disables the status updater

void set_status_updater_on ()

Enable the status updater so that a full update is performed every time a symbol is read.

void set_symbol_uncoded (uint32_t index)

Specifies that the decoder has fully decoded a specific symbol.

Parameter index:
Index of the symbol whose state should be changed.

void set_trace_callback (const kodo_core::trace_callback_function & callback)

Enables tracing in a stack. trace_callback for more information about the callback signature.

Parameter callback:
The function callback where the tracing information will be delivered. As a user you specify the callback if you want to have control over the tracing output.

void set_trace_off ()

Disables tracing in a stack.

void set_trace_stdout ()

Enables tracing in a stack. The output will be written to standard out.

void set_zone_prefix (const std::string & zone_prefix)

Sets a zone prefix for the tracing output. The zone prefix will be appended to all the output. This makes it possible to have two stacks that both trace to standard out, but still differentiate the output.

Parameter zone_prefix:
The zone prefix to append to all tracing zones

uint32_t symbol_size ()

Returns:
the symbol size of a symbol in bytes

uint32_t symbols ()

Returns:
the number of symbols in this block coder

uint32_t symbols_initialized ()

Returns:
The number of symbols that are initialized. Initialized means that a symbols memory is available and has been explicitly set by the user through a layer::set_const_symbol() , layer::set_const_symbols() , layer::set_mutable_symbol() or layer::set_mutable_symbols() call. Any symbol which is initialized is also available.

uint32_t symbols_missing ()

Returns:
The number of missing symbols at the decoder

uint32_t symbols_partially_decoded ()

Returns:
The number of partially decoded symbols at the decoder

uint32_t symbols_uncoded ()

Returns the number of uncoded symbols currently known. Depending on the algorithm used the true number of uncoded symbols may be higher. The reason for this uncertainty is that some algorithms do not keep track of the exact status of the decoding matrix for performance reasons. It is however guaranteed that at least this amount of uncoded symbols exists.

Returns:
The number of uncoded symbols at the decoder

void update_symbol_status ()

Performs a more thorough update of the symbols’ status

Writes the payload representing a single encoded symbol into the provided buffer. The exact content and structure of the payload depends on the codec used. The provided buffer should have a size of at least layer::payload_size() bytes. This is guaranteed to be enough for the specific configuration used for the codec, e.g. the number of symbols and the size of a symbol. However, since many codecs use variable-size encoding, i.e. using less bytes to represent the headers of a systematic symbol, we will return the actual number of bytes used. So that the application can avoid transmitting/storing more data than actually needed.

Parameter payload:
The buffer where the payload should be written.
Returns:
the total bytes used from the payload buffer

# class factory¶

Scope: kodo_rlnc::decoder

In header: #include <decoder.hpp>

## Brief description¶

Factory class that is needed to instantiate a decoder.

## Member types (public)¶

 using pointer

## Member functions (public)¶

 factory (fifi::api::field field, uint32_t symbols, uint32_t symbol_size) pointer build () void set_coding_vector_format (kodo_rlnc::coding_vector_format format) void set_field (fifi::api::field field) void set_symbol_size (uint32_t symbol_size) void set_symbols (uint32_t symbols) uint32_t symbol_size () const uint32_t symbols () const

## Member Function Description¶

factory (fifi::api::field field, uint32_t symbols, uint32_t symbol_size)

Factory base constructor.

Parameter field:
the chosen finite field
Parameter symbols:
the number of symbols in the coding block
Parameter symbol_size:
the size of a symbol in bytes

pointer build ()

Builds the actual coder.

Returns:
pointer to an instantiation of an encoder or decoder

void set_coding_vector_format (kodo_rlnc::coding_vector_format format)

Set the coding vector format

Parameter format:
The selected coding vector format

void set_field (fifi::api::field field)

Sets the finite field

Parameter field:
the selected field type

void set_symbol_size (uint32_t symbol_size)

Sets the symbol size

Parameter symbol_size:
the symbol size

void set_symbols (uint32_t symbols)

Sets the number of symbols

Parameter symbols:
the number of symbols

uint32_t symbol_size ()

Returns:
the symbol size in bytes

uint32_t symbols ()

Returns:
the number of symbols in a block

## Type Description¶

using pointer = std::shared_ptr
Type of the pointer returned by the factory objects.