Time

This section describes the services, which are provided by Circle regarding time. This concerns:

The current non-consecutive system time (local and UTC) in seconds since 1970-01-01 00:00:00
The timezone, expressed in minutes +/- from UTC
The current consecutive system up-time in seconds
A coarse grained, consecutive system tick counter in 1/100 seconds
A fine grained, consecutive system tick counter in microseconds
A possibly greater number of kernel timers, which elapse after a given number of coarse system ticks, resulting in a callback function to be executed
Up to four periodic timer handlers, called 100 times per second
Delaying program execution for a number of milli-, micro- or nanoseconds
One fine grained periodic user timer, executing a callback function in an interval down to microseconds
Converting time values (seconds since 1970-01-01 00:00:00) into time components (i.e. year, month, day, hour, minute, seconds) or reversed or into a string representation

These services are implemented in the classes CTimer, CUserTimer and CTime.

Note

“Consecutive” in this context means, that the time does never “jump”. For example the current local system time may be updated, while the system is running, from an external time source (e.g. NTP server). This may cause a step back or forward in time. Consecutive time sources ensure, that this does not happen, which is important, e.g. when a program waits for an amount of time to pass, by calculating the difference between the current time and a start time.

CTimer

This class is the main provider of time services in Circle.

#include <circle/timer.h>

class CTimer

There is exactly one or no instance of this class in the system. Only relatively simple programs can work without an instance of CTimer. The only static timer functions, which can be called before this instance of CTimer is created and initialized, are:

static unsigned CTimer::GetClockTicks(void): Returns the current value of the fine grained, consecutive system tick counter in microseconds. It does not necessarily start at zero and may overrun after a while. It continues to count from zero then.

CLOCKHZ: Frequency of the fine grained, consecutive system tick counter (1000000).

static void CTimer::SimpleMsDelay(unsigned nMilliSeconds)

static void CTimer::SimpleusDelay(unsigned nMicroSeconds): Delay the program execution by the given amount of time.

Initialization

CTimer::CTimer(CInterruptSystem *pInterruptSystem): Creates the instance of CTimer.

boolean CTimer::Initialize(void): Initializes and activates the system timer services. Returns TRUE on success.

Note

CTimer::Initialize() may generate log messages. Therefore it requires an initialized instance of the class CLogger in the system.

CTimer::Initialize() determines the CPU speed by calibrating a delay loop by default. This can be suppressed with the system option NO_CALIBRATE_DELAY (e.g. to reduce boot time).

static CTimer *CTimer::Get(void): Returns a pointer to the single instance of CTimer.

Local time and UTC

boolean CTimer::SetTimeZone(int nMinutesDiff)

int CTimer::GetTimeZone(void) const: Sets or returns the current timezone in minutes difference to UTC.

boolean CTimer::SetTime(unsigned nTime, boolean bLocal = TRUE): Sets the current system time in seconds since 1970-01-01 00:00:00. The time is given according to the timezone by default or in UTC, if the parameter bLocal is FALSE. Returns TRUE, if the time is valid.

unsigned CTimer::GetTime(void) const

unsigned CTimer::GetLocalTime(void) const

boolean CTimer::GetLocalTime(unsigned *pSeconds, unsigned *pMicroSeconds): Returns the current local system time in seconds since 1970-01-01 00:00:00. The third variant always returns TRUE.

unsigned CTimer::GetUniversalTime(void) const

boolean CTimer::GetUniversalTime(unsigned *pSeconds, unsigned *pMicroSeconds): Returns the current universal system time (UTC) in seconds since 1970-01-01 00:00:00. This value may be invalid, if the time was not set and the timezone difference is greater than zero. The third variant returns FALSE in this case.

CString *CTimer::GetTimeString(void): Returns the current local system time as a string (format "[MMM dD ]HH:MM:SS.ss"). Returns zero, when Initialize() has not been called yet. The resulting CString object must be deleted by the caller.

Coarse system tick and up-time

unsigned CTimer::GetTicks(void) const: Returns the current value of the coarse grained, consecutive system tick counter in 1/100 seconds units.

Note

CTimer::GetTicks() reads the ticks variable only and returns quickly. CTimer::GetClockTicks() reads a hardware register (on Raspberry Pi 1 and Zero) or has to do some calculations (in 64-bit mode). Therefore calling CTimer::GetTicks() does normally cost less CPU cycles. You should use CTimer::GetTicks(), if its precision is sufficient for your purpose, or CTimer::GetClockTicks() otherwise.

HZ: Frequency of the coarse grained, consecutive system tick counter (100).

unsigned CTimer::GetUptime(void) const: Returns the system up-time in seconds, since the class CTimer has been initialized.

Kernel timers

TKernelTimerHandle CTimer::StartKernelTimer(unsigned nDelay, TKernelTimerHandler *pHandler, void *pParam = 0, void *pContext = 0): Start a kernel timer, which elapses after nDelay coarse system ticks (100 Hz). Call pHandler on elapse with the given values of pParam and pContext. Returns a handle to the started timer. TKernelTimerHandler has the following prototype:

void TKernelTimerHandler (TKernelTimerHandle hTimer, void *pParam, void *pContext);

MSEC2HZ(msecs): A macro, which converts milliseconds into coarse system ticks.

void CTimer::CancelKernelTimer(TKernelTimerHandle hTimer): Cancel (remove) the kernel timer given with the handle hTimer. It will not elapse any more.

Periodic timers

void CTimer::RegisterPeriodicHandler(TPeriodicTimerHandler *pHandler): Register a periodic timer handler, which is called HZ times (100) per second. Up to four handlers are allowed. TPeriodicTimerHandler has the following prototype:

void TPeriodicTimerHandler (void);

Update time handler

void CTimer::RegisterUpdateTimeHandler(TUpdateTimeHandler *pHandler): Register a handler, which is called when SetTime() is invoked. This allows the application to apply additional checks, before the new time is set.

typedef boolean TUpdateTimeHandler(unsigned nNewTime, unsigned nOldTime): The handler gets the nNewTime to be set and the current nOldTime in seconds since 1970-01-01 00:00:00 UTC, and returns TRUE, if the new time can be set or FALSE, if the time is invalid. The call to SetTime() is ignored then.

Delay

void CTimer::MsDelay(unsigned nMilliSeconds)

void CTimer::usDelay(unsigned nMicroSeconds)

void CTimer::nsDelay(unsigned nNanoSeconds): Delay the program execution by the given amount of time. These functions should be used, when an instance of CTimer is available in the system (i.e. instead of SimpleMsDelay() and SimpleusDelay()).

Note

The actual delay may deviate from the requested value to some degree, but is never smaller than requested.

CUserTimer

This class implements a fine grained, user programmable interrupt timer. It uses the system timer 1 hardware, which must not be used for other purposes in the application then.

#include <circle/usertimer.h>

class CUserTimer

CUserTimer::CUserTimer(CInterruptSystem *pInterruptSystem, TUserTimerHandler *pHandler, void *pParam = 0, boolean bUseFIQ = FALSE): Creates an instance of CUserTimer. Only one is allowed. pHandler is a pointer to the callback function, which is executed, when the user timer elapses. By default the IRQ is used to trigger the interrupt. bUseFIQ has to be set to TRUE to use the FIQ instead (e.g. for high frequencies). TUserTimerHandler has this prototype:

void TUserTimerHandler (CUserTimer *pUserTimer, void *pParam);

boolean CUserTimer::Initialize(void): Initializes the user timer. Returns TRUE on success. Automatically starts the user timer with a delay of 1 hour.

void CUserTimer::Stop(void): Stops the user timer. It has to be re-initialized to be used again.

void CUserTimer::Start(unsigned nDelayMicros): (Re-)starts the user timer to elapse after the given number of microseconds (> 1). This method must be called from the user timer handler to a set new delay. It can be called on a running user timer to update the delay.

USER_CLOCKHZ: Frequency of the user timer (1000000).

CTime

This class converts the time into different representations.

#include <circle/time.h>

type time_t: Time representation (normally) in seconds since 1970-01-01 00:00:00.

class CTime

CTime::CTime(void): Creates an instance of CTime.

CTime::CTime(const CTime &rSource): Creates an instance of CTime from a different CTime object (copy constructor).

void CTime::Set(time_t Time): Sets the time to the number seconds since 1970-01-01 00:00:00.

boolean CTime::SetTime(unsigned nHours, unsigned nMinutes, unsigned nSeconds): Sets the time from its components hours (0-23), minutes (0-59) and seconds (0-59). Returns TRUE if the time is valid.

boolean CTime::SetDate(unsigned nMonthDay, unsigned nMonth, unsigned nYear): Sets the date from its components month-day (1-31), month (1-12) and year (1970-). Returns TRUE if the date is valid.

time_t CTime::Get(void) const: Returns the time in the number seconds since 1970-01-01 00:00:00.

unsigned CTime::GetSeconds(void) const

unsigned CTime::GetMinutes(void) const

unsigned CTime::GetHours(void) const

unsigned CTime::GetMonthDay(void) const

unsigned CTime::GetMonth(void) const

unsigned CTime::GetYear(void) const: Return the components of the time. See SetTime() and SetDate() for the possible value ranges.

unsigned CTime::GetWeekDay(void) const: Returns the weekday (0-6, Sun-Sat).

const char *CTime::GetString(void): Returns a string representation of the time. The format is "WWW MMM DD HH:MM:SS YYYY", where “WWW” is the weekday.