You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
61 lines
2.4 KiB
61 lines
2.4 KiB
.. _net_timeout_interface: |
|
|
|
Network Timeout |
|
############### |
|
|
|
.. contents:: |
|
:local: |
|
:depth: 2 |
|
|
|
Overview |
|
******** |
|
|
|
Zephyr's network infrastructure mostly uses the millisecond-resolution uptime |
|
clock to track timeouts, with both deadlines and durations measured with |
|
32-bit unsigned values. The 32-bit value rolls over at 49 days 17 hours 2 minutes |
|
47.296 seconds. |
|
|
|
Timeout processing is often affected by latency, so that the time at which the |
|
timeout is checked may be some time after it should have expired. Handling |
|
this correctly without arbitrary expectations of maximum latency requires that |
|
the maximum delay that can be directly represented be a 31-bit non-negative |
|
number (``INT32_MAX``), which overflows at 24 days 20 hours 31 minutes 23.648 |
|
seconds. |
|
|
|
Most network timeouts are shorter than the delay rollover, but a few protocols |
|
allow for delays that are represented as unsigned 32-bit values counting |
|
seconds, which corresponds to a 42-bit millisecond count. |
|
|
|
The net_timeout API provides a generic timeout mechanism to correctly track |
|
the remaining time for these extended-duration timeouts. |
|
|
|
Use |
|
*** |
|
|
|
The simplest use of this API is: |
|
|
|
#. Configure a network timeout using :c:func:`net_timeout_set()`. |
|
#. Use :c:func:`net_timeout_evaluate()` to determine how long it is until the |
|
timeout occurs. Schedule a timeout to occur after this delay. |
|
#. When the timeout callback is invoked, use :c:func:`net_timeout_evaluate()` |
|
again to determine whether the timeout has completed, or whether there is |
|
additional time remaining. If the latter, reschedule the callback. |
|
#. While the timeout is running, use :c:func:`net_timeout_remaining` to get |
|
the number of seconds until the timeout expires. This may be used to |
|
explicitly update the timeout, which should be done by canceling any |
|
pending callback and restarting from step 1 with the new timeout. |
|
|
|
The :c:struct:`net_timeout` contains a ``sys_snode_t`` that allows multiple |
|
timeout instances to be aggregated to share a single kernel timer element. |
|
The application must use :c:func:`net_timeout_evaluate()` on all instances to |
|
determine the next timeout event to occur. |
|
|
|
:c:func:`net_timeout_deadline()` may be used to reconstruct the full-precision |
|
deadline of the timeout. This exists primarily for testing but may have use |
|
in some applications, as it does allow a millisecond-resolution calculation of |
|
remaining time. |
|
|
|
API Reference |
|
************* |
|
|
|
.. doxygengroup:: net_timeout
|
|
|