Singleton service for background NTP measurements. More...

#include <ntp_time_service.hpp>

Public Member Functions
	NtpTimeServiceT (const NtpTimeServiceT &)=delete
NtpTimeServiceT &	operator= (const NtpTimeServiceT &)=delete
bool	init ()
	Start background measurements using stored interval.
bool	init (std::chrono::milliseconds interval, bool measure_immediately=true)
	Start background measurements with interval and immediate flag.
bool	init (int interval_ms, bool measure_immediately=true)
	Start background measurements using milliseconds.
void	shutdown ()
	Stop background measurements and release resources.
bool	running () const noexcept
	Return true when background runner is active.
void	ensure_started () noexcept
	Ensure background runner is started with current config.
int64_t	offset_us () noexcept
	Return last estimated offset in microseconds.
int64_t	utc_time_us () noexcept
	Return current UTC time in microseconds based on offset.
int64_t	utc_time_ms () noexcept
	Return current UTC time in milliseconds based on offset.
int64_t	utc_time_sec () noexcept
	Return current UTC time in seconds based on offset.
bool	last_measure_ok () const noexcept
	Return whether last measurement updated the offset.
uint64_t	measure_count () const noexcept
	Return total number of measurement attempts.
uint64_t	fail_count () const noexcept
	Return number of failed measurement attempts.
int64_t	last_update_realtime_us () const noexcept
	Return realtime timestamp of last measurement attempt.
int64_t	last_success_realtime_us () const noexcept
	Return realtime timestamp of last successful measurement.
bool	stale (std::chrono::milliseconds max_age) const noexcept
	Return true when last measurement is older than max_age.
bool	stale (int max_age_ms) const noexcept
	Return true when last measurement is older than max_age_ms.
bool	set_servers (std::vector< NtpServerConfig > servers)
	Replace server list used for new runner instances.
bool	set_default_servers ()
	Use conservative default servers for new runner instances.
bool	clear_servers ()
	Clear custom server list and return to default behavior.
bool	set_pool_config (NtpPoolConfig cfg)
	Override pool configuration for new runner instances.
NtpPoolConfig	pool_config () const
	Return current pool configuration.
std::vector< NtpSample >	last_samples () const
	Return copy of last measurement samples.
	NtpTimeServiceT ()=default
	Construct service.
	~NtpTimeServiceT ()=default
	Immortal singleton is stopped via process-shutdown handler.
bool	apply_config_now ()
	Apply current config by rebuilding the runner.

Static Public Member Functions
static NtpTimeServiceT &	instance () noexcept
	Return the singleton instance.

Private Types
enum class	ProcessState : uint8_t { alive , shutting_down }
	Global lifetime state of the immortal singleton. More...
enum class	State : uint8_t { stopped , starting , running , stopping }
	Lifecycle state of the singleton runner. More...

Private Member Functions
void	register_process_shutdown_handler () noexcept
	Register one process-shutdown handler for this specialization.
void	begin_process_shutdown () noexcept
	Mark the singleton as shutting down and stop the runner.
bool	is_process_shutting_down () const noexcept
	Return true when process shutdown has started.
bool	is_process_shutting_down_locked () const noexcept
	Return true when process shutdown has started.
uint32_t	atexit_registration_count () const noexcept
	Return number of successful atexit registrations.
bool	is_running_locked () const noexcept
	Check runner status under lock.
bool	is_transitioning_locked () const noexcept
	Return true when a start or stop transition is in progress.
bool	is_reconfigurable_locked () const noexcept
	Return true when configuration can be changed safely.
std::unique_ptr< RunnerT >	build_runner_locked ()
	Build a runner with current server list and pool config.

Private Attributes
std::mutex	m_mtx
std::condition_variable	m_cv
State	m_state {State::stopped}
std::atomic< ProcessState >	m_process_state {ProcessState::alive}
std::atomic< int64_t >	m_last_offset_us {0}
std::atomic< uint32_t >	m_atexit_registration_count {0}
std::chrono::milliseconds	m_interval {std::chrono::seconds(30)}
bool	m_measure_immediately {true}
bool	m_has_custom_servers {false}
std::vector< NtpServerConfig >	m_servers
bool	m_has_custom_pool_cfg {false}
NtpPoolConfig	m_pool_cfg {}
std::unique_ptr< RunnerT >	m_runner

