| .. _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 |