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