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

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 (uint64_t repair_interval, uint64_t repair_target)
uint64_t repair_interval () const
uint64_t repair_target () const
double repair_rate () const
void disable_repair ()
void flush_repair ()
void 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 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 dropping or releasing it to the application. 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 (uint64_t repair_interval, uint64_t repair_target)

Enables repair 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.
auto repair_interval () const -> uint64_t
Returns:
The configured repair interval
auto repair_target () const -> uint64_t
Returns:
The configured repair target
auto repair_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 is protected against 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 ()
Disables repair generation.
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 sourc symbols.

void consume (const uint8_t * payload, std::size_t bytes, int64_t now)

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().
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 by repair. 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 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
4.0.1
4.0.0
3.0.2
3.0.1
3.0.0
2.0.0
Development
latest