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:

This graph shows which files directly or indirectly include 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. More...

#define	generalTimeEventTpName generalTimeEventProviderName
	Old name provided for backwards compatibility. More...

Functions
LIBCOM_API void	generalTime_Init (void)
	Initialise 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

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

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 generalTimeCurrentTpName generalTimeCurrentProviderName

Old name provided for backwards compatibility.

Definition at line 140 of file epicsGeneralTime.h.

#define generalTimeEventTpName generalTimeEventProviderName

Old name provided for backwards compatibility.

Definition at line 142 of file epicsGeneralTime.h.

#define NUM_TIME_EVENTS 256

The number of time events that are validated.

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 56 of file epicsGeneralTime.h.

Function Documentation

LIBCOM_API void generalTime_Init ( void )

Initialise the framework.

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

Definition at line 99 of file epicsGeneralTime.c.

 {
     epicsThreadOnce(&onceId, generalTime_InitOnce, NULL);
 }

LIBCOM_API const char* generalTimeCurrentProviderName ( void )

Return the nume of the provider that last returned a valid current time, or NULL if none.

Used by stringin device support with:

1 DTYP = "General Time"

2 INP = "@BESTTCP"

Returns: Provider name

Definition at line 638 of file epicsGeneralTime.c.

 {
     if (gtPvt.lastTimeProvider)
         return gtPvt.lastTimeProvider->name;
     return NULL;
 }

LIBCOM_API const char* generalTimeEventProviderName ( void )

Return the name of the provider that last returned a valid Time Event time, or NULL of none.

Used by stringin device support with:

1 DTYP = "General Time"

2 INP = "@BESTTEP"

Returns: Provider name

Definition at line 645 of file epicsGeneralTime.c.

 {
     if (gtPvt.lastEventProvider)
         return gtPvt.lastEventProvider->name;
     return NULL;
 }

LIBCOM_API int generalTimeGetErrorCounts ( void )

Return the internal counter of the number of times the time returned was earlier than when previously requested.

Used by device support for longin record with:

1 DTYP = "General Time"

2 INP = "@GETERRCNT"

Returns: Reset error counts

Definition at line 630 of file epicsGeneralTime.c.

 {
     int key = epicsInterruptLock();
     int errors = gtPvt.ErrorCounts;
     epicsInterruptUnlock(key);
     return errors;
 }

LIBCOM_API const char* generalTimeHighestCurrentName ( void )

Return the name of the registered current time provider that has the highest priority.

Used by stringin device support with:

1 DTYP = "General Time"

2 INP = "@TOPTCP"

Returns: Provider name

Definition at line 652 of file epicsGeneralTime.c.

 {
     gtProvider *ptp;
 
     epicsMutexMustLock(gtPvt.timeListLock);
     ptp = (gtProvider *)ellFirst(&gtPvt.timeProviders);
     epicsMutexUnlock(gtPvt.timeListLock);
     return ptp ? ptp->name : NULL;
 }

LIBCOM_API long generalTimeReport ( int interest )

Provide information about the installed providers and their current best times.

Parameters

interest Desired interest level to report

Definition at line 529 of file epicsGeneralTime.c.

 {
     int items;
 
     if (onceId == EPICS_THREAD_ONCE_INIT) {
         printf("General time framework not yet initialized.\n");
         return epicsTimeOK;
     }
 
     printf("Backwards time errors prevented %u times.\n\n",
         generalTimeGetErrorCounts());
 
     /* Use an output buffer to avoid holding mutexes during printing */
 
     printf("Current Time Providers:\n");
     epicsMutexMustLock(gtPvt.timeListLock);
     if ((items = ellCount(&gtPvt.timeProviders))) {
         gtProvider *ptp;
         char *message;     /* Temporary output buffer */
         char *pout;
 
         message = calloc(items, 80 * 2); /* Each provider needs 2 lines */
         if (!message) {
             epicsMutexUnlock(gtPvt.timeListLock);
             printf("Out of memory\n");
             return S_time_noMemory;
         }
 
         pout = message;
 
         for (ptp = (gtProvider *)ellFirst(&gtPvt.timeProviders);
              ptp; ptp = (gtProvider *)ellNext(&ptp->node)) {
             pout += sprintf(pout, "    \"%s\", priority = %d\n",
                 ptp->name, ptp->priority);
             if (level) {
                 epicsTimeStamp tempTS;
                 if (ptp->get.Time(&tempTS) == epicsTimeOK) {
                     char tempTSText[40];
                     epicsTimeToStrftime(tempTSText, sizeof(tempTSText),
                         "%Y-%m-%d %H:%M:%S.%06f", &tempTS);
                     pout += sprintf(pout, "\tCurrent Time is %s.\n",
                         tempTSText);
                 } else {
                     pout += sprintf(pout, "\tCurrent Time not available\n");
                 }
             }
         }
         epicsMutexUnlock(gtPvt.timeListLock);
         puts(message);
         free(message);
     } else {
         epicsMutexUnlock(gtPvt.timeListLock);
         printf("\tNo Providers registered.\n");
     }
 
     printf("Event Time Providers:\n");
     epicsMutexMustLock(gtPvt.eventListLock);
     if ((items = ellCount(&gtPvt.eventProviders)))
     {
         gtProvider *ptp;
         char *message;     /* Temporary output buffer */
         char *pout;
 
         message = calloc(items, 80);     /* Each provider needs 1 line, */
         if (!message) {
             epicsMutexUnlock(gtPvt.eventListLock);
             printf("Out of memory\n");
             return S_time_noMemory;
         }
 
         pout = message;
 
         for (ptp = (gtProvider *)ellFirst(&gtPvt.eventProviders);
              ptp; ptp = (gtProvider *)ellNext(&ptp->node)) {
             pout += sprintf(pout, "    \"%s\", priority = %d\n",
                 ptp->name, ptp->priority);
         }
         epicsMutexUnlock(gtPvt.eventListLock);
         puts(message);
         free(message);
     }
     else
     {
         epicsMutexUnlock(gtPvt.eventListLock);
         printf("\tNo Providers registered.\n");
     }
 
     return epicsTimeOK;
 }

LIBCOM_API void generalTimeResetErrorCounts ( void )

Reset the internal counter of the number of times the time returned was earlier than when previously requested.

Used by device support for binary out record with:

1 DTYP = "General Time"

2 OUT = "@RSTERRCNT"

Definition at line 623 of file epicsGeneralTime.c.

 {
     int key = epicsInterruptLock();
     gtPvt.ErrorCounts = 0;
     epicsInterruptUnlock(key);
 }

LIBCOM_API int installLastResortEventProvider ( void )

Install a Time Event time provider that returns the current time for any Time event number.

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.

Definition at line 520 of file epicsGeneralTime.c.

 {
     return generalTimeEventTpRegister("Last Resort Event",
         LAST_RESORT_PRIORITY, lastResortGetEvent);
 }

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation