Network Timeout
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
net_timeout_set().Use
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
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
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 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 net_timeout_evaluate() on all instances to
determine the next timeout event to occur.
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.