Skip to content
Permalink
Browse files

Anjay 1.15.3a

Improvements:
- Documented retransmission parameters configuration in chapter
  "Retransmissions, timeouts & response caching"
  • Loading branch information...
sznaider committed Apr 5, 2019
1 parent 428ba01 commit 1ae83f49e09c16dc36cbb05161e7c3e26cdd1cd6
Showing with 179 additions and 3 deletions.
  1. +1 −1 CMakeLists.txt
  2. +178 −2 doc/sphinx/source/AdvancedTutorial/AT5.rst
@@ -15,7 +15,7 @@
cmake_minimum_required(VERSION 2.8.12)

project(anjay C)
set(ANJAY_VERSION "1.15.3" CACHE STRING "Anjay library version")
set(ANJAY_VERSION "1.15.3a" CACHE STRING "Anjay library version")
set(ANJAY_BINARY_VERSION 1.0.0)

set(ANJAY_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
@@ -13,8 +13,8 @@
See the License for the specific language governing permissions and
limitations under the License.
Retransmissions & response caching
==================================
Retransmissions, timeouts & response caching
============================================

Due to potential network instability, the need to retransmit a message
between a Client and a Server may sometimes occur. Detecting retransmissions
@@ -90,3 +90,179 @@ Limitations
responses (starting from the oldest) are **dropped** from the cache (even if
they are still considered valid in terms of mentioned ``MAX_TRANSMIT_SPAN``),
till the new response fits.


Configuring retransmissions and timeouts
----------------------------------------

Background
~~~~~~~~~~

To provide custom retransmission policy, affecting CoAP layer across
the library, one needs to set ``anjay_configuration_t::udp_tx_params``
accordingly prior library instantiation with ``anjay_new()``.

``anjay_configuration_t::udp_tx_params`` is a ``avs_coap_tx_params_t`` structure,
defined as follows:

.. code-block:: c

/** CoAP transmission params object. */
typedef struct {
/** RFC 7252: ACK_TIMEOUT */
avs_time_duration_t ack_timeout;
/** RFC 7252: ACK_RANDOM_FACTOR */
double ack_random_factor;
/** RFC 7252: MAX_RETRANSMIT */
unsigned max_retransmit;
} avs_coap_tx_params_t;

It should be noted that without any additional configuration,
Anjay uses default values as specified in the `Section 4.8 of RFC7252
<https://tools.ietf.org/html/rfc7252#section-4.8>`_:


+-----------------------+---------------+-------------------------------------------------+
| Parameter | Default value | Corresponding field in ``avs_coap_tx_params_t`` |
+=======================+===============+=================================================+
| ``ACK_TIMEOUT`` | 2 seconds | ``ack_timeout`` |
+-----------------------+---------------+-------------------------------------------------+
| ``ACK_RANDOM_FACTOR`` | 1.5 | ``ack_random_factor`` |
+-----------------------+---------------+-------------------------------------------------+
| ``MAX_RETRANSMIT`` | 4 | ``max_retransmit`` |
+-----------------------+---------------+-------------------------------------------------+


Meaning of each parameter, calculations of timeouts and the number of retransmissions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``ACK_RANDOM_FACTOR``
^^^^^^^^^^^^^^^^^^^^^

Configures the amount of random perturbation to a timeout to a response to
an initial message (``ACK_TIMEOUT``, see next subsection). Its value has to
be at least ``1.0``. The randomness is mixed in as follows:

* generate a random number ``r`` from a closed range ``[1.0, ACK_RANDOM_FACTOR]``,
* multiply the ``ACK_TIMEOUT`` by ``r`` and use it as initial timeout.

.. admonition:: Example
:class: hint

Say the library has ``ACK_TIMEOUT`` set to `16s`.

Now, if the ``ACK_RANDOM_FACTOR`` is ``1.0``, no random behavior is
introduced, because the library is forced to pick a random number from
a trivial interval ``[1.0, 1.0]``.

However, if the ``ACK_RANDOM_FACTOR`` is, say, ``1.5``, the number picked
may lie in range ``[1.0, 1.5]``, thus the actual time the library would wait
may vary between ``[16, 24]`` seconds.


``ACK_TIMEOUT``
^^^^^^^^^^^^^^^

Configures the amount of time the library shall wait for the response to the
initial confirmable message (not retransmission).

.. admonition:: Example
:class: hint

Say the library wants to send a confirmable message.

If ``ACK_TIMEOUT`` is set to, say, `10` seconds, the library sends the
message and then waits ``10 * r`` seconds (``r`` is defined as in the
above discussion about ``ACK_RANDOM_FACTOR``) for the initial response.


``MAX_RETRANSMIT``
^^^^^^^^^^^^^^^^^^

Configures the total number of retransmissions the library is allowed to
perform before giving up on message delivery.

.. admonition:: Example
:class: hint

If ``MAX_RETRANSMIT`` is set to, say, `4`, the library would send `1`
initial message + up to `4` retransmissions, accounting for up to `5`
messages in total.

If ``MAX_RETRANSMIT`` is set to `0`, no retransmission would be attempted,
and the library would give up if no response arrived after ``ACK_TIMEOUT *
r`` seconds.


Exponential back-off
^^^^^^^^^^^^^^^^^^^^

After waiting for a response for ``t`` seconds , the wait time for the next
retransmission (in the absence of response) would be ``2 * t`` seconds. In
other words, retransmissions are performed with exponential back-off.

Example configuration
~~~~~~~~~~~~~~~~~~~~~

As an example, we may configure the library as follows:

.. code-block:: c

avs_coap_tx_params_t udp_tx_params = {
// Wait at least 4 seconds for the initial response.
.ack_timeout = avs_time_duration_from_scalar(4, AVS_TIME_S),
// Do not randomize wait times for simplicity of the discussion,
// thus "at least" in the comment above should be thought of as
// "exactly".
.ack_random_factor = 1.0,
// Allow up to 4 retransmissions.
.max_retransmit = 4
};

anjay_configuration_t configuration = {
// Some other configuration ...
.udp_tx_params = &udp_tx_params
};

// Create Anjay instance with custom transmission parameters
anjay_t *anjay = anjay_new(&configuration);

The above configuration would result in the following retransmission times to a confirmable
message:

+----------+--------------+--------------------------------+----------------------------+
| Time [s] | Retry number | Wait time for the response [s] | Action by the library |
+==========+==============+================================+============================+
| 0 | 0 | 4 | send initial message |
+----------+--------------+--------------------------------+----------------------------+
| 4 | 1 | 8 | 1st retransmission |
+----------+--------------+--------------------------------+----------------------------+
| 12 | 2 | 16 | 2nd retransmission |
+----------+--------------+--------------------------------+----------------------------+
| 28 | 3 | 32 | 3rd retransmission |
+----------+--------------+--------------------------------+----------------------------+
| 60 | 4 | 64 | 4th (final) retransmission |
+----------+--------------+--------------------------------+----------------------------+
| 124 | -- | -- | give up |
+----------+--------------+--------------------------------+----------------------------+

Other retransmission parameters
-------------------------------

While setting ``anjay_configuration_t::udp_tx_params`` parameter
covers most cases, there are also means to configure:

- DTLS handshake retransmissions
(``anjay_configuration_t::udp_dtls_hs_tx_params`` `docs
<../api/structanjay__configuration.html#ab8ca076537138e7d78bd1ee5d5e2031a>`_),

- SMS retransmission parameters (``anjay_configuration_t::sms_tx_params`` `docs
<../api/structanjay__configuration.html#a3358d949a97ff9e10c8838740dabab68>`_),

- firmware update module retransmissions (by implementing
custom ``anjay_fw_update_get_coap_tx_params_t`` handler `docs
<../api/fw__update_8h.html#ad0a274fbe4d73643df3aa62884d7decb>`_).

We recommend to refer to the doxygen documentation for more details.

0 comments on commit 1ae83f4

Please sign in to comment.
You can’t perform that action at this time.