class decoder¶

Scope: kodo_slide

Brief description¶

Implementation of a complete Random Linear Network coding sliding window decoder.

Member functions (public)¶

	decoder ()
	decoder (const decoder & other)
decoder &	operator= (const decoder & other)
	decoder (decoder && other)
decoder &	operator= (decoder && other)
	~decoder ()
void	reset ()
void	configure (kodo_slide::finite_field field, std::size_t max_symbol_size)
kodo_slide::finite_field	finite_field () const
std::size_t	max_symbol_size () const
std::size_t	stream_symbols () const
bool	is_stream_empty () const
std::size_t	stream_lower_bound () const
std::size_t	stream_upper_bound () const
void	set_stream_lower_bound (std::size_t stream_lower_bound)
std::size_t	push_front_symbol (uint8_t * symbol)
std::size_t	pop_back_symbol ()
std::size_t	window_symbols () const
std::size_t	window_lower_bound () const
std::size_t	window_upper_bound () const
void	set_window (std::size_t lower_bound, std::size_t symbols)
std::size_t	coefficient_vector_size () const
void	set_seed (uint64_t seed_value)
void	generate (uint8_t * coefficients)
void	read_symbol (const uint8_t * symbol, std::size_t symbol_size, uint8_t * coefficients)
void	read_source_symbol (const uint8_t * symbol, std::size_t symbol_size, std::size_t index)
std::size_t	rank () const
std::size_t	symbols_missing () const
std::size_t	symbols_partially_decoded () const
std::size_t	symbols_decoded () const
bool	is_symbol_decoded (std::size_t index) const
void	set_log_stdout ()
void	set_zone_prefix (const std::string & zone_prefix)

Member Function Descriptions¶

decoder ()

Default constructor.

decoder (const decoder & other)

Copy constructor (disabled). This type is only movable.

decoder & operator= (const decoder & other)

Copy assign operator (disabled). This type is only movable.

decoder (decoder && other)

R-value copy constructor.

decoder & operator= (decoder && other)

R-value move assign operator.

~decoder ()

Destructor.

void reset ()

Resets the coder and ensures that the object is in a clean state. A coder may be reset many times.

void configure (kodo_slide::finite_field field, std::size_t max_symbol_size)

Configures the decoder with the given parameters. This must be called before anything else. If needed configure can be called again. This is useful for reusing an existing coder. Note that a reconfiguration always implies a reset, so the coder will be in a clean state after the operation

Parameter field:
the chosen finite field

Parameter max_symbol_size:
the size of a symbol in bytes

kodo_slide::finite_field finite_field () const

Returns:
The finite field used.

std::size_t max_symbol_size () const

Returns:
The size of a symbol in the stream in bytes.

std::size_t stream_symbols () const

Returns:
The total number of symbols known at the decoder. The number of symbols in the decoding window MUST be less than or equal to this number. The total range of valid symbol indicies is
for (std::size_t i = 0; i < stream_symbols(); ++i)
{
    std::cout << i + stream_lower_bound() << "\n";
}

bool is_stream_empty () const

Returns:
Whether the stream is empty or not, i.e. that decoder::stream_symbols() == 0.

std::size_t stream_lower_bound () const

Returns:
The index of the oldest symbol known by the decoder. This symbol may not be inside the window but can be included in the window if needed.

std::size_t stream_upper_bound () const

Returns:
The upper bound of the stream. The range of valid symbol indices goes from [ decoder::stream_lower_bound(), decoder::stream_upper_bound() ). Note the stream is a half-open interval. Going from decoder::stream_lower_bound() to decoder::stream_upper_bound() - 1.

void set_stream_lower_bound (std::size_t stream_lower_bound)

Set the index of the oldest symbol known by the decoder. This must only be called on a decoder with an empty stream.

Parameter stream_lower_bound:
The new stream lower bound, the new lower bound must be larger than or equal to the prior lower bound.

std::size_t push_front_symbol (uint8_t * symbol)

Adds a new symbol to the front of the decoder. Increments the number of symbols in the stream and increases the decoder::stream_upper_bound().

Parameter symbol:
Pointer to the symbol. Note, the caller must ensure that the memory of the symbol remains valid as long as the symbol is included in the stream. The caller is responsible for freeing the memory if needed. Once the symbol is popped from the stream. The memory must be at least decoder::max_symbol_size() bytes large.

Returns:
The stream index of the symbol being added.

std::size_t pop_back_symbol ()

Remove the “oldest” symbol from the stream. Increments the decoder::stream_lower_bound().

Returns:
The index of the symbol being removed

std::size_t window_symbols () const

Returns:
The number of symbols currently in the coding window. The window must be within the bounds of the stream.

std::size_t window_lower_bound () const

Returns:
The index of the “oldest” symbol in the coding window.

std::size_t window_upper_bound () const

Returns:
The upper bound of the window. The range of valid symbol indices goes from [ decoder::window_lower_bound(), decoder::window_upper_bound() ). Note the window is a half-open interval. Going from decoder::window_lower_bound() to decoder::window_upper_bound() - 1.

void set_window (std::size_t lower_bound, std::size_t symbols)

The window represents the symbols which will be included in the next decoding. The window cannot exceed the bounds of the stream.

Example: If window_lower_bound=4 and window_symbol=3 the following symbol indices will be included 4,5,6

Parameter lower_bound:
Sets the index of the oldest symbol in the window.

Parameter symbols:
Sets number of symbols within the window.

std::size_t coefficient_vector_size () const

Returns:
The size of the coefficient vector in the current window in bytes. The number of coefficients is equal to the number of symbols in the window. The size in bits of each coefficients depends on the finite field chosen. A custom coding scheme can be implemented by generating the coding vector manually. Alternatively the built-in generator can be used. See decoder::set_seed (…) and decoder::generate (…).

void set_seed (uint64_t seed_value)

Seed the internal random generator function. If using the same seed on the decoder and decoder the exact same set of coefficients will be generated.

Parameter seed_value:
A value for the seed.

void generate (uint8_t * coefficients)

Generate coding coefficients for the symbols in the coding window according to the specified seed (see decoder::set_seed (…)).

Parameter coefficients:
Buffer where the coding coefficients should be stored. This buffer must be decoder::coefficient_vector_size() large in bytes.

void read_symbol (const uint8_t * symbol, std::size_t symbol_size, uint8_t * coefficients)

Decodes a coded 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.

Before calling this function you need to instruct the decoder how to map the coding coefficients to the stream. This is done using the decoder::set_window() function. When reading a coded symbol from the encoder, these are the typical operations performed:

Read the seed and encoding window from the incoming packet

Call the decoder::set_seed() and decoder::set_window() functions to update the state of the decoder.

Call the decoder::generate() to generate the coding coefficients

Pass the encoded symbol and the coding coefficients to the decoder::read_symbol() function.

Parameter symbol:
Buffer representing a coded symbol.

Parameter symbol_size:
the size of the symbol in bytes

Parameter coefficients:
The coding coefficients used to create the encoded symbol

void read_source_symbol (const uint8_t * symbol, std::size_t symbol_size, std::size_t index)

Add a source symbol at the decoder.

A source symbol is a unit of data originating from the source that has not been encoded.

It is not necessary to call the decoder::set_window() function before reading a source symbol. However, the symbol must be within the stream i.e. the following conditions must hold:
uint8_t* data = "... some data ...";
std::size_t index = 32; // The index of the source symbol

assert(index >= decoder.stream_lower_bound());
assert(index < decoder.stream_upper_bound());
decoder.read_source_symbol(data, index);
Parameter symbol:
Buffer containing the source symbol’s data.

Parameter symbol_size:
the size of the symbol in bytes

Parameter index:
The index of the source symbol in the stream

std::size_t rank () const

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

Returns:
The rank of the decoder

std::size_t symbols_missing () const

Returns:
The number of missing symbols in the stream.

std::size_t symbols_partially_decoded () const

Returns:
The number of partially decoded symbols in the stream.

std::size_t symbols_decoded () const

Returns:
The number of decoded symbols in the stream.

bool is_symbol_decoded (std::size_t index) const

Parameter index:
Index of the symbol to check.

Returns:
True if the symbol is decoded (i.e. it corresponds to a source symbol), and otherwise false.

void set_log_stdout ()

Enables logging 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 logging output. The zone prefix will be appended to all the output. This makes it possible to have two stacks that both log to standard out, but still differentiate the output.

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

Table Of Contents

class decoder¶

Brief description¶

Member functions (public)¶

Member Function Descriptions¶