class encoder

Scope: kodo_rlnc

In header: #include <encoder.hpp>

Brief description

A complete RLNC encoder including a Payload API.

Member types (public)

class factory

Member functions (public)

uint32_t block_size () const
uint32_t bytes_used () const
uint32_t coefficient_vector_size () const
const uint8_t * const_symbol (uint32_t index) const
float density () const
void generate (uint8_t * coefficients)
void generate_partial (uint8_t * coefficients)
bool has_generate () const
bool has_generate_partial () const
bool has_set_seed () const
bool has_systematic_mode () const
bool has_trace_support () const
bool has_write_payloads () const
bool has_write_symbols () const
uint32_t id_size () const
bool in_systematic_phase () const
void initialize (factory & the_factory)
bool is_every_symbol_initialized () const
bool is_symbol_initialized (uint32_t index) const
bool is_systematic_on () const
bool is_trace_enabled () const
uint32_t payload_size () const
uint32_t rank () const
void set_bytes_used (uint32_t bytes_used)
void set_const_symbol (uint32_t index, const storage::const_storage & symbol)
void set_const_symbols (const storage::const_storage & symbol_storage)
void set_density (float density)
void set_seed (uint32_t seed_value)
void set_systematic_off ()
void set_systematic_on ()
void set_trace_callback (const kodo_core::trace_callback_function & callback)
void set_trace_off ()
void set_trace_stdout ()
void set_zone_prefix (const std::string & zone_prefix)
uint32_t symbol_size () const
uint32_t symbols () const
uint32_t symbols_initialized () const
uint32_t write_id (uint8_t * symbol_id, uint8_t ** coefficients)
uint32_t write_payload (uint8_t * payload)
uint32_t write_payloads (uint8_t ** payloads, uint32_t payload_count)
uint32_t write_symbol (uint8_t * symbol_data, uint8_t * coefficients)
void write_symbols (uint8_t ** coded_symbols, uint8_t ** constants, uint32_t symbol_count)
uint32_t write_uncoded_symbol (uint8_t * symbol_data, uint32_t index)

Description

The key features of this configuration are the following:

  • Systematic encoding (uncoded symbols produced before switching to coded symbols)
  • Multiple options for the encoding vector format: this stack uses the payload_writer which specifies the possible formats.
  • By default, a seed is sent instead of the full encoding vectors, this reduces the amount of overhead per symbol.
  • Encoding vectors are generated using a random uniform generator.

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.

const uint8_t * const_symbol (uint32_t index)

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

float density ()

Returns the density of the generated coefficients.

Returns:
the density of the generator

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_set_seed ()

Returns whether the coder implements set_seed() .

Returns:
True if the function is available otherwise false

bool has_systematic_mode ()

Returns whether the encoder has a systematic mode.

Returns:
True if the systematic mode is available otherwise false

bool has_trace_support ()

Returns whether the coder has support for tracing.

Returns:
True if tracing is available otherwise false

bool has_write_payloads ()

Returns whether the coder implements write_payloads() .

Returns:
True if the function is available otherwise false

bool has_write_symbols ()

Returns whether the coder implements write_symbols() .

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.

bool in_systematic_phase ()

Returns:
true if the encoder is in the systematic phase, i.e. there is a systematic packet to send

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_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_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_systematic_on ()

Returns:
, true if the encoder is in systematic mode

bool is_trace_enabled ()

Returns whether a tracing is enabled for the coder.

Returns:
True if tracing is enabled otherwise false

uint32_t payload_size ()

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 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_const_symbol (uint32_t index, const storage::const_storage & symbol)

Sets the data storage for a const symbol.

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

void set_const_symbols (const storage::const_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::const_storage container initialized with the buffer to be use as encoding buffer.

void set_density (float density)

Sets the density of the generated coefficients

Parameter density:
coefficients density

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_systematic_off ()

Turns off systematic mode

void set_systematic_on ()

Sets the encoder in systematic mode

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 write_id (uint8_t * symbol_id, uint8_t ** coefficients)

Can be reimplemented by a Symbol ID layer.

Parameter symbol_id:
The buffer where the symbol id is written. This id should uniquely describe the coding coefficients used to generate an encoded symbol. It is therefore sufficient to transmit only the symbol id and not necessarily all coding coefficients to decoders.
Parameter coefficients:
Pointer to a pointer of coefficients. After the call to write_id the coefficients pointer will point to memory storing all coding coefficients corresponding to the symbol id written to 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.
Returns:
The number of bytes used from the symbol_id buffer.

uint32_t write_payload (uint8_t * payload)

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

uint32_t write_payloads (uint8_t ** payloads, uint32_t payload_count)

Writes multiple payloads representing multiple encoded symbols into the provided buffers. The exact content and structure of the payloads depends on the codec used. The provided buffers should have a size of at least layer::payload_size() bytes. 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
Parameter payload_count:
The number of payloads that should be written.
Returns:
the total number of payloads written

uint32_t write_symbol (uint8_t * symbol_data, uint8_t * coefficients)

Encodes a symbol according to the symbol coefficients

Parameter symbol_data:
The destination buffer for the encoded symbol
Parameter coefficients:
At this point the symbol id should be initialized with the desired coding coefficients.
Returns:
The number of bytes used.

void write_symbols (uint8_t ** coded_symbols, uint8_t ** constants, uint32_t symbol_count)

Produces multiple coded symbols according to the provided coding coefficients. The coded symbols will not contain any headers. 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() .
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 written.

uint32_t write_uncoded_symbol (uint8_t * symbol_data, uint32_t index)

Generates specific uncoded symbols, i.e. systematic packets.

Parameter symbol_data:
The destination of the uncoded source symbol.
Parameter index:
The index of this uncoded symbol in the data block.
Returns:
The number of bytes used.

class factory

Scope: kodo_rlnc::encoder

In header: #include <encoder.hpp>

Brief description

Factory class that is needed to instantiate an encoder.

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.