1.. _net_timeout_interface:
2
3Network Timeout
4###############
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13Zephyr's network infrastructure mostly uses the millisecond-resolution uptime
14clock to track timeouts, with both deadlines and durations measured with
1532-bit unsigned values.  The 32-bit value rolls over at 49 days 17 hours 2 minutes
1647.296 seconds.
17
18Timeout processing is often affected by latency, so that the time at which the
19timeout is checked may be some time after it should have expired.  Handling
20this correctly without arbitrary expectations of maximum latency requires that
21the maximum delay that can be directly represented be a 31-bit non-negative
22number (``INT32_MAX``), which overflows at 24 days 20 hours 31 minutes 23.648
23seconds.
24
25Most network timeouts are shorter than the delay rollover, but a few protocols
26allow for delays that are represented as unsigned 32-bit values counting
27seconds, which corresponds to a 42-bit millisecond count.
28
29The net_timeout API provides a generic timeout mechanism to correctly track
30the remaining time for these extended-duration timeouts.
31
32Use
33***
34
35The simplest use of this API is:
36
37#. Configure a network timeout using :c:func:`net_timeout_set()`.
38#. Use :c:func:`net_timeout_evaluate()` to determine how long it is until the
39   timeout occurs.  Schedule a timeout to occur after this delay.
40#. When the timeout callback is invoked, use :c:func:`net_timeout_evaluate()`
41   again to determine whether the timeout has completed, or whether there is
42   additional time remaining.  If the latter, reschedule the callback.
43#. While the timeout is running, use :c:func:`net_timeout_remaining` to get
44   the number of seconds until the timeout expires.  This may be used to
45   explicitly update the timeout, which should be done by canceling any
46   pending callback and restarting from step 1 with the new timeout.
47
48The :c:struct:`net_timeout` contains a ``sys_snode_t`` that allows multiple
49timeout instances to be aggregated to share a single kernel timer element.
50The application must use :c:func:`net_timeout_evaluate()` on all instances to
51determine the next timeout event to occur.
52
53:c:func:`net_timeout_deadline()` may be used to reconstruct the full-precision
54deadline of the timeout.  This exists primarily for testing but may have use
55in some applications, as it does allow a millisecond-resolution calculation of
56remaining time.
57
58API Reference
59*************
60
61.. doxygengroup:: net_timeout
62