epicsGeneralTime.h File Reference

The generalTime framework provides a mechanism for several time providers to be present within the system. More...

#include "libComAPI.h"

Include dependency graph for epicsGeneralTime.h:

Go to the source code of this file.

Macros
#define	NUM_TIME_EVENTS   256
	The number of time events that are validated. More...
#define	generalTimeCurrentTpName   generalTimeCurrentProviderName
	Old name provided for backwards compatibility.
#define	generalTimeEventTpName   generalTimeEventProviderName
	Old name provided for backwards compatibility.

Functions
LIBCOM_API void	generalTime_Init (void)
	Initialize the framework. More...
LIBCOM_API int	installLastResortEventProvider (void)
	Install a Time Event time provider that returns the current time for any Time event number. More...
LIBCOM_API void	generalTimeResetErrorCounts (void)
	Reset the internal counter of the number of times the time returned was earlier than when previously requested. More...
LIBCOM_API int	generalTimeGetErrorCounts (void)
	Return the internal counter of the number of times the time returned was earlier than when previously requested. More...
LIBCOM_API const char *	generalTimeCurrentProviderName (void)
	Return the nume of the provider that last returned a valid current time, or NULL if none. More...
LIBCOM_API const char *	generalTimeEventProviderName (void)
	Return the name of the provider that last returned a valid Time Event time, or NULL of none. More...
LIBCOM_API const char *	generalTimeHighestCurrentName (void)
	Return the name of the registered current time provider that has the highest priority. More...
LIBCOM_API long	generalTimeReport (int interest)
	Provide information about the installed providers and their current best times. More...

Detailed Description

There are two types of time provider, one type provides the current wall-clock time, the other provides Event System times. Each time provider is registered with a priority, and installed providers are queried in priority order whenever a time is requested, until one returns successfully. Thus there is a fallback from higher priority providers (smaller value of priority) to lower priority providers (larger value of priority) if the highest priority ones fail. Each architecture has a "last resort" provider, installed at priority 999, usually based on the system clock, which is used in the absence of any other provider.

Targets running VxWorks and RTEMS have an NTP provider installed at priority 100.

Registered providers may also add an interrupt-safe routine that will be called from the epicsTimeGetCurrentInt() or epicsTimeGetEventInt() API routines. These interfaces cannot check the priority queue, so will only succeed if the last-used provider has registered a suitable routine.

Note

There are two interfaces to this framework, epicsGeneralTime.h for consumers to obtain a time and query the framework, and generalTimeSup.h for providers that can supply timestamps.

Definition in file epicsGeneralTime.h.

Macro Definition Documentation

#define NUM_TIME_EVENTS   256

Time Events numbered 0 through (NUM_TIME_EVENTS-1) are validated by code in epicsGeneralTime.c that tests for advancing timestamps and enforces that restriction.

Note

Event numbers greater than or equal to NUM_TIME_EVENTS are now allowed if supported by a custom time provider which should provide its own advancing timestamp validation.

Definition at line 57 of file epicsGeneralTime.h.

Function Documentation

LIBCOM_API void generalTime_Init

(

void

)

This routine is called automatically by any function that requires the framework. It does not need to be called explicitly.

LIBCOM_API int installLastResortEventProvider

(

void

)

Note

This is optional as it is site policy whether the last resort for a Time Event time in the absence of any working provider should be a failure, or the current time.

LIBCOM_API void generalTimeResetErrorCounts

(

void

)

Used by device support for binary out record with:

DTYP = "General Time"
OUT = "@RSTERRCNT"

LIBCOM_API int generalTimeGetErrorCounts

(

void

)

Used by device support for longin record with:

DTYP = "General Time"
INP = "@GETERRCNT"

Returns

Reset error counts

LIBCOM_API const char* generalTimeCurrentProviderName

(

void

)

Used by stringin device support with:

DTYP = "General Time"
INP = "@BESTTCP"

Returns

Provider name

LIBCOM_API const char* generalTimeEventProviderName

(

void

)

Used by stringin device support with:

DTYP = "General Time"
INP = "@BESTTEP"

Returns

Provider name

LIBCOM_API const char* generalTimeHighestCurrentName

(

void

)

Used by stringin device support with:

DTYP = "General Time"
INP = "@TOPTCP"

Returns

Provider name

LIBCOM_API long generalTimeReport

(

int

interest

)

Parameters

interest

Desired interest level to report