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 198 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 601 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 607 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 523 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 666 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 622 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 686 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 475 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 336 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 407 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 214 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 298 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 222 of file ntp_time_service.hpp.

◆ instance()

template<class RunnerT >

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

inlinestaticnoexcept

Return the singleton instance.

Returns: Singleton instance.

Definition at line 205 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 656 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 661 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 681 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 671 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 676 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 391 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 510 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 423 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 415 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 399 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 350 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 500 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 615 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 330 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 463 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 488 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 451 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 303 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 444 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 432 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 379 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 385 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 366 of file ntp_time_service.hpp.

Friends And Related Symbol Documentation

◆ detail::NtpTimeServiceSingleton< RunnerT >

template<class RunnerT >

friend struct detail::NtpTimeServiceSingleton< RunnerT >

friend

Definition at line 184 of file ntp_time_service.hpp.

◆ detail::NtpTimeServiceTestAccess< RunnerT >

template<class RunnerT >

friend struct detail::NtpTimeServiceTestAccess< RunnerT >

friend

Definition at line 184 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 713 of file ntp_time_service.hpp.

◆ m_cv

template<class RunnerT >

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

private

Definition at line 709 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 720 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 717 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 714 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 712 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 715 of file ntp_time_service.hpp.

◆ m_mtx

template<class RunnerT >

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

mutableprivate

Definition at line 708 of file ntp_time_service.hpp.

◆ m_pool_cfg

template<class RunnerT >

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

private

Definition at line 721 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 711 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 723 of file ntp_time_service.hpp.

◆ m_servers

template<class RunnerT >

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

private

Definition at line 718 of file ntp_time_service.hpp.

◆ m_state

template<class RunnerT >

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

private

Definition at line 710 of file ntp_time_service.hpp.

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

include/time_shield/ntp/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