Facilities for retrieving time using the Network Time Protocol. More...

Files
file	ntp_client.hpp
	Simple NTP client for querying time offset from NTP servers.

file	wsa_guard.hpp
	Singleton guard for WinSock initialization.

Classes
class	time_shield::NtpClient
	NTP client for measuring time offset. More...

struct	time_shield::detail::NtpPacket
	NTP packet layout (48 bytes). More...

class	time_shield::WsaGuard
	Singleton guard for WinSock initialization. More...

struct	time_shield::NtpSample
	NTP measurement sample (one server response). More...

struct	time_shield::NtpServerConfig
	Per-server configuration. More...

struct	time_shield::NtpPoolConfig
	Pool configuration. More...

class	time_shield::NtpClientPoolT< ClientT >
	Pool of NTP servers: rate-limited multi-server offset estimation. More...

class	time_shield::BasicPoolRunner< PoolT >
	Background runner that periodically measures NTP offsets using a pool. More...

class	time_shield::NtpTimeServiceT< RunnerT >
	Singleton service for background NTP measurements. More...

Typedefs
using	time_shield::NtpTimeService = NtpTimeServiceT<detail::FakeNtpRunner>
	NTP time service alias that uses a fake runner for tests.

Enumerations
enum	time_shield::detail::NtpProtoError { time_shield::detail::NTP_EPROTO_BASE = -10000 , time_shield::detail::NTP_E_BAD_MODE = NTP_EPROTO_BASE - 1 , time_shield::detail::NTP_E_BAD_VERSION = NTP_EPROTO_BASE - 2 , time_shield::detail::NTP_E_BAD_LI = NTP_EPROTO_BASE - 3 , time_shield::detail::NTP_E_BAD_STRATUM = NTP_EPROTO_BASE - 4 , time_shield::detail::NTP_E_KOD = NTP_EPROTO_BASE - 5 , time_shield::detail::NTP_E_BAD_TS = NTP_EPROTO_BASE - 6 }
	Protocol-level error codes for NTP parsing. More...

Functions
bool	time_shield::ntp::init (std::chrono::milliseconds interval=std::chrono::seconds(30), bool measure_immediately=true)
	Initialize NTP time service and start background measurements.

bool	time_shield::ntp::init (int interval_ms, bool measure_immediately=true)
	Initialize NTP time service using milliseconds.

void	time_shield::ntp::shutdown ()
	Stop NTP time service.

int64_t	time_shield::ntp::offset_us () noexcept
	Return last estimated offset in microseconds.

int64_t	time_shield::ntp::utc_time_us () noexcept
	Return current UTC time in microseconds based on offset.

int64_t	time_shield::ntp::utc_time_ms () noexcept
	Return current UTC time in milliseconds based on offset.

int64_t	time_shield::ntp::utc_time_sec () noexcept
	Return current UTC time in seconds based on offset.

bool	time_shield::ntp::last_measure_ok () noexcept
	Return whether last measurement updated the offset.

uint64_t	time_shield::ntp::measure_count () noexcept
	Return total number of measurement attempts.

uint64_t	time_shield::ntp::fail_count () noexcept
	Return number of failed measurement attempts.

int64_t	time_shield::ntp::last_update_realtime_us () noexcept
	Return realtime timestamp of last measurement attempt.

int64_t	time_shield::ntp::last_success_realtime_us () noexcept
	Return realtime timestamp of last successful measurement.

bool	time_shield::ntp::stale (std::chrono::milliseconds max_age) noexcept
	Return true when last measurement is older than max_age.

Detailed Description

Facilities for retrieving time using the Network Time Protocol.

This module contains a minimal client and optional pool/service pipeline capable of querying remote NTP servers to measure the offset between local realtime and network time. It uses WinSock via the WsaGuard helper on Windows and POSIX sockets on Unix platforms.

Architecture:

NtpClient performs a single request/response exchange with one server.
NtpClientPool samples multiple servers with rate limiting and backoff.
NtpClientPoolRunner runs the pool periodically in a background thread.
NtpTimeService wraps the runner in a singleton interface for easy access.

Offset computation:

For each response, offsets and delays are computed using the standard NTP four-timestamp method:

t1 — client transmit time
t2 — server receive time
t3 — server transmit time
t4 — client receive time

Offset and delay are derived as: offset = ((t2 - t1) + (t3 - t4)) / 2, delay = (t4 - t1) - (t3 - t2).

Pools aggregate per-server offsets using the configured strategy (median, best-delay sample, or median with MAD trimming) and optional exponential smoothing.

Features:

Query NTP servers and obtain the time offset.
Retrieve corrected UTC time in microseconds and milliseconds.
Automatic WinSock initialization through WsaGuard (Windows build).
Requires network connectivity.

Example Usage:

time_shield::NtpClient client;
if (client.query()) {
    int64_t offset = client.offset_us();
    int64_t utc_ms = client.utc_time_ms();
}

Typedef Documentation

◆ NtpTimeService

typedef NtpTimeServiceT< NtpClientPoolRunner > time_shield::NtpTimeService = NtpTimeServiceT<detail::FakeNtpRunner>

NTP time service alias that uses a fake runner for tests.

NTP time service alias that uses the real pool runner.

Definition at line 556 of file ntp_time_service.hpp.

Enumeration Type Documentation

◆ NtpProtoError

enum time_shield::detail::NtpProtoError

Protocol-level error codes for NTP parsing.

Enumerator
NTP_EPROTO_BASE
NTP_E_BAD_MODE
NTP_E_BAD_VERSION
NTP_E_BAD_LI
NTP_E_BAD_STRATUM
NTP_E_KOD
NTP_E_BAD_TS

Definition at line 42 of file ntp_packet.hpp.

Function Documentation

◆ fail_count()

uint64_t time_shield::ntp::fail_count ( )

inlinenoexcept

Return number of failed measurement attempts.

Returns: Number of failed measurement attempts.

Definition at line 636 of file ntp_time_service.hpp.

◆ init() [1/2]

bool time_shield::ntp::init	(	int	interval_ms,
		bool	measure_immediately = true )

inline

Initialize NTP time service using milliseconds.

Parameters

interval_ms	Measurement interval in milliseconds.
measure_immediately	Measure before first sleep if true.

Returns: True when background runner started.

Definition at line 580 of file ntp_time_service.hpp.

◆ init() [2/2]

bool time_shield::ntp::init	(	std::chrono::milliseconds	interval = std::chrono::seconds(30),
		bool	measure_immediately = true )

inline

Initialize NTP time service and start background measurements.

Parameters

interval	Measurement interval.
measure_immediately	Measure before first sleep if true.

Returns: True when background runner started.

Definition at line 570 of file ntp_time_service.hpp.

◆ last_measure_ok()

bool time_shield::ntp::last_measure_ok ( )

inlinenoexcept

Return whether last measurement updated the offset.

Returns: True when last measurement updated the offset.

Definition at line 622 of file ntp_time_service.hpp.

◆ last_success_realtime_us()

int64_t time_shield::ntp::last_success_realtime_us ( )

inlinenoexcept

Return realtime timestamp of last successful measurement.

Returns: Realtime microseconds timestamp for last successful measurement.

Definition at line 650 of file ntp_time_service.hpp.

◆ last_update_realtime_us()

int64_t time_shield::ntp::last_update_realtime_us ( )

inlinenoexcept

Return realtime timestamp of last measurement attempt.

Returns: Realtime microseconds timestamp for last measurement attempt.

Definition at line 643 of file ntp_time_service.hpp.

◆ measure_count()

uint64_t time_shield::ntp::measure_count ( )

inlinenoexcept

Return total number of measurement attempts.

Returns: Number of measurement attempts.

Definition at line 629 of file ntp_time_service.hpp.

◆ offset_us()

int64_t time_shield::ntp::offset_us ( )

inlinenoexcept

Return last estimated offset in microseconds.

Returns: Offset in microseconds (UTC - local realtime).

Definition at line 594 of file ntp_time_service.hpp.

◆ shutdown()

void time_shield::ntp::shutdown ( )

inline

Stop NTP time service.

Definition at line 587 of file ntp_time_service.hpp.

◆ stale()

bool time_shield::ntp::stale ( std::chrono::milliseconds max_age )

inlinenoexcept

Return true when last measurement is older than max_age.

Parameters

max_age Maximum allowed age.

Returns: True when last measurement age exceeds max_age.

Definition at line 658 of file ntp_time_service.hpp.

◆ utc_time_ms()

int64_t time_shield::ntp::utc_time_ms ( )

inlinenoexcept

Return current UTC time in milliseconds based on offset.

Returns: UTC time in milliseconds using last offset.

Definition at line 608 of file ntp_time_service.hpp.

◆ utc_time_sec()

int64_t time_shield::ntp::utc_time_sec ( )

inlinenoexcept

Return current UTC time in seconds based on offset.

Returns: UTC time in seconds using last offset.

Definition at line 615 of file ntp_time_service.hpp.

◆ utc_time_us()

int64_t time_shield::ntp::utc_time_us ( )

inlinenoexcept

Return current UTC time in microseconds based on offset.

Returns: UTC time in microseconds using last offset.

Definition at line 601 of file ntp_time_service.hpp.

Files

Classes

Typedefs

Enumerations

Functions

Detailed Description

Architecture:

Offset computation:

Features:

Example Usage:

Typedef Documentation

◆ NtpTimeService

Enumeration Type Documentation

◆ NtpProtoError

Function Documentation

◆ fail_count()

◆ init() [1/2]

◆ init() [2/2]

◆ last_measure_ok()

◆ last_success_realtime_us()

◆ last_update_realtime_us()

◆ measure_count()

◆ offset_us()

◆ shutdown()

◆ stale()

◆ utc_time_ms()

◆ utc_time_sec()

◆ utc_time_us()