Friends
struct	detail::NtpTimeServiceSingleton< RunnerT >
struct	detail::NtpTimeServiceTestAccess< RunnerT >

Detailed Description

template<class RunnerT>
class time_shield::NtpTimeServiceT< RunnerT >

Singleton service for background NTP measurements.

Uses an internal runner to keep offset updated. It exposes UTC time computed as realtime clock plus the latest offset. Configure pool servers and sampling before starting the service. During process shutdown, the singleton stops background work and falls back to the last cached offset without restarting the runner.

Definition at line 199 of file ntp_time_service.hpp.

Member Enumeration Documentation

◆ ProcessState

template<class RunnerT>

enum class time_shield::NtpTimeServiceT::ProcessState : uint8_t

strongprivate

Global lifetime state of the immortal singleton.

Enumerator
alive
shutting_down

Definition at line 602 of file ntp_time_service.hpp.

◆ State

template<class RunnerT>

enum class time_shield::NtpTimeServiceT::State : uint8_t

strongprivate

Lifecycle state of the singleton runner.

Enumerator
stopped
starting
running
stopping

Definition at line 608 of file ntp_time_service.hpp.

Constructor & Destructor Documentation

◆ NtpTimeServiceT() [1/2]

template<class RunnerT>

time_shield::NtpTimeServiceT< RunnerT >::NtpTimeServiceT ( const NtpTimeServiceT< RunnerT > & )

delete

◆ NtpTimeServiceT() [2/2]

template<class RunnerT>

time_shield::NtpTimeServiceT< RunnerT >::NtpTimeServiceT ( )

default

Construct service.

◆ ~NtpTimeServiceT()

template<class RunnerT>

time_shield::NtpTimeServiceT< RunnerT >::~NtpTimeServiceT ( )

default

Immortal singleton is stopped via process-shutdown handler.

Member Function Documentation

◆ apply_config_now()

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::apply_config_now ( )

inline

Apply current config by rebuilding the runner.

Returns: True when runner restarted successfully.

Definition at line 524 of file ntp_time_service.hpp.

◆ atexit_registration_count()

template<class RunnerT>

uint32_t time_shield::NtpTimeServiceT< RunnerT >::atexit_registration_count ( ) const

inlineprivatenoexcept

Return number of successful atexit registrations.

Definition at line 667 of file ntp_time_service.hpp.

◆ begin_process_shutdown()

template<class RunnerT>

void time_shield::NtpTimeServiceT< RunnerT >::begin_process_shutdown ( )

inlineprivatenoexcept

Mark the singleton as shutting down and stop the runner.

Definition at line 623 of file ntp_time_service.hpp.

◆ build_runner_locked()

template<class RunnerT>

std::unique_ptr< RunnerT > time_shield::NtpTimeServiceT< RunnerT >::build_runner_locked ( )

inlineprivate

Build a runner with current server list and pool config.

Definition at line 687 of file ntp_time_service.hpp.

◆ clear_servers()

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::clear_servers ( )

inline

Clear custom server list and return to default behavior.

Returns: False when service is already running.

Definition at line 476 of file ntp_time_service.hpp.

◆ ensure_started()

template<class RunnerT>

void time_shield::NtpTimeServiceT< RunnerT >::ensure_started ( )

inlinenoexcept

Ensure background runner is started with current config.

Definition at line 337 of file ntp_time_service.hpp.

◆ fail_count()

template<class RunnerT>

uint64_t time_shield::NtpTimeServiceT< RunnerT >::fail_count ( ) const

inlinenoexcept

Return number of failed measurement attempts.

Returns: Number of failed measurement attempts.

Definition at line 408 of file ntp_time_service.hpp.

◆ init() [1/3]

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::init ( )

inline

Start background measurements using stored interval.

Returns: True when background runner started.

