Network long timeout primitives and helpers

Network long timeout primitives and helpers. More...

Data Structures
struct	net_timeout
	Generic struct for handling network timeouts. More...

Macros
#define	NET_TIMEOUT_MAX_VALUE   ((uint32_t)INT32_MAX)
	Divisor used to support ms resolution timeouts.

Functions
void	net_timeout_set (struct net_timeout *timeout, uint32_t lifetime, uint32_t now)
	Configure a network timeout structure.
int64_t	net_timeout_deadline (const struct net_timeout *timeout, int64_t now)
	Return the 64-bit system time at which the timeout will complete.
uint32_t	net_timeout_remaining (const struct net_timeout *timeout, uint32_t now)
	Calculate the remaining time to the timeout in whole seconds.
uint32_t	net_timeout_evaluate (struct net_timeout *timeout, uint32_t now)
	Update state to reflect elapsed time and get new delay.

Detailed Description

Network long timeout primitives and helpers.

Macro Definition Documentation

NET_TIMEOUT_MAX_VALUE

#define NET_TIMEOUT_MAX_VALUE   ((uint32_t)INT32_MAX)

#include <zephyr/net/net_timeout.h>

Divisor used to support ms resolution timeouts.

Because delays are processed in work queues which are not invoked synchronously with clock changes we need to be able to detect timeouts after they occur, which requires comparing "deadline" to "now" with enough "slop" to handle any observable latency due to "now" advancing past "deadline".

The simplest solution is to use the native conversion of the well-defined 32-bit unsigned difference to a 32-bit signed difference, which caps the maximum delay at INT32_MAX. This is compatible with the standard mechanism for detecting completion of deadlines that do not overflow their representation.

Function Documentation

net_timeout_deadline()

int64_t net_timeout_deadline	(	const struct net_timeout *	timeout,
		int64_t	now
	)

#include <zephyr/net/net_timeout.h>

Return the 64-bit system time at which the timeout will complete.

Note

Correct behavior requires invocation of net_timeout_evaluate() at its specified intervals.

Parameters

timeout	state a pointer to the timeout state, initialized by net_timeout_set() and maintained by net_timeout_evaluate().
now	the full-precision value of k_uptime_get() relative to which the deadline will be calculated.

Returns

the value of k_uptime_get() at which the timeout will expire.

net_timeout_evaluate()

uint32_t net_timeout_evaluate	(	struct net_timeout *	timeout,
		uint32_t	now
	)

#include <zephyr/net/net_timeout.h>

Update state to reflect elapsed time and get new delay.

This function must be invoked periodically to (1) apply the effect of elapsed time on what remains of a total delay that exceeded the maximum representable delay, and (2) determine that either the timeout has completed or that the infrastructure must wait a certain period before checking again for completion.

Parameters

timeout	a pointer to the timeout state
now	the time relative to which the estimate of remaining time should be calculated. This should be recently captured value from k_uptime_get_32().

Return values

0	if the timeout has completed
positive	the maximum delay until the state of this timeout should be re-evaluated, in milliseconds.

net_timeout_remaining()

uint32_t net_timeout_remaining	(	const struct net_timeout *	timeout,
		uint32_t	now
	)

#include <zephyr/net/net_timeout.h>

Calculate the remaining time to the timeout in whole seconds.

Note

This function rounds the remaining time down, i.e. if the timeout will occur in 3500 milliseconds the value 3 will be returned.

Correct behavior requires invocation of net_timeout_evaluate() at its specified intervals.

Parameters

timeout	a pointer to the timeout state
now	the time relative to which the estimate of remaining time should be calculated. This should be recently captured value from k_uptime_get_32().

Return values

0	if the timeout has completed.
positive	the remaining duration of the timeout, in seconds.

net_timeout_set()

void net_timeout_set	(	struct net_timeout *	timeout,
		uint32_t	lifetime,
		uint32_t	now
	)

#include <zephyr/net/net_timeout.h>

Configure a network timeout structure.

Parameters

timeout	a pointer to the timeout state.
lifetime	the duration of the timeout in seconds.
now	the time at which the timeout started counting down, in milliseconds. This is generally a captured value of k_uptime_get_32().