class encoder

Scope: kodo_slide

Brief description

Implementation of a complete RLNC sliding window encoder.

Member functions (public)

  encoder ()
  encoder (const encoder & other)
encoder & operator= (const encoder & other)
  encoder (encoder && other)
encoder & operator= (encoder && other)
  ~encoder ()
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
std::size_t push_front_symbol (const uint8_t * symbol, std::size_t symbol_size)
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)
std::size_t max_write_size () const
std::size_t write_symbol (uint8_t * symbol, const uint8_t * coefficients)
std::size_t write_source_symbol (uint8_t * symbol, std::size_t index)
void set_log_stdout ()
void set_zone_prefix (const std::string & zone_prefix)

Member Function Descriptions

encoder ()
Default constructor.

encoder (const encoder & other)
Copy constructor (disabled). This type is only movable.

encoder & operator= (const encoder & other)
Copy assign operator (disabled). This type is only movable.

encoder (encoder && other)
R-value copy constructor.

encoder & operator= (encoder && other)
R-value move assign operator.

~encoder ()
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 encoder 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 the 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 maximum 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 available in memory at the encoder. The number of symbols in the coding window MUST be less than or equal to this number. The total range of valid symbol indices 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 encoder::stream_symbols() == 0.

std::size_t stream_lower_bound () const
Returns:
The index of the oldest symbol known by the encoder. 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 [ encoder::stream_lower_bound(), encoder::stream_upper_bound() ). Note the stream is a half-open interval. Going from encoder::stream_lower_bound() to encoder::stream_upper_bound() - 1.

std::size_t push_front_symbol (const uint8_t * symbol, std::size_t symbol_size)

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

This does not move the encoder’s window. So if you want to include this new symbol in the encoding you should update the window also:

encoder.set_window(encoder.stream_lower_bound(),
                   encoder.stream_symbols());
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.
Parameter symbol_size:
the size of a symbol in bytes
Returns:
The stream index of the symbol being added.

std::size_t pop_back_symbol ()

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

This does not update the encoder’s window. So you need to make sure the symbol is not longer included in any encodings e.g.:

encoder.set_window(encoder.stream_lower_bound(),
                   encoder.stream_symbols());
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 [ encoder::window_lower_bound(), encoder::window_upper_bound() ). Note the window is a half-open interval. Going from encoder::window_lower_bound() to encoder::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 encoding. 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 encoder::set_seed (…) and encoder::generate (…).

void set_seed (uint64_t seed_value)

Seed the internal random generator function. If using the same seed on the encoder 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 encoder::set_seed (…)).

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

std::size_t max_write_size () const
Returns:
The maximum size of an encoded symbol in bytes

std::size_t write_symbol (uint8_t * symbol, const uint8_t * coefficients)

Write an encoded symbol according to the coding coefficients.

Parameter symbol:
The buffer where the encoded symbol will be stored. The symbol buffer must be encoder::max_symbol_size() large.
Parameter coefficients:
The coding coefficients. These must have the memory layout required (see README.rst). A compatible format can be created using encoder::generate (…)
Returns:
The size of the output symbol in bytes i.e. the number of bytes used from the symbol buffer.

std::size_t write_source_symbol (uint8_t * symbol, std::size_t index)

Write a source symbol to the symbol buffer.

Parameter symbol:
The buffer where the source symbol will be stored. The symbol buffer must be encoder::max_symbol_size() large.
Parameter index:
The symbol index which should be written.
Returns:
The size of the output symbol in bytes i.e. the number of bytes used from the symbol buffer.

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