Definition at line 215 of file ntp_time_service.hpp.

◆ init() [2/3]

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::init	(	int	interval_ms,
		bool	measure_immediately = true )

inline

Start background measurements 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 299 of file ntp_time_service.hpp.

◆ init() [3/3]

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::init	(	std::chrono::milliseconds	interval,
		bool	measure_immediately = true )

inline

Start background measurements with interval and immediate flag.

Parameters

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

Returns: True when background runner started.

Definition at line 223 of file ntp_time_service.hpp.

◆ instance()

template<class RunnerT>

NtpTimeServiceT & time_shield::NtpTimeServiceT< RunnerT >::instance ( )

inlinestaticnoexcept

Return the singleton instance.

Returns: Singleton instance.

Definition at line 206 of file ntp_time_service.hpp.

◆ is_process_shutting_down()

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::is_process_shutting_down ( ) const

inlineprivatenoexcept

Return true when process shutdown has started.

Definition at line 657 of file ntp_time_service.hpp.

◆ is_process_shutting_down_locked()

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::is_process_shutting_down_locked ( ) const

inlineprivatenoexcept

Return true when process shutdown has started.

Definition at line 662 of file ntp_time_service.hpp.

◆ is_reconfigurable_locked()

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::is_reconfigurable_locked ( ) const

inlineprivatenoexcept

Return true when configuration can be changed safely.

Definition at line 682 of file ntp_time_service.hpp.

◆ is_running_locked()

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::is_running_locked ( ) const

inlineprivatenoexcept

Check runner status under lock.

Definition at line 672 of file ntp_time_service.hpp.

◆ is_transitioning_locked()

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::is_transitioning_locked ( ) const

inlineprivatenoexcept

Return true when a start or stop transition is in progress.

Definition at line 677 of file ntp_time_service.hpp.

◆ last_measure_ok()

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::last_measure_ok ( ) const

inlinenoexcept

Return whether last measurement updated the offset.

Returns: True when last measurement updated the offset.

Definition at line 392 of file ntp_time_service.hpp.

◆ last_samples()

template<class RunnerT>

std::vector< NtpSample > time_shield::NtpTimeServiceT< RunnerT >::last_samples ( ) const

inline

Return copy of last measurement samples.

Returns: Copy of samples from the last measurement.

Definition at line 511 of file ntp_time_service.hpp.

◆ last_success_realtime_us()

template<class RunnerT>

int64_t time_shield::NtpTimeServiceT< RunnerT >::last_success_realtime_us ( ) const

inlinenoexcept

Return realtime timestamp of last successful measurement.

Returns: Realtime microseconds timestamp for last successful measurement.

Definition at line 424 of file ntp_time_service.hpp.

◆ last_update_realtime_us()

template<class RunnerT>

int64_t time_shield::NtpTimeServiceT< RunnerT >::last_update_realtime_us ( ) const

inlinenoexcept

Return realtime timestamp of last measurement attempt.

Returns: Realtime microseconds timestamp for last measurement attempt.

Definition at line 416 of file ntp_time_service.hpp.

◆ measure_count()

template<class RunnerT>

uint64_t time_shield::NtpTimeServiceT< RunnerT >::measure_count ( ) const

inlinenoexcept

Return total number of measurement attempts.

Returns: Number of measurement attempts.

Definition at line 400 of file ntp_time_service.hpp.

◆ offset_us()

template<class RunnerT>

int64_t time_shield::NtpTimeServiceT< RunnerT >::offset_us ( )

inlinenoexcept

Return last estimated offset in microseconds.

Note: During process shutdown, returns the last cached offset without restarting the background runner.

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

Definition at line 351 of file ntp_time_service.hpp.

◆ operator=()

template<class RunnerT>

NtpTimeServiceT & time_shield::NtpTimeServiceT< RunnerT >::operator= ( const NtpTimeServiceT< RunnerT > & )

delete

◆ pool_config()

template<class RunnerT>

NtpPoolConfig time_shield::NtpTimeServiceT< RunnerT >::pool_config ( ) const

inline

Return current pool configuration.

