Timer Management Module (TMR_)

#include "tmr.h"

void
TMR_init(OS_Uint16 numberOfTimers, OS_Uint16 millisecondsPerTick);

ReturnCode
TMR_start(OS_Uint32 milliseconds,
          void * hUserData1,
          void * hUserData2,
          ReturnCode (* pfHandler)(void * hTimer,
                                   void * hUserData1,
                                   void * hUserData2),
          void ** phTimer);

void *
TMR_create(LgInt milliseconds, Int (*pfHandler)());

void
TMR_stop(void * hTimer);

void
TMR_cancel(void * hTimer);

ReturnCode
TMR_processQueue(OS_Boolean * pProcessedSomething);

void
TMR_poll(void);

void
TMR_startClockInterruptPlus(void (* pfHandler)(void));

SuccFail
TMR_startClockInterrupt(Int period);

void
TMR_stopClockInterrupt(void);

void
TMR_setLocalDataSize(OS_Uint16 size);

OS_Uint16
TMR_getLocalDataSize(void);

void *
TMR_getData(void * hTimer);

void *
TMR_getDesc(void * pLocalData);

OS_Uint32
TMR_diff(OS_Uint32 time1, OS_Uint32 time2);

Many data communication protocols rely on the availability of timer facilities, yet these facilities are inherently environment dependent. The TMR_ module defines a model and an interface for providing timer facilities to Open C Layers, regardless of the environment, provided that all implementations of the TMR_ module conform to the interface defined here.

A timer is created through the TMR_start() or TMR_create() facilities. Unless the timer is canceled through the TMR_stop() or TMR_cancel() facilities it will expire at the specified time. The time for the expiration of a timer is specified in millisecond relative to now. When the timer expires, the TMR_ module schedules a user-supplied function for synchronous invocation. The granularity of timers is environment specific. Timers created through TMR_start() or TMR_create() are not "sticky". If a periodic timer is desired it must be repeatedly re-created.

Starting a Timer

ReturnCode
TMR_start(OS_Uint32 milliseconds,
          void * hUserData1,
          void * hUserData2,
          ReturnCode (* pfHandler)(void * hTimer,
                                   void * hUserData1,
                                   void * hUserData2),
          void ** phTimer);

void *
TMR_create(LgInt milliseconds, Int (*pfHandler)());

TMR_start() and TMR_create() both start a new timer and arrange, via the scheduler module (SCH_), for the synchronous invocation of the user-supplied function pfHandler when this timer expires.

A limited amount of user data can be associated with each timer. A pointer to the user specific data buffer is passed as a parameter to pfHandler, i.e.

(*pfHandler)(tmrData);

The timer expiration time is specified in absolute milliseconds relative to present. The time argument must be positive; a negative value or a value of 0 is illegal.

Stopping a Timer

void
TMR_stop(void * hTimer);

void
TMR_cancel(void * hTimer);

TMR_stop() and TMR_cancel() both halt an active timer and remove it from the timer queue. hTimer is a timer descriptor previously obtained by TMR_create() or TMR_start().

Associating User Data with Timers

void *
TMR_getData(void * hTimer);

void *
TMR_getDesc(void * pLocalData);

A limited amount of user data can be associated with each timer. The size limit of the user data is implementation specific. Likewise, the semantics of this data are specific to the user and irrelevant to the timer module.

The location of the user data may be obtained by the TMR_getData() facility.

Conversely, given a pointer to some user data, the timer associated with that data can be obtained by the TMR_getDesc() facility.

Implementation Specific Interfaces

void
TMR_init(OS_Uint16 numberOfTimers, OS_Uint16 millisecondsPerTick);

void
TMR_startClockInterruptPlus(void (* pfHandler)(void));

SuccFail
TMR_startClockInterrupt(Int period);

void
TMR_stopClockInterrupt(void);

ReturnCode
TMR_processQueue(OS_Boolean * pProcessedSomething);

void
TMR_poll(void);

The timing mechanisms that underlie the TMR_ module are implementation-specific. For instance, in unhosted environments, the TMR_ module can be implemented based on a periodic interrupt. On the other hand, in hosted environments, the TMR_ module can be implemented based on operating system-supplied timing mechanisms such as the Unix signal() facility. In either case the interface described below can be used for initialization and integration of the TMR_ module.

• Initialization of the TMR_ module is performed through TMR_init(), which must be invoked prior to using any of the other timer module facilities. numberOfTimers specifies the maximum number of timers that may be in use at any one moment. millisecondsPerTick specifies how often a clock "tick" is generated.

• TMR_startClockInterruptPlus() and TMR_startClockInterrupt() both start the timer module clock tick. On unhosted systems this has the effect of enabling the TMR_ module clock interrupt source. TMR_startClockInterruptPlus() allows the user to specify the routine that is called when a clock tick occurs but uses a built-in number of milliseconds per tick. TMR_startClockInterrupt() uses a predefined service routine but allows the user to specify the number of milliseconds per tick.

• TMR_stopClockInterrupt() disables the clock tick. On unhosted systems this has the effect of disabling the TMR_ module interrupt source.

• TMR_poll() or TMR_processQueue() must regularly be called to process expired timers. TMR_processQueue() provides additional information about the status of its completion via the Boolean parameter pProcessedSomething. In both hosted and unhosted systems, TMR_poll() or TMR_processQueue() are scheduled for execution by the clock tick service routine via the OCP scheduler (SCH_) facility SCH_submit(). It is during the execution of these facilities that the user functions themselves are invoked.

• TMR_clock() is the entry point to the clock tick handler routine.

Example Usage

The following code fragment demonstrates the use of the timer facilities.

Click here to see the complete codes.

/* Call Graph for the example program */