Warning: This is a development version. The latest stable version is Version 7.0.0.

Table Of Contents

  1. Docs
  2. API
  3. class encoder

class encoder

Scope: rely

In header: #include <rely/encoder.hpp>

Brief description

The Rely encoder. The encoder consumes payloads and produces packets which can be used to reconstruct the original payload with the rely::decoder. A timeout is used to determine when a payload is deemed too old and therefore needs to be excluded from the stream.

Member functions (public)

  encoder ()
  encoder (const encoder & other)
encoder & operator= (const encoder & other)
  encoder (encoder && other)
encoder & operator= (encoder && other)
  ~encoder ()
void configure (std::size_t max_packet_bytes, int64_t timeout, std::size_t max_stream_size)
std::size_t max_packet_bytes () const
std::size_t header_bytes () const
int64_t timeout () const
void set_timeout (int64_t timeout)
std::size_t max_stream_size () const
std::size_t stream_size () const
void set_repair_trigger (std::size_t repair_interval, std::size_t repair_target, std::size_t repair_limit = 0)
std::size_t repair_trigger_interval () const
std::size_t repair_trigger_target () const
double repair_trigger_rate () const
void disable_repair_trigger ()
bool is_repair_trigger_disabled () const
bool has_unprotected_symbols () const
std::size_t unprotected_symbols () const
void generate_repair (std::size_t count)
void flush_repair ()
std::size_t consume (const uint8_t * payload, std::size_t bytes, int64_t now)
bool can_produce () const
std::size_t produce_queue_size () const
const uint8_t * produce_data () const
std::size_t produce_bytes () const
int64_t produce_timestamp () const
void produce_next ()
void flush (int64_t now)
void catch_up (int64_t now)
bool has_upcoming_flush () const
int64_t upcoming_flush (int64_t now) const
void set_flush_threshold (int64_t threshold)
int64_t flush_threshold () const
void enable_log (log_callback callback, void * user_data = nullptr)
void disable_log ()
bool is_log_enabled () const
std::string counter_name (counter id) const
uint64_t counter_value (counter id) const
bool counter_is_valid (counter id) const
const uint8_t * counters_data () const
std::size_t counters_size () const
std::string counters_to_json () const
void reset_counters ()
void reset_counter (counter id)
std::size_t counters () const
counter counter_id (std::size_t index) const

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 configure (std::size_t max_packet_bytes, int64_t timeout, std::size_t max_stream_size)

Configure the encoder. Note, that if called on an existing encoder this will reset the internal state.

Parameter max_packet_bytes:
The maximum size of the packets in bytes that can be produced by this encoder. This parameter can be adjusted according to the network path MTU (Maximum Transfer Unit).
Parameter timeout:
The maximum time a packet is held by the encoder before it’s removed from the encoding. The unit of this value must match the value provided for the “now” parameters. E.g. the if the timeout is given in milliseconds, so must the now parameter for, e.g., the encoder::consume() member function.
Parameter max_stream_size:
The maximum number of packets that will be held by the encoder. This effectively limits the maximum memory consumption of the algorithm. In practice it makes sense to maximize this parameter as much as possible. If symbols are removed due to a full stream rather than a timeout, useful payloads may be dropped.
auto max_packet_bytes () const -> std::size_t
Returns:
The size of the packets in bytes that can be produced by this encoder. Specified in encoder::configure().
auto header_bytes () const -> std::size_t
Returns:
The header size in bytes.
auto timeout () const -> int64_t
Returns:
The maximum time a symbol is held by the encoder before dropping from the encoding.
void set_timeout (int64_t timeout)

Set the time a source symbol is held by the encoder before being dropped from the encoding.

This function should be used if the latency budget changes. For best performance, minor changes in the latency should be accounted for as jitter. See Timeout Configuration for more information on how to pick the right timeout.

Note

Setting the timeout to a lower value will cause an upcoming flush to happen sooner. It might even cause a flush to be late, i.e., make encoder::upcoming_flush() return a negative value. Depending on the application this can be problematic, encoder::catch_up() can be used to drop symbols that are expired.

