class decoder

Scope: kodo_fulcrum

In header: #include <decoder.hpp>

Brief description

The fulcrum combined decoder tries to decode as much as possible in the inner code before passing symbols to the outer code.

Member types (public)

class factory

Member functions (public)

uint32_t block_size () const
uint32_t bytes_used () const
uint32_t expansion () const
bool has_trace_support () const
void initialize (factory & the_factory)
uint32_t inner_symbols () const
bool is_complete () const
bool is_every_symbol_initialized () const
bool is_symbol_initialized (uint32_t index) const
bool is_symbol_missing (uint32_t index) const
bool is_symbol_partially_decoded (uint32_t index) const
bool is_symbol_pivot (uint32_t index) const
bool is_symbol_uncoded (uint32_t index) const
bool is_trace_enabled () const
uint8_t * mutable_symbol (uint32_t index) const
uint32_t payload_size () const
uint32_t rank () const
void read_payload (uint8_t * payload)
void set_bytes_used (uint32_t bytes_used)
void set_is_complete_callback (const std::function< void()> & callback)
void set_mutable_symbol (uint32_t index, const storage::mutable_storage & symbol)
void set_mutable_symbols (const storage::mutable_storage & symbol_storage)
void set_symbol_uncoded (uint32_t index)
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 symbols_missing () const
uint32_t symbols_partially_decoded () const
uint32_t symbols_uncoded () const

Description

The main component of the combined decoder is implemented in the fulcrum_two_stage_decoder layer. Which implements decoding in the inner code, as soon as a full decoding is deemed possible symbols are taken from the fulcrum_two_stage_decoder and passed to the main decoder (which decodes in the outer code). For a detailed description of the fulcrum codec see the following paper on arxiv: by Lucani et. al.

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

Returns:
The expansion factor used. The expansion factor denotes the number of additional symbols created by the outer code.

bool has_trace_support ()

Returns whether the coder has support for tracing.

Returns:
True if tracing is available otherwise false

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.

uint32_t inner_symbols ()

Returns:
the number of symbols in the inner code

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

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 read_payload (uint8_t * payload)

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.

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_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

class factory

Scope: kodo_fulcrum::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 ()
uint32_t expansion () const
void set_expansion (uint32_t expansion)
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

uint32_t expansion ()

Returns:
The expansion factor used. The expansion factor denotes the number of additional symbols created by the outer code.

void set_expansion (uint32_t expansion)

Sets the number of expansion symbols

Parameter expansion:
The number of expansion symbols to use

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.