Warning: This is a development version. The latest stable version is Version 4.0.1.
Scope: rely
In header: #include <rely/encoder.hpp>
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.
Default constructor.
Copy constructor (disabled). This type is only movable.
Copy assign operator (disabled). This type is only movable.
R-value copy constructor.
R-value move assign operator.
Destructor.
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.
- Returns:
- The size of the packets in bytes that can be produced by this encoder. Specified in encoder::configure().
- Returns:
- The header size in bytes.
- Returns:
- The maximum time a symbol is held by the encoder before dropping from the encoding.
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.
- Returns:
- The maximum number of symbols that will be held by the encoder.
- Returns:
- The number of symbols that’s currently held by the encoder.
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.
- Returns:
- The configured repair interval
- Returns:
- The configured repair target
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.
Disables repair generation.
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.
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:
- True if any packets are available for writing otherwise false.
- Returns:
- The number of packets pending in the queue ready for writing. Use encoder::produce_next() to move to the next packet.
The memory of the current packet ready to be written by the encoder.
- Returns:
- The pointer to the packet
The size of the buffer returned by encoder::produce_data()
- Returns:
- The size in bytes
The timestamp of the current packet ready to be written by the encoder.
- Returns:
- The timestamp of the current packet to be produced
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(); }
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().
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().
- Returns:
- True if the encoder has symbols for which a flush is needed at some point
- 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.
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.
Disable logging.
- Returns:
- Whether the log is enabled or disabled
- Returns:
- The name of a counter as a string
- Returns:
- A specific counter value
- Returns:
- True if the counter is valid. Some counters are encoder or decoder specific.
- 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.
- Returns:
- The size of the memory backing the counter storage in bytes.
- Returns:
- All counters in json format.
Reset all the counters.
Reset specific counter.
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
- Returns:
- The counter id associated with the counter index