Parameter timeout:
The time a symbol is held by the encoder. The unit of this value must be consistent with the other time parameters in this API.
auto max_stream_size () const -> std::size_t
Returns:
The maximum number of symbols that will be held by the encoder.
auto stream_size () const -> std::size_t
Returns:
The number of symbols that’s currently held by the encoder.
void set_repair_trigger (std::size_t repair_interval, std::size_t repair_target, std::size_t repair_limit = 0)

Enables repair trigger for the encoder.

Parameter repair_interval:
The number of symbols to consume before entering a repair phase where repair is produced.
Parameter repair_target:
The number of repair symbols to produce in each repair phase.
Parameter repair_limit:
Limits the number of repair symbols that may be produced when enabeling the repair trigger. This may be used in cases where repair has been disabled i.e. the encoder may contain a large number of unprotected symbols. In this case we may want to avoid a sudden burst of repair packets when setting the repair trigger. If repair_limit = 0 no limit is enforced.
auto repair_trigger_interval () const -> std::size_t
Returns:
The configured repair trigger interval
auto repair_trigger_target () const -> std::size_t
Returns:
The configured repair trigger target
auto repair_trigger_rate () const -> double

The repair rate is calculated as:

rapair_rate = repair_target / (repair_interval + repair_target)

As an example if the rapair rate is 0.2 it means that 20% of the packets produced by the encoder will contain repair symbols. Consequently the stream can withstand up to 20% packet loss.

Returns:
The repair rate based on the interval and target. The repair rate is a number between 0 and 1 which specified the ratio of repair symbols to source symbols.
void disable_repair_trigger ()
Disables repair generation.
auto is_repair_trigger_disabled () const -> bool

Returns whether the repair trigger is enabled or not.

Returns:
true if repair trigger is enabled otherwise false.
auto has_unprotected_symbols () const -> bool

Returns whether the stream contains unprotected source symbols or not.

Returns:
true if the stream contains unprotected source symbols otherwise false.
auto unprotected_symbols () const -> std::size_t

Returns the number of unprotected source symbols currently in the stream.

Returns:
the number of unprotected source symbols currently in the stream.
void generate_repair (std::size_t count)

This member function provides an alternative to the repair trigger API. It simply generates the given number of repair packets based on the source symbols currently in the stream.

This function is typically used to ensure repair is generated after consuming a payload. See Content-Aware Coding for more information.

This function can be used with the repair trigger API both disabled or enabled. It will not affect the protected state of individual symbols. So encoder::has_unprotected_symbols() and encoder::unprotected_symbols() will have the same return value before and after invoking this function.

Parameter count:
The number of repair packets to generate.
void flush_repair ()

Force the encoder generate repair for all unprotected source symbols currently in the stream.

If repair is disabled or if no symbols are unprotected i.e. if repair has already been generated this function will have no effect.

This function is typically used to ensure timely repair is generated see Content-Aware Coding for more information.

If unprotected sources symbols exist the amount of generated repair will depend on the chosen repair rate and the number of unprotected source symbols.

auto consume (const uint8_t * payload, std::size_t bytes, int64_t now) -> std::size_t

Consume a payload. The consumed payload is copied to the encoder, so there’s no need for the calling code to manage the life time of the given payload.

Parameter payload:
Pointer to the payload
Parameter bytes:
The number of bytes stored in the payload
Parameter now:
The the current time. The unit must match the unit of the timeout parameter provided in encoder::configure().
Returns:
The number of source symbols consumed by the encoder. A single payload may be split into multiple source symbols in case of fragmentation to respect the max_packet bytes passed to encoder::configure()
auto can_produce () const -> bool
Returns:
True if any packets are available for writing otherwise false.
auto produce_queue_size () const -> std::size_t
Returns:
The number of packets pending in the queue ready for writing. Use encoder::produce_next() to move to the next packet.
auto produce_data () const -> const uint8_t *

The memory of the current packet ready to be written by the encoder.

Returns:
The pointer to the packet
auto produce_bytes () const -> std::size_t

The size of the buffer returned by encoder::produce_data()

Returns:
The size in bytes
auto produce_timestamp () const -> int64_t

The timestamp of the current packet ready to be written by the encoder.

Returns:
The timestamp of the current packet to be produced
void produce_next ()

Advance the encoder to move to the next packet. The following sample code illustrates how to “drain” the encoder for pending packets.

while(encoder.can_produce())
{
    socket.write(encoder.produce_data(), encoder.produce_bytes());
    encoder.produce_next();
}
void flush (int64_t now)

Flush expired symbols.

If payloads are added at a constant pace to the encoder flushing may not be needed. However, if the flow of traffic into the encoder is choppy it is possible that symbols added to the encoder will not have their repair_target satisfied before expiring. That is without the use of the flush member function. When calling flush, repair is scheduled for the expired symbols such that proper protection against packet loss is ensured.

If encoder::has_upcoming_flush() returns true it means that not all symbols in the encoder has been protected, i.e, the encoder still has an obligation to generate repair for symbols in the stream. You can query when a flush should take place using the encoder::upcoming_flush() function. Note, that a pending flush may be canceled if additional symbols are added to the encoder since this may trigger a repair phase. You should therefore check whether a flush is still pending after consuming payloads.

Parameter now:
The the current time. The unit must match the unit of the timeout parameter provided in encoder::configure().
void catch_up (int64_t now)

Drops expired symbols. Note, unlike encoder::flush(), repair will not be generated for the the expired symbols. This can be used, e.g., if encoder::upcoming_flush() returns a negative value smaller than some application specific threshold.

Parameter now:
The the current time. The unit must match the unit of the timeout parameter provided in encoder::configure().
auto has_upcoming_flush () const -> bool
Returns:
True if the encoder has symbols for which a flush is needed at some point
auto upcoming_flush (int64_t now) const -> int64_t
Parameter now:
The the current time. The unit must match the unit of the timeout parameter provided in encoder::configure().
Returns:
The time until the next flush should be performed. Can be negative.
void set_flush_threshold (int64_t threshold)
Parameter threshold:
Set the current flush threshold. The flush threshold is used to trigger flush before symbols expire. This can be used to handle jitter between an encoder and decoder. See Taking Jitter Into Account for more information.
auto flush_threshold () const -> int64_t
Returns:
The current flush threshold.
void enable_log (log_callback callback, void * user_data = nullptr)

Enable logging for the encoder

Parameter callback:
The callback used for handling log messages.
Parameter user_data:
A pointer to user_data, this can be useful for binding state into the callback. If not needed simply use nullptr.
void disable_log ()
Disable logging.
auto is_log_enabled () const -> bool
Returns:
Whether the log is enabled or disabled
auto counter_name (counter id) const -> std::string
Returns:
The name of a counter as a string
auto counter_value (counter id) const -> uint64_t
Returns:
A specific counter value
auto counter_is_valid (counter id) const -> bool
Returns:
True if the counter is valid. Some counters are encoder or decoder specific.
auto counters_data () const -> const uint8_t *
Returns:
The memory backing the counter storage. See the Performance Counters section in the documentation to find a description of th memory layout of the counters.
auto counters_size () const -> std::size_t
Returns:
The size of the memory backing the counter storage in bytes.
auto counters_to_json () const -> std::string
Returns:
All counters in json format.
void reset_counters ()
Reset all the counters.
void reset_counter (counter id)
Reset specific counter.
auto counters () const -> std::size_t

Returns the number of counters available. Can be used in a loop to extract all valid counters:

for(std::size_t i = 0; i < encoder.counters(); ++i)
{
    rely::counter id = encoder.counter_id(i);

    if (encoder.counter_is_valid(id))
    {
        std::cout << encoder.counter_name(id) << "\n";
        std::cout << encoder.counter_value(id) << "\n";
    }
}
Returns:
The number of counters
auto counter_id (std::size_t index) const -> counter
Returns:
The counter id associated with the counter index
API
class decoder
© Copyright 2019, Steinwurf. Created using Sphinx.
Versions
7.0.0
6.1.0
6.0.0
5.0.0
4.0.1
4.0.0
3.0.2
3.0.1
3.0.0
2.0.0
Development
latest