Returns: Current pool configuration.

Definition at line 501 of file ntp_time_service.hpp.

◆ register_process_shutdown_handler()

template<class RunnerT>

void time_shield::NtpTimeServiceT< RunnerT >::register_process_shutdown_handler ( )

inlineprivatenoexcept

Register one process-shutdown handler for this specialization.

Definition at line 616 of file ntp_time_service.hpp.

◆ running()

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::running ( ) const

inlinenoexcept

Return true when background runner is active.

Returns: True when background runner is active.

Definition at line 331 of file ntp_time_service.hpp.

◆ set_default_servers()

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::set_default_servers ( )

inline

Use conservative default servers for new runner instances.

Returns: False when service is already running.

Definition at line 464 of file ntp_time_service.hpp.

◆ set_pool_config()

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::set_pool_config ( NtpPoolConfig cfg )

inline

Override pool configuration for new runner instances.

Parameters

cfg	Pool configuration to apply.

Returns: False when service is already running.

Definition at line 489 of file ntp_time_service.hpp.

◆ set_servers()

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::set_servers ( std::vector< NtpServerConfig > servers )

inline

Replace server list used for new runner instances.

Parameters

servers Server configurations to use.

Returns: False when service is already running.

Definition at line 452 of file ntp_time_service.hpp.

◆ shutdown()

template<class RunnerT>

void time_shield::NtpTimeServiceT< RunnerT >::shutdown ( )

inline

Stop background measurements and release resources.

Definition at line 304 of file ntp_time_service.hpp.

◆ stale() [1/2]

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::stale ( int max_age_ms ) const

inlinenoexcept

Return true when last measurement is older than max_age_ms.

Parameters

max_age_ms Maximum allowed age in milliseconds.

Returns: True when last measurement age exceeds max_age_ms.

Definition at line 445 of file ntp_time_service.hpp.

◆ stale() [2/2]

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::stale ( std::chrono::milliseconds max_age ) const

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 433 of file ntp_time_service.hpp.

◆ utc_time_ms()

template<class RunnerT>

int64_t time_shield::NtpTimeServiceT< RunnerT >::utc_time_ms ( )

inlinenoexcept

Return current UTC time in milliseconds based on offset.

Returns: UTC time in milliseconds using last offset.

Definition at line 380 of file ntp_time_service.hpp.

◆ utc_time_sec()

template<class RunnerT>

int64_t time_shield::NtpTimeServiceT< RunnerT >::utc_time_sec ( )

inlinenoexcept

Return current UTC time in seconds based on offset.

Returns: UTC time in seconds using last offset.

Definition at line 386 of file ntp_time_service.hpp.

◆ utc_time_us()

template<class RunnerT>

int64_t time_shield::NtpTimeServiceT< RunnerT >::utc_time_us ( )

inlinenoexcept

Return current UTC time in microseconds based on offset.

Note: During process shutdown, returns realtime plus the last cached offset without restarting the background runner.

Returns: UTC time in microseconds using last offset.

Definition at line 367 of file ntp_time_service.hpp.

◆ detail::NtpTimeServiceSingleton< RunnerT >

template<class RunnerT>

friend struct detail::NtpTimeServiceSingleton< RunnerT >

friend

Definition at line 185 of file ntp_time_service.hpp.

◆ detail::NtpTimeServiceTestAccess< RunnerT >

template<class RunnerT>

friend struct detail::NtpTimeServiceTestAccess< RunnerT >

friend

Definition at line 185 of file ntp_time_service.hpp.

Member Data Documentation

◆ m_atexit_registration_count

template<class RunnerT>

std::atomic<uint32_t> time_shield::NtpTimeServiceT< RunnerT >::m_atexit_registration_count {0}

private

Definition at line 714 of file ntp_time_service.hpp.

◆ m_cv

template<class RunnerT>

std::condition_variable time_shield::NtpTimeServiceT< RunnerT >::m_cv

private

Definition at line 710 of file ntp_time_service.hpp.

◆ m_has_custom_pool_cfg

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::m_has_custom_pool_cfg {false}

private

Definition at line 721 of file ntp_time_service.hpp.

◆ m_has_custom_servers

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::m_has_custom_servers {false}

private

Definition at line 718 of file ntp_time_service.hpp.

◆ m_interval

template<class RunnerT>

std::chrono::milliseconds time_shield::NtpTimeServiceT< RunnerT >::m_interval {std::chrono::seconds(30)}

private

Definition at line 715 of file ntp_time_service.hpp.

◆ m_last_offset_us

template<class RunnerT>

std::atomic<int64_t> time_shield::NtpTimeServiceT< RunnerT >::m_last_offset_us {0}

private

Definition at line 713 of file ntp_time_service.hpp.

◆ m_measure_immediately

template<class RunnerT>

bool time_shield::NtpTimeServiceT< RunnerT >::m_measure_immediately {true}

private

Definition at line 716 of file ntp_time_service.hpp.

◆ m_mtx

template<class RunnerT>

std::mutex time_shield::NtpTimeServiceT< RunnerT >::m_mtx

mutableprivate

Definition at line 709 of file ntp_time_service.hpp.

◆ m_pool_cfg

template<class RunnerT>

NtpPoolConfig time_shield::NtpTimeServiceT< RunnerT >::m_pool_cfg {}

private

Definition at line 722 of file ntp_time_service.hpp.

◆ m_process_state

template<class RunnerT>

std::atomic<ProcessState> time_shield::NtpTimeServiceT< RunnerT >::m_process_state {ProcessState::alive}

private

Definition at line 712 of file ntp_time_service.hpp.

◆ m_runner

template<class RunnerT>

std::unique_ptr<RunnerT> time_shield::NtpTimeServiceT< RunnerT >::m_runner

private

Definition at line 724 of file ntp_time_service.hpp.

◆ m_servers

template<class RunnerT>

std::vector<NtpServerConfig> time_shield::NtpTimeServiceT< RunnerT >::m_servers

private

Definition at line 719 of file ntp_time_service.hpp.

◆ m_state

template<class RunnerT>

State time_shield::NtpTimeServiceT< RunnerT >::m_state {State::stopped}

private

Definition at line 711 of file ntp_time_service.hpp.

The documentation for this class was generated from the following file:

include/time_shield/ntp_time_service.hpp

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Private Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ ProcessState

◆ State

Constructor & Destructor Documentation

◆ NtpTimeServiceT() [1/2]

◆ NtpTimeServiceT() [2/2]

◆ ~NtpTimeServiceT()

Member Function Documentation

◆ apply_config_now()

◆ atexit_registration_count()

◆ begin_process_shutdown()

◆ build_runner_locked()

◆ clear_servers()

◆ ensure_started()

◆ fail_count()

◆ init() [1/3]

◆ init() [2/3]

◆ init() [3/3]

◆ instance()

◆ is_process_shutting_down()

◆ is_process_shutting_down_locked()

◆ is_reconfigurable_locked()

◆ is_running_locked()

◆ is_transitioning_locked()

◆ last_measure_ok()

◆ last_samples()

◆ last_success_realtime_us()

◆ last_update_realtime_us()

◆ measure_count()

◆ offset_us()

◆ operator=()

◆ pool_config()

◆ register_process_shutdown_handler()

◆ running()

◆ set_default_servers()

◆ set_pool_config()

◆ set_servers()

◆ shutdown()

◆ stale() [1/2]

◆ stale() [2/2]

◆ utc_time_ms()

◆ utc_time_sec()

◆ utc_time_us()

Friends And Related Symbol Documentation

◆ detail::NtpTimeServiceSingleton< RunnerT >

◆ detail::NtpTimeServiceTestAccess< RunnerT >

Member Data Documentation

◆ m_atexit_registration_count

◆ m_cv

◆ m_has_custom_pool_cfg

◆ m_has_custom_servers

◆ m_interval

◆ m_last_offset_us

◆ m_measure_immediately

◆ m_mtx

◆ m_pool_cfg

◆ m_process_state

◆ m_runner

◆ m_servers

◆ m_state