Warning: This is a development version. The latest stable version is Version 7.0.0.
Rely can be used in two modes:
Let’s spend a few minutes to look at both modes in more detail.
Table of Contents
In automatic repair mode we use the rely::encoder::set_repair_trigger() and related functions to drive the generation of repair symbols. Using the repair trigger we automatically will generate repair when a configurable amount of payloads have been added to Rely.
The following pseudocode highlights the basic usage:
// Enable the automatic repair generation
repair_interval = 4
repair_target = 1
// In this case 20% repair will be generated i.e. after consuming four
// source symbols one repair symbol will be generated.
encoder.set_repair_trigger(repair_interval, repair_target)
encoder.consume(payload #1)
encoder.consume(payload #2)
encoder.consume(payload #3)
encoder.consume(payload #4)
// At this point one repair symbols has been produced
It is still possible to generate additional repair using the rely::encoder::generate_repair() function. This can be useful in situations where suddenly more packet loss than expected is observed on the network and to avoid decoding failure we want to temporarily generate more repair than our repair target.
You may turn off the repair trigger by calling rely::encoder::disable_repair_trigger() if no further repair is required.
If you are using Rely in “automatic repair” mode there may be periods where you observe no losses and therefore do not require any repair generation. In this case all symbols stored in the encoder will be considered unprotected.
When switching repair on this may cause a burst of repair packets to be generated.
As an example let’s assume that repair is disabled and that the encoder contains
50 source symbols. Say we are starting to observe some losses at this point we
may want to start to generate repair e.g. 10%. This could be accomplished by
calling
rely::encoder::set_repair_trigger()
and setting repair_interval = 9
and repair_target = 1
.
However, since the encoder already contains 50 unprotected symbols Rely will
generate repair for all 50 symbols. Which means that 5 repair symbols will be
generated instead of just repair_target = 1
.
To avoid this situation you can limit the amount of repair that is generated by
specifying the repair_limit
parameter. For example setting it equal to the
repair_target
will limit the generated repair to 1 symbol.
When running in automatic mode you may have situations where symbols are added
sporadically, this may lead to situations where the repair_interval
is not
reached before a symbol is about to expire. In this case you need to use the
flush API to ensure that all symbols get the configured level of protection (see
rely::encoder::flush()).
In some situations we may experience cases where the configured timeout needs to be changed. This could be because the network latency has decreased or increased causing us to have either more or less time for Rely.
When increasing the timeout we have more time to protect the data consumed by Rely and no specific considerations are needed.
However, when decreasing the timeout we may have a situation where we suddenly have expired unprotected symbols in Rely. In general this situation can be handled by the rely::encoder::flush() mechanism, which is designed to ensure that symbols that have just expired will be protected by repair. However, when changing the timeout some symbols may be so old that providing repair for them no longer makes sense. To accommodate for this we can use the rely::encoder::catch_up() mechanism which allows us to drop symbols older than a given threshold.
In the “manual repair” mode we control the generation of repair traffic. This is done via the rely::encoder::generate_repair() function. Using this approach we can implement Content-Aware Coding coding by calling rely::encoder::generate_repair() e.g. after all payloads of a specific video frame have been added.
See the Content-Aware Coding for more details.
The default mode of a Rely encoder is “manual repair”. Unless you specify a repair trigger you will fully control when and how repair is generated.
When using “manual repair” we have to be careful to ensure that symbols receive the desired level of protection.