A clock driver to use clocks through the POSIX interface. More...

#include <PosixClock.hpp>

Inheritance diagram for duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >:

Collaboration diagram for duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >:

Classes
struct	Token

Public Types
typedef duds::data::GenericMeasurement< SVT, SQT, TVT, TQT >	Measurement

Public Types inherited from duds::hardware::devices::clocks::GenericClock< SVT, SQT, TVT, TQT >
typedef std::shared_ptr< GenericClock< SVT, SQT, TVT, TQT > >	ClockSptr

typedef duds::data::GenericMeasurement< SVT, SQT, TVT, TQT >	Measurement
	The measurement type provided by the instruments of this device. More...

Public Types inherited from duds::hardware::devices::GenericDevice< SVT, SQT, TVT, TQT >
typedef clocks::GenericClock< SVT, SQT, TVT, TQT >	Clock
	The clock driver type used by the instruments of this device for time stamps. More...

typedef std::shared_ptr< Clock >	ClockSptr
	A shared pointer type to the clock type used by this device. More...

typedef std::shared_ptr< const Measurement >	ConstMeasurementSptr
	A shared pointer type to the const measurement type used by this device. More...

typedef std::shared_ptr< const Sensor >	ConstSensorSptr
	A shared pointer type to the const sensor type used by this device. More...

typedef duds::data::GenericMeasurement< SVT, SQT, TVT, TQT >	Measurement
	The measurement type provided by the instruments of this device. More...

typedef std::shared_ptr< Measurement >	MeasurementSptr
	A shared pointer type to the measurement type used by this device. More...

typedef GenericSensor< SVT, SQT, TVT, TQT >	Sensor
	The sensor type used by this device. More...

typedef std::shared_ptr< Sensor >	SensorSptr
	A shared pointer type to the sensor type used by this device. More...

typedef std::weak_ptr< Sensor >	SensorWptr
	A weak pointer type to the sensor type used by this device. More...

Public Member Functions
virtual void	sample ()
	Samples the time from this clock stores it in the measured field of the Measurement object of the device's first sensor. More...

virtual void	sample (const ClockSptr &clock)
	Samples the time from this clock and the given clock, then stores the measurement. More...

virtual void	sampleTime (typename Measurement::TimeSample &time)
	Samples the time from the clock device without storing the result in the clock's sensor object. More...

virtual bool	unambiguous () const noexcept
	Returns true if the clock properly reports the time during a leap second. More...

Public Member Functions inherited from duds::hardware::devices::clocks::GenericClock< SVT, SQT, TVT, TQT >
	operator ClockSptr () const

Measurement::TimeSample	sampleTime ()
	Samples the time from the clock device without storing the result in the clock's sensor object. More...

Public Member Functions inherited from duds::hardware::devices::GenericDevice< SVT, SQT, TVT, TQT >
	~GenericDevice ()
	Modifies member Sensor objects so they no longer have a pointer back to this object, and waits for calls those objects may be making to sharedPtr() to complete. More...

ConstMeasurementSptr	currentMeasurement (unsigned int sIdx=0) const
	Returns the measurement object for the sensor at the given device specific index. More...

unsigned int	numSensors () const
	Returns the number of sensors provided by this device. More...

virtual void	sample (const ClockSptr &clock)=0
	Samples the device and updates its sensor objects, and provides a timestamp from the given clock device. More...

const SensorSptr &	sensor (unsigned int sIdx=0) const
	Returns the sensor object at the given device specific index. More...

std::shared_ptr< GenericDevice< SVT, SQT, TVT, TQT > >	sharedPtr ()
	Returns a shared pointer to this device object; will be empty if this object's destructor is running. More...

Public Member Functions inherited from duds::Something
virtual	~Something ()=0

std::string	getName () const
	Returns the name for the current locale. More...

const general::LanguageTaggedStringMap &	names () const
	Returns the set of names for all locales and languages. More...

bool	operator!= (const Something &s) const
	Something objects are compared using the someId member. More...

bool	operator< (const Something &s) const
	Something objects are compared using the someId member. More...

bool	operator<= (const Something &s) const
	Something objects are compared using the someId member. More...

bool	operator== (const Something &s) const
	Something objects are compared using the someId member. More...

bool	operator> (const Something &s) const
	Something objects are compared using the someId member. More...

bool	operator>= (const Something &s) const
	Something objects are compared using the someId member. More...

template<class DerivedClass >
std::shared_ptr< DerivedClass >	sharedPtr () const
	Returns a shared pointer to this object for a derived class. More...

const boost::uuids::uuid &	uuid () const
	Returns the object's unique identifier. More...

Static Public Member Functions
static std::shared_ptr< GenericPosixClock< SVT, SQT, TVT, TQT > >	make (clockid_t id=CLOCK_REALTIME, int os=0)
	Makes a new clock device for a POSIX clock. More...

Private Member Functions
	GenericPosixClock (clockid_t id, int os, Token)
	Construct a clock device for the given POSIX clock. More...

duds::data::int128_t	doSample () const
	Samples the time and adds in an offset. More...

template<class Sample >
void	setSample (Sample &dest, const duds::data::int128_t &time) const
	Sets the sample values based on the time sample. More...

Static Private Member Functions
static duds::data::int128_t	sum (const timespec &ts)
	Sums the second and nanosecond fields given by the POSIX functions into a large integer. More...

Private Attributes
clockid_t	clk
	The POSIX clock id. More...

int	offset
	An offset in seconds that is applied to the time provided by the clock. More...

SQT	sampleResolution
	The clock's resolution for use with samples. More...

TQT	timeResolution
	The clock's resolution for use with time stamps. More...

Additional Inherited Members
Protected Member Functions inherited from duds::hardware::devices::clocks::GenericClock< SVT, SQT, TVT, TQT >
	GenericClock ()=delete

	GenericClock (const boost::uuids::uuid &id)

Protected Member Functions inherited from duds::hardware::devices::GenericDevice< SVT, SQT, TVT, TQT >
	GenericDevice ()=default
	Derived classes should create Sensor objects and place them in sens either in the constructor or an initialization function. More...

	GenericDevice (const boost::uuids::uuid &id)
	Derived classes should create Sensor objects and place them in sens either in the constructor or an initialization function. More...

void	setMeasurement (const ConstMeasurementSptr &store, int sIdx=0) const
	Updates the current measurement of a member sensor. More...

void	setMeasurement (ConstMeasurementSptr &&store, int sIdx=0) const
	Updates the current measurement of a member sensor. More...

Protected Member Functions inherited from duds::Something
	Something ()=default
	Simple constructor. More...

	Something (const boost::uuids::uuid &id)
	Creates Something with the given UUID. More...

void	setUuid (const boost::uuids::uuid &id)
	Sets the UUID that is associated with this object. More...

Static Protected Member Functions inherited from duds::hardware::devices::clocks::GenericClock< SVT, SQT, TVT, TQT >
template<class Ratio , class Src , class Dest >
static void	convert (Dest &dest, const Src &src)
	General template to convert time in one format to another. More...

template<class Ratio , class Src >
static void	convert (duds::time::interstellar::FemtoTime &dest, const Src &src)
	Template specialization to convert time in one format to FemtoTime. More...

template<class Ratio , class Src >
static void	convert (duds::time::interstellar::NanoTime &dest, const Src &src)
	Template specialization to convert time in one format to NanoTime. More...

template<class Ratio , class Src >
static void	convert (duds::data::GenericValue &dest, const Src &src)
	Template specialization to convert time in one format to FemtoTime in a GenericValue. More...

template<class Ratio , class IST , class Src >
static void	convertIST (IST &dest, const Src &src)
	Template to convert time in one format to one of the types defined in duds::time::interstellar. More...

template<class Ratio , class IST >
static void	convertIST (IST &dest, const duds::data::int128_t &src)
	More specialized template to convert time stored in a 128-bit integer to one of the types defined in duds::time::interstellar. More...

Protected Attributes inherited from duds::hardware::devices::GenericDevice< SVT, SQT, TVT, TQT >
std::vector< SensorSptr >	sens
	Contains Sensor objects to represent all the kinds of data this device can collect. More...

Protected Attributes inherited from duds::Something
general::LanguageTaggedStringMap	ltnames
	A name for this item intended for user presentation. More...

Detailed Description

template<class SVT, class SQT, class TVT, class TQT>
class duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >

A clock driver to use clocks through the POSIX interface.

Not all POSIX clocks are suitable to provide the time. For example, CLOCK_MONOTONIC cannot be related to the time without additional information.

Warning: Linux uses an offset between UTC and TAI, and computes TAI from UTC. The default value of this offset is zero and will result in TAI being the same as UTC, which is incorrect. The Linux specific adjtimex() function queries the current offset value. On most Linux systems, unless a system administrator has taken action to assure the offset is set, then it probably is not set. It seems most distributions do nothing to set the offset.

Template Parameters

SVT	Sample value type.
SQT	Sample quality type.
TVT	Time value type.
TQT	Time quality type.

Author: Jeff Jackowski

Definition at line 71 of file PosixClock.hpp.

Member Typedef Documentation

◆ Measurement

template<class SVT , class SQT , class TVT , class TQT >

typedef duds::data::GenericMeasurement<SVT, SQT, TVT, TQT> duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::Measurement

Definition at line 73 of file PosixClock.hpp.

Constructor & Destructor Documentation

◆ GenericPosixClock()

template<class SVT , class SQT , class TVT , class TQT >

duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::GenericPosixClock	(	clockid_t	id,
		int	os,
		Token
	)

inlineprivate

Construct a clock device for the given POSIX clock.

Parameters

id	The ID number for the POSIX clock.
os	An offset in seconds that will be applied to the time provdied by this object. A non-zero value may be needed to provide TAI, but this will result in incorrect times after another leap second is added.

Warning: On Linux, CLOCK_TAI may provide UTC. See the warning in the detail documentation of this class for more information.

Exceptions

PosixClockUnsupported The specified clock is not supported by the system.

Definition at line 168 of file PosixClock.hpp.

Member Function Documentation

◆ doSample()

template<class SVT , class SQT , class TVT , class TQT >

duds::data::int128_t duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::doSample ( ) const

inlineprivate

Samples the time and adds in an offset.

Returns: The time in nanoseconds.

Exceptions

ClockError The clock failed to be sampled.

Definition at line 120 of file PosixClock.hpp.

◆ make()

template<class SVT , class SQT , class TVT , class TQT >

static std::shared_ptr< GenericPosixClock <SVT, SQT, TVT, TQT> > duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::make	(	clockid_t	id = `CLOCK_REALTIME`,
		int	os = `0`
	)

inlinestatic

Makes a new clock device for a POSIX clock.

Parameters

id	The ID number for the POSIX clock.
os	An offset in seconds that will be applied to the time provdied by this object. A non-zero value may be needed to provide TAI, but this will result in incorrect times after another leap second is added.

Warning: On Linux, CLOCK_TAI may provide UTC. See the warning in the detail documentation of this class for more information.

Exceptions

PosixClockUnsupported The specified clock is not supported by the system.

Definition at line 197 of file PosixClock.hpp.

◆ sample() [1/2]

template<class SVT , class SQT , class TVT , class TQT >

virtual void duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::sample ( )

inlinevirtual

Samples the time from this clock stores it in the measured field of the Measurement object of the device's first sensor.

The timestamp field will be clear.

Implements duds::hardware::devices::clocks::GenericClock< SVT, SQT, TVT, TQT >.

Definition at line 208 of file PosixClock.hpp.

◆ sample() [2/2]

template<class SVT , class SQT , class TVT , class TQT >

virtual void duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::sample ( const ClockSptr & clock )

inlinevirtual

Samples the time from this clock and the given clock, then stores the measurement.

The sample from this clock will be in the measured field of the Measurement object, while the sample from the given clock will be in the timestamp field.

Parameters

clock The clock that will be sampled for the timestamp in the resulting measurement. If it is this clock, the clock must only be sampled once and the same time must be in both the measured and timestamp fields of the Measurement object. Different types may be used to hold the time in those fields so they might not evaluate as equal.

Implements duds::hardware::devices::clocks::GenericClock< SVT, SQT, TVT, TQT >.

Definition at line 218 of file PosixClock.hpp.

◆ sampleTime()

template<class SVT , class SQT , class TVT , class TQT >

virtual void duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::sampleTime ( typename Measurement::TimeSample & time )

inlinevirtual

Samples the time from the clock device without storing the result in the clock's sensor object.

Parameters

time	The place to put the sampled time.

Implements duds::hardware::devices::clocks::GenericClock< SVT, SQT, TVT, TQT >.

Definition at line 204 of file PosixClock.hpp.

◆ setSample()

template<class SVT , class SQT , class TVT , class TQT >

template<class Sample >

void duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::setSample	(	Sample &	dest,
		const duds::data::int128_t &	time
	)		const

inlineprivate

Sets the sample values based on the time sample.

Template Parameters

A	GenericSample class,

Parameters

dest	The Sample object that will be the destination for the time.
time	The time in nanoseconds.

Definition at line 137 of file PosixClock.hpp.

◆ sum()

template<class SVT , class SQT , class TVT , class TQT >

static duds::data::int128_t duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::sum ( const timespec & ts )

inlinestaticprivate

Sums the second and nanosecond fields given by the POSIX functions into a large integer.

Parameters

ts	The result from one of the POSIX clock functions.

Returns: The combined value in nanoseconds.

Definition at line 109 of file PosixClock.hpp.

◆ unambiguous()

template<class SVT , class SQT , class TVT , class TQT >

virtual bool duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::unambiguous ( ) const

inlinevirtualnoexcept

Returns true if the clock properly reports the time during a leap second.

Should the clock replay the second 59 for the leap second, then two seconds appear the same making the time ambiguous. If the clock reports 60 for the second field during a leap second, increments normally, or otherwise makes the leap second distinct, then it is unambiguous.

Ideally, ambiguous clocks should also indicate the problem in the reported quality values. For example, if a clock replays the previous second during the leap second, the accracy value should increase by a second starting one second before the leap second and continuing until after the leap second.

Implements duds::hardware::devices::clocks::GenericClock< SVT, SQT, TVT, TQT >.

Definition at line 237 of file PosixClock.hpp.

Member Data Documentation

◆ clk

template<class SVT , class SQT , class TVT , class TQT >

clockid_t duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::clk

private

The POSIX clock id.

Definition at line 102 of file PosixClock.hpp.

◆ offset

template<class SVT , class SQT , class TVT , class TQT >

int duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::offset

private

An offset in seconds that is applied to the time provided by the clock.

Definition at line 89 of file PosixClock.hpp.

◆ sampleResolution

template<class SVT , class SQT , class TVT , class TQT >

SQT duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::sampleResolution

private

The clock's resolution for use with samples.

Another value is used for the time stamp to avoid more than one convertion.

Definition at line 80 of file PosixClock.hpp.

◆ timeResolution

template<class SVT , class SQT , class TVT , class TQT >

TQT duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >::timeResolution

private

The clock's resolution for use with time stamps.

Another value is used for the sample to avoid more than one convertion.

Definition at line 85 of file PosixClock.hpp.

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

PosixClock.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

template<class SVT, class SQT, class TVT, class TQT> class duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >

Member Typedef Documentation

◆ Measurement

Constructor & Destructor Documentation

◆ GenericPosixClock()

Member Function Documentation

◆ doSample()

◆ make()

◆ sample() [1/2]

◆ sample() [2/2]

◆ sampleTime()

◆ setSample()

◆ sum()

◆ unambiguous()

Member Data Documentation

◆ clk

◆ offset

◆ sampleResolution

◆ timeResolution

template<class SVT, class SQT, class TVT, class TQT>
class duds::hardware::devices::clocks::GenericPosixClock< SVT, SQT, TVT, TQT >