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

Table Of Contents

  1. Docs
  2. API
  3. class decoder

class decoder

Scope: rely

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

Brief description

The Rely decoder. The Rely decoder consumes packets with symbols from the rely::encoder and produces the original payloads based on these. A timeout is used to determine when symbols are deemed too old and therefore needs to be dropped.

Member functions (public)

  decoder ()
  decoder (const decoder & other)
decoder & operator= (const decoder & other)
  decoder (decoder && other)
decoder & operator= (decoder && other)
  ~decoder ()
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 consume (const uint8_t * packet, 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

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 configure (std::size_t max_packet_bytes, int64_t timeout, std::size_t max_stream_size)
Parameter max_packet_bytes:
The maximum size of the packets in bytes that can be consumed by this decoder.
Parameter timeout:
The maximum time a symbol is held by the decoder 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 the decoder::consume() member function.
Parameter max_stream_size:
The maximum number of symbols that will be held by the decoder. 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, decodable payloads may be dropped.
auto max_packet_bytes () const -> std::size_t
Returns:
The maximum size of the packets in bytes that can be consumed by this decoder.
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 decoder before dropping or releasing it to the application.
void set_timeout (int64_t timeout)

Set the time a source symbol is held by the decoder before being dropped from the decoding.

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 decoder::upcoming_flush() return a negative value. Depending on the application this can be problematic, decoder::catch_up() can be used to drop symbols that are expired.

Parameter timeout:
The time a symbol is held by the decoder. 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 decoder.
auto stream_size () const -> std::size_t
Returns:
The number of symbols that’s currently held by the decoder.
void consume (const uint8_t * packet, std::size_t bytes, int64_t now)

Consume a packet in the decoder. The consumed packet is copied to the decoder, so there’s no need for the calling code to manage the life time of the consumed data.

Parameter packet:
Pointer to the packet
Parameter bytes:
The number of bytes stored in the packet, must be less than or equal to decoder::max_packet_bytes().
Parameter now:
The the current time. The unit must match the unit of the timeout parameter provided in decoder::configure().
auto can_produce () const -> bool
Returns:
True if any payloads are available otherwise false
auto produce_queue_size () const -> std::size_t
Returns:
The number of payloads pending in the produce queue. Use decoder::produce_next() to move to the next payload.
auto produce_data () const -> const uint8_t *

Pointer to the decoder’s decoded payload

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

The size of the payload stored at decoder::produce_data()

Returns:
The size in bytes
auto produce_timestamp () const -> int64_t
Returns:
The timestamp of the produced payload.
void produce_next ()

Advance the decoder to move to the next payload. The following sample code illustrates how to “drain” the decoder for pending payloads.

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

Flush expired symbols.

If packets are added at a constant pace, flushing may ot be needed. However, if the flow of traffic is choppy it’s possible that decoded symbols are “blocked” by one or more missing symbols. Additionally, if no more packets are added to the decoder, decoded, but blocked, symbols may still need to be released to the output queue. When flushing, expired and missing symbols are dropped and thereby allow the release of otherwise blocked symbols.

If decoder::has_upcoming_flush() returns true it means that some symbols in the decoder are blocked by missing symbols. You can query when a flush should take place using the decoder::upcoming_flush() function. Note, a pending flush may be canceled if symbols are consumed by the decoder since this may trigger the decoding of the previously missing symbols. You should therefore check whether a flush is still pending after consuming a packet.

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

Drops expired symbols. Note, unlike decoder::flush(), the expired decoded symbols are not released. This can be used, e.g., if decoder::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 decoder::configure().
auto has_upcoming_flush () const -> bool
Returns:
Whether symbols are blocked by missing symbols, and therefore may need a flush.
auto upcoming_flush (int64_t now) const -> int64_t
Parameter now:
The current time. The unit must match the unit of the timeout parameter provided in decoder::configure().
Returns:
The time until the next flush should be performed
void enable_log (log_callback callback, void * user_data = nullptr)

Enable logging for the decoder

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 :ref: 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 < decoder.counters(); ++i)
{
    rely::counter id = decoder.counter_id(i);

    if (decoder.counter_is_valid(id))
    {
        std::cout << decoder.counter_name(id) << "\n";
        std::cout << decoder.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
class encoder
function version()
© 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