FARGOS/VISTA Object Management Environment Core  ..
FARGOS/VISTA Object Management Environment Core Table of Contents
FARGOS Time Functions

High-performance unambiguous time representations of arbitrary granularity, cache-assisted conversions from native representation to locale-specific interpretation. More...

Classes

struct  TimeWithNanoseconds
 Structure for representing time as relative seconds and nanoseconds. More...
 
struct  TimeAsDayAndYear
 Structure for representing day-of-the-year. More...
 
struct  TimeAsHourMinSec
 Structure for representing time of day. More...
 
class  TimePointCache
 Cache locale-specific time data around a particular point in time. More...
 
class  TimePointCacheTable
 Convenience class to maintain a table of TimePointCache objects. More...
 
class  POSIXtimeInUnits< UNITS >
 Representation of UNITS-since-POSIX-epoch. This is an unambiguous time reference; there is no locale-specific attribute. More...
 
class  TimePointOfGranularity< UNITS >
 Representation of localized expanded UNITS-since-epoch. More...
 

Macros

#define _GCT_DEFAULT_ARG   = 0
 
#define USE_INTERPOLATED_TIME   1
 Set to 1 if interpolated time should be used; 0 if native clock_gettime() call should always be used. More...
 
#define CALL_TZSET()   do { } while (0) /* null statement */
 

Typedefs

typedef int(* Clock_GetTime_InterfaceFP) (struct timespec *result, bool force)
 Defines the interface for clock_gettime_via_tick() or equivalent. More...
 
typedef POSIXtimeInUnits< 1000000000U > POSIXtimeInNanoseconds
 Convenience typedef for nanosecond-resolution time. More...
 
typedef POSIXtimeInUnits< 1U > POSIXtimeInSeconds
 Convenience typedef for conventional 1-second resolution time. More...
 
typedef TimePointOfGranularity< 1000000000 > NanosecondTimePoint
 Desired standard granularity with nanosecond resolution. More...
 
typedef TimePointOfGranularity< 1 > POSIXEpochTimePoint
 Convenience typedef using conventional 1-second resolution. More...
 

Functions

const struct TimeWithNanosecondsgetCurrentTime (struct TimeWithNanoseconds *nowTime, bool force)
 Get the current time. More...
 
const struct TimeAsDayAndYeargetTodaysDate (struct TimeAsHourMinSec *nowTimeFields)
 Get today's date. More...
 
uint64_t get_CPU_ticks ()
 Return value of CPU tick register. More...
 
void set_tick_rate (double ticksPerNanosecond)
 Manually set CPU tick rate per nanoseconds. More...
 
void set_max_clock_sample_interval (uint64_t nanoseconds)
 Set maximum number of nanoseconds between forced retrieval of time from hardware clock when clock_gettime_via_tick() is called with force=false. Defaults to 1 second. NOTE: setting to 0 will have the effect of preventing any possible use of the interpolated clock. More...
 
uint64_t profile_clock_rate (bool setGlobalRate)
 Normal initialization routine to determine tick rate of underlying hardware. More...
 
int interpolated_clock_gettime (struct timespec *result, bool force)
 Get time with nanosecond precision using interpolation of elapsed CPU ticks. More...
 
int simulated_clock_gettime (struct timespec *result, bool force)
 Alternate of interpolated_clock_gettime() that can use an external RDTSC counter. More...
 
void set_external_rdtsc_variable (uint64_t *rdtsc_pointer)
 Sets the storage location from which the current time in nanoseconds will be read. More...
 
Clock_GetTime_InterfaceFP set_clock_function (Clock_GetTime_InterfaceFP func)
 Set clock routine implementation. More...
 
int clock_gettime_via_tick (struct timespec *result, bool force) OME_ALWAYS_INLINE OME_ALWAYS_OPTIMIZE("-O3")
 
template<unsigned int UNITS>
CONSTEXPR unsigned int int_digitsNeeded ()
 Via compile-time evaluation, compute log10(). Used to determine number digits required to display precision. More...
 
template<>
CONSTEXPR unsigned int int_digitsNeeded< 1 > ()
 \brief Special case for unit precision of 1–no decimal point needed More...
 
template<>
CONSTEXPR unsigned int int_digitsNeeded< 0 > ()
 Termination condition for safety. More...
 
template<typename STREAMTYPE , unsigned int UNITS>
STREAMTYPE & operator<< (STREAMTYPE &o, const TimePointOfGranularity< UNITS > &t)
 Output TimePointOfGranularity as text onto a stream-like object. More...
 
template<typename STREAMTYPE , unsigned int UNITS>
STREAMTYPE & operator<< (STREAMTYPE &o, const POSIXtimeInUnits< UNITS > pt)
 Output POSIXtimeInUnits as text onto a stream-like object. More...
 
template<unsigned int ALT_UNITS>
 POSIXtimeInUnits< UNITS >::operator POSIXtimeInUnits< ALT_UNITS > () const OME_ALWAYS_INLINE
 Cast operator to convert to alternate unit precision. More...
 

Variables

Clock_GetTime_InterfaceFP clockRoutine_function
 
TimePointCache TimePointCacheForToday
 Cached TimePoint information representing today. More...
 

Detailed Description

High-performance unambiguous time representations of arbitrary granularity, cache-assisted conversions from native representation to locale-specific interpretation.

Macro Definition Documentation

◆ _GCT_DEFAULT_ARG

#define _GCT_DEFAULT_ARG   = 0

◆ CALL_TZSET

#define CALL_TZSET ( )    do { } while (0) /* null statement */

◆ USE_INTERPOLATED_TIME

#define USE_INTERPOLATED_TIME   1

Set to 1 if interpolated time should be used; 0 if native clock_gettime() call should always be used.

Typedef Documentation

◆ Clock_GetTime_InterfaceFP

typedef int(* Clock_GetTime_InterfaceFP) (struct timespec *result, bool force)

Defines the interface for clock_gettime_via_tick() or equivalent.

Parameters
resultpoints to the storage into which the current time will be copied.
forceindicates if interpolation is disabled.

This is not an ideal interface, but it inherits its signature from the POSIX clock_gettime() function.

Return values
0indicates success
-1indicates failure

◆ NanosecondTimePoint

Desired standard granularity with nanosecond resolution.

◆ POSIXEpochTimePoint

Convenience typedef using conventional 1-second resolution.

◆ POSIXtimeInNanoseconds

Convenience typedef for nanosecond-resolution time.

◆ POSIXtimeInSeconds

Convenience typedef for conventional 1-second resolution time.

Note
This typedef is directly equivalent to a standard time_t.

Function Documentation

◆ clock_gettime_via_tick()

int clock_gettime_via_tick ( struct timespec *  result,
bool  force 
)
inline

◆ get_CPU_ticks()

uint64_t get_CPU_ticks ( )
inline

◆ getCurrentTime()

const struct TimeWithNanoseconds* getCurrentTime ( struct TimeWithNanoseconds nowTime,
bool  force 
)

Get the current time.

Parameters
nowTimepoints to a TimeWithNanoseconds structure into which a copy of the current time will be saved. If possible, the time is determined via interpolation of the CPU's current tick register value.
forceis a Boolean flag that indicates if interpolation should not be attempted and instead a kernel call made to obtain the current time.

Referenced by IO_Processor::recvConsume().

◆ getTodaysDate()

const struct TimeAsDayAndYear* getTodaysDate ( struct TimeAsHourMinSec nowTimeFields)

Get today's date.

Parameters
nowTimeFieldspoints to a TimeAsHourMinSec structure into which the current local time will be stored.
Returns
A pointer to a TimeAsDayAndYear structure populated with today's date is returned.

Referenced by makeQualifiedFileName().

◆ int_digitsNeeded()

template<unsigned int UNITS>
CONSTEXPR unsigned int int_digitsNeeded ( )
inline

Via compile-time evaluation, compute log10(). Used to determine number digits required to display precision.

◆ int_digitsNeeded< 0 >()

template<>
CONSTEXPR unsigned int int_digitsNeeded< 0 > ( )
inline

Termination condition for safety.

◆ int_digitsNeeded< 1 >()

template<>
CONSTEXPR unsigned int int_digitsNeeded< 1 > ( )
inline

\brief Special case for unit precision of 1–no decimal point needed

◆ interpolated_clock_gettime()

int interpolated_clock_gettime ( struct timespec *  result,
bool  force 
)

Get time with nanosecond precision using interpolation of elapsed CPU ticks.

Parameters
resultis a pointer to a timespec structure which will be filled in with the current time.
forceis a Boolean which indicates if the use of clock_gettime() should be used rather than attempt to calculate a time based on elapsed CPU ticks.
Note
If nanosecond precision is absolutely required, the force flag should be set to true. If microsecond precision is tolerable, the force flag can be set to false to avoid the overhead of always calling clock_gettime(). If too many CPU ticks have occurred between calls to clock_gettime(), the current time will be obtained from clock_gettime().

References OME_EXPECT_FALSE.

Referenced by LogManager::defaultGetTime().

◆ operator POSIXtimeInUnits< ALT_UNITS >()

template<unsigned int UNITS>
template<unsigned int ALT_UNITS>
POSIXtimeInUnits< UNITS >::operator POSIXtimeInUnits< ALT_UNITS >
inline

Cast operator to convert to alternate unit precision.

◆ operator<<() [1/2]

template<typename STREAMTYPE , unsigned int UNITS>
STREAMTYPE& operator<< ( STREAMTYPE &  o,
const POSIXtimeInUnits< UNITS >  pt 
)
inline

Output POSIXtimeInUnits as text onto a stream-like object.

◆ operator<<() [2/2]

template<typename STREAMTYPE , unsigned int UNITS>
STREAMTYPE& operator<< ( STREAMTYPE &  o,
const TimePointOfGranularity< UNITS > &  t 
)
inline

Output TimePointOfGranularity as text onto a stream-like object.

References TimePointOfGranularity< UNITS >::formatIntoString().

◆ profile_clock_rate()

uint64_t profile_clock_rate ( bool  setGlobalRate)

Normal initialization routine to determine tick rate of underlying hardware.

Parameters
setGlobalRateis a Boolean flag which indicates if a call to set_tick_rate() should be performed to set the discovered rate.
Returns
The number of ticks per nanosecond times 100.
Note
This routine takes a few seconds to execute; it is suitable for one-time initialization in a long-running program. For short-lived programs, like utilities used in shell scripts, the get_clock_rate_estimate() routine is a better choice.

References CLOCK_REALTIME, and first_sample_time.

◆ set_clock_function()

Set clock routine implementation.

Parameters
funcspecifies the function to be used.

The default clock source function is interpolated_clock_gettime().

Returns
The previously set clock routine is returned.

References clockRoutine_function.

◆ set_external_rdtsc_variable()

void set_external_rdtsc_variable ( uint64_t *  rdtsc_pointer)

Sets the storage location from which the current time in nanoseconds will be read.

Parameters
rdtsc_pointerpoints at the storage location to be used

As a convenience, this routine automatically selects the use of simulated_clock_gettime(). If an alternate clock source routine is desired, a subsequent call to set_clock_function() must be made.

◆ set_max_clock_sample_interval()

void set_max_clock_sample_interval ( uint64_t  nanoseconds)

Set maximum number of nanoseconds between forced retrieval of time from hardware clock when clock_gettime_via_tick() is called with force=false. Defaults to 1 second. NOTE: setting to 0 will have the effect of preventing any possible use of the interpolated clock.

◆ set_tick_rate()

void set_tick_rate ( double  ticksPerNanosecond)

Manually set CPU tick rate per nanoseconds.

References stderr, and stdout.

◆ simulated_clock_gettime()

int simulated_clock_gettime ( struct timespec *  result,
bool  force 
)

Alternate of interpolated_clock_gettime() that can use an external RDTSC counter.

Variable Documentation

◆ clockRoutine_function

Clock_GetTime_InterfaceFP clockRoutine_function

◆ TimePointCacheForToday

TimePointCache TimePointCacheForToday

Cached TimePoint information representing today.

Generated: Fri Jul 31 2020 18:19:16
Support Information