clock.h File Reference

Pluggable monotonic clock for all library timing. More...

#include <Arduino.h>
#include <stdint.h>

Go to the source code of this file.

Classes
struct	DetwsLatencyStat
	Rolling latency statistics in microseconds: sample count, min / max / mean, and how many samples blew a budget. Fixed size, no heap; a subsystem (the preempting queue, a DMA path, a forwarding rule) keeps one and reports it for real-time visibility. More...

Typedefs
typedef uint32_t(*	detws_clock_fn) (void)
	User clock: returns a free-running monotonic tick count.

Functions
detws_clock_fn &	_detws_clock_fn_ref ()
uint32_t &	_detws_clock_div_ref ()
void	detws_set_clock (detws_clock_fn fn, uint32_t ticks_per_second)
	Install a custom clock running at ticks_per_second; the library divides it down to its internal 1000 Hz. Pass (nullptr, 0) to revert to the platform default.
uint32_t	detws_millis (void)
	The library's monotonic time at 1000 Hz (milliseconds).
detws_clock_fn &	_detws_micros_fn_ref ()
uint32_t &	_detws_micros_div_ref ()
void	detws_set_micros_clock (detws_clock_fn fn, uint32_t ticks_per_second)
	Install a custom microsecond clock running at ticks_per_second; the library divides it down to 1 MHz. Pass (nullptr, 0) for the platform default.
uint32_t	detws_micros (void)
	Monotonic microseconds - the high-resolution time base for ISR timestamps and sub-millisecond latency. Safe to call from an ISR. Wraps roughly every 71 minutes, so use it only for short deltas (unsigned subtraction is wrap-safe).
void	detws_lat_reset (DetwsLatencyStat *s)
	Zero a stat (min seeded high so the first sample sets it).
uint32_t	detws_lat_begin (void)
	Start of a measured span: capture the current microsecond time.
void	detws_lat_end (DetwsLatencyStat *s, uint32_t start_us, uint32_t budget_us)
	End of a span started at start_us: record its latency, counting it as over-budget when budget_us is non-zero and exceeded. Wrap-safe.
uint32_t	detws_lat_avg_us (const DetwsLatencyStat *s)
	Mean latency (us) over the recorded samples, 0 if none.

Detailed Description

Pluggable monotonic clock for all library timing.

The library's internal timing runs at 1000 Hz - one tick is one millisecond, the cadence the test suite asserts and every timeout / poll is expressed in. detws_millis() is that single time source; by default it is the platform millis().

To drive the library from your own clock (a hardware timer, an external RTC, a simulation clock), call:

detws_set_clock(my_clock_fn, my_ticks_per_second);

Your clock reports a free-running tick count at ticks_per_second. The library divides it down to its internal 1000 Hz, so timeouts and polling keep the exact 1 ms granularity the tests verify regardless of how fast your clock runs. Pass a rate >= 1000, ideally a multiple of 1000 for exact division (e.g. a 1 MHz timer -> ticks_per_second = 1000000, divided by 1000). Pass nullptr to revert to the platform default. One source covers everything - swap it once and every subsystem follows.

The worker poll cadence is fixed at 1000 Hz (the tested default); a build can trade latency for idle power with DETWS_WORKER_POLL_TICKS - see ServerConfig.h.

Header-only (the override state lives in inline-function-local statics, a single instance across the whole program), so there is nothing extra to compile or link.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file clock.h.

Typedef Documentation

detws_clock_fn

typedef uint32_t(* detws_clock_fn) (void)

User clock: returns a free-running monotonic tick count.

Definition at line 43 of file clock.h.

Function Documentation

_detws_clock_fn_ref()

detws_clock_fn & _detws_clock_fn_ref ( )

inline

Definition at line 48 of file clock.h.

Referenced by detws_millis(), and detws_set_clock().

_detws_clock_div_ref()

uint32_t & _detws_clock_div_ref ( )

inline

Definition at line 53 of file clock.h.

Referenced by detws_millis(), and detws_set_clock().

detws_set_clock()

void detws_set_clock ( detws_clock_fn  fn, uint32_t  ticks_per_second  )

inline

Install a custom clock running at ticks_per_second; the library divides it down to its internal 1000 Hz. Pass (nullptr, 0) to revert to the platform default.

Definition at line 64 of file clock.h.

References _detws_clock_div_ref(), and _detws_clock_fn_ref().

detws_millis()

uint32_t detws_millis ( void  )

inline

The library's monotonic time at 1000 Hz (milliseconds).

Definition at line 71 of file clock.h.

References _detws_clock_div_ref(), and _detws_clock_fn_ref().

Referenced by DeterministicAsyncTCP::check_timeouts(), det_conn_begin_close(), det_conn_touch_active(), detws_micros(), lowlevel_recv_cb(), lowlevel_sent_cb(), DetWebServer::service_once(), ssh_conn_poll(), and ssh_newkeys_complete().

_detws_micros_fn_ref()

detws_clock_fn & _detws_micros_fn_ref ( )

inline

Definition at line 88 of file clock.h.

Referenced by detws_micros(), and detws_set_micros_clock().

_detws_micros_div_ref()

uint32_t & _detws_micros_div_ref ( )

inline

Definition at line 93 of file clock.h.

Referenced by detws_micros(), and detws_set_micros_clock().

detws_set_micros_clock()

void detws_set_micros_clock ( detws_clock_fn  fn, uint32_t  ticks_per_second  )

inline

Install a custom microsecond clock running at ticks_per_second; the library divides it down to 1 MHz. Pass (nullptr, 0) for the platform default.

Definition at line 104 of file clock.h.

References _detws_micros_div_ref(), and _detws_micros_fn_ref().

detws_micros()

uint32_t detws_micros ( void  )

inline

Monotonic microseconds - the high-resolution time base for ISR timestamps and sub-millisecond latency. Safe to call from an ISR. Wraps roughly every 71 minutes, so use it only for short deltas (unsigned subtraction is wrap-safe).

Definition at line 116 of file clock.h.

References _detws_micros_div_ref(), _detws_micros_fn_ref(), and detws_millis().

Referenced by detws_lat_begin(), and detws_lat_end().

detws_lat_reset()

void detws_lat_reset ( DetwsLatencyStat *  s )

inline

Zero a stat (min seeded high so the first sample sets it).

Definition at line 148 of file clock.h.

References DetwsLatencyStat::count, DetwsLatencyStat::max_us, DetwsLatencyStat::min_us, DetwsLatencyStat::over_budget, and DetwsLatencyStat::sum_us.

detws_lat_begin()

uint32_t detws_lat_begin ( void  )

inline

Start of a measured span: capture the current microsecond time.

Definition at line 158 of file clock.h.

References detws_micros().

detws_lat_end()

void detws_lat_end ( DetwsLatencyStat *  s, uint32_t  start_us, uint32_t  budget_us  )

inline

End of a span started at start_us: record its latency, counting it as over-budget when budget_us is non-zero and exceeded. Wrap-safe.

Definition at line 167 of file clock.h.

References DetwsLatencyStat::count, detws_micros(), DetwsLatencyStat::max_us, DetwsLatencyStat::min_us, DetwsLatencyStat::over_budget, and DetwsLatencyStat::sum_us.

detws_lat_avg_us()

uint32_t detws_lat_avg_us ( const DetwsLatencyStat *  s )

inline

Mean latency (us) over the recorded samples, 0 if none.

Definition at line 181 of file clock.h.

References DetwsLatencyStat::count, and DetwsLatencyStat::sum_us.