Timer objects

Timer objects provide methods for tasks synchronization in reference to the specific time points or time intervals. Timers are similar to events. They are set into signaled state every time when a specified amount of time elapses and into non-signaled when timers are reset.

Timer creation and deletion

The function osCreateTimer creates a timer object. The timer can be created before system start, from an interrupt handler or by a task. During timer creation, an optional timer name may be specified. It makes tasks able to open it by osOpenTimer function. During timer creation and opening, its handle is returned. The handle is assigned by the system and it is used to discern the system objects. All operations performed on the timer except to specify its handle. The non-used timer should be closed with the osCloseHandle. Timer will be deleted when it will be closed by all tasks that opened it. More information you can find in the system objects management section.

When timers are not used, the OS_USE_TIMER constant may be set to 0, to reduce the output code.

Using a timer object

When the timer is created it is not configured and remains in the signaled state. To start the timer the osSetTimer function should be used. This time it is determined an interval that is the length of the single cycle. A single cycle is an amount of time when the timer state is changed into non-signaled. When the cycle is finished, the timer is restored to the signaled state.

Cycles can be repeated a specific number of times, that is given in PassCount parameter of osSetTimer function. After a single cycle a pass counter is incremented and to start a new cycle the timer should be reset. If the specified pass count is reached, the timer will be stopped and its state will be changed into signaled. The timer remains in this state until the next call of the osSetTimer function for specified timer. When the PassCount value is 0, the timer will be a periodical timer that will never be stopped (cycles are started every time, when timer is reset).

The timer reset can be performed by osResetTimer, or it is done automatically. Whether timer should be manual-reset or auto-reset is determined during the timer object creation.

In case of manual-reset timer the new cycle can be started with osResetTimer, and in case of auto-reset timer the new cycle is also started just after the end of the previous one. When many tasks are waiting for auto-reset timer, only one will start after the end of each cycle.

When osResetTimer resets a timer and the actual cycle is not finished yet, the cycle will be restarted. The restarting means that the cycle will be performed from the beginning. The Pass counter will be incremented only when the cycle is finished. The cycle can be restarted many times. The function fails, when is used on stopped timer.

To stop timer at once the function osCancelTimer should be used. The state of the stopped timer is changed into signaled, and all waiting tasks are released.

SpaceShadow documentation