NewAsyncTimer
int NewAsyncTimer (double interval, int count, int initialState, void *eventFunction, void *callbackData);
Purpose
Creates a new asynchronous timer and returns a timer ID you can use to identify the timer in subsequent function calls.
NewAsyncTimer creates asynchronous timers that run in threads with priority THREAD_PRIORITY_HIGHEST (2).
RT NewAsyncTimer creates asynchronous timers that run in threads with a priority of 2. To specify a different priority, call NewAsyncTimerWithPriority.
 |
Note You can use asynchronous timers on Windows, real-time (RT), and Linux operating systems. |
Asynchronous timer tick events can accumulate when the library thread responsible for generating timer tick events is unable to call the callback function at the specified interval. For example, the library thread could fall behind if the time to complete the callback function is longer than the specified interval. When asynchronous timer tick events accumulate, the library thread dispatches the accumulated events as quickly as possible. In this case, the interval at which the library thread generates events might be shorter than the interval you specified when you created the asynchronous timer. If the cause for the accumulated events is temporary and the library thread finishes generating the accumulated events, the library thread resumes generating events at the interval you specified when you created the asynchronous timer.
On Windows, all asynchronous callback functions share a common thread. As a result, the duration of any asynchronous callback function can have an impact on all other asynchronous timers, possibly causing timer tick events to accumulate.
Parameters
| Input | ||||
| Name | Type | Description | ||
| interval | double | Specifies the wait interval, in seconds, between timer events. The minimum interval value that you can use depends on the system that is running the asynchronous timer. If the interval is smaller than the asynchronous timer resolution supported by your system, LabWindows/CVI uses an interval equal to the resolution supported by the system. Call GetAsyncTimerResolution to get the asynchronous timer resolution for your system. |
||
| count | int | Specifies the number of timer events to be generated before the timer is automatically discarded. If you pass a negative value, the timer will generate events until it is discarded by a call to DiscardAsyncTimer or suspended by a call to SuspendAsyncTimerCallbacks.
|
||
| initialState | int | Specifies whether the timer is enabled or disabled when it is created. You can specify one of the following values:
|
||
| eventFunction | void * | Specifies the name of the user function that processes the callback. This event function (type AsyncTimerCallbackPtr) takes the same form as the timer callback function: int CVICALLBACK FunctionName (int reserved, int timerId, int event, void *callbackData, int eventData1, int eventData2); The first parameter of the event function is reserved. timerId is the timer that caused the callback. The types of events generated are EVENT_TIMER_TICK and EVENT_DISCARD. eventData1 is a pointer to a double that represents the current time in seconds and is relative to the start of the first timer event. eventData2 is a pointer to a double that represents the time that has elapsed since the last call to the timer callback. The elapsed time is set to zero if the callback has not been called previously. The resolution of eventData1 and eventData2 matches the resolution of the asynchronous timer. Callback data defined by the user also is passed to the event function. |
||
| callbackData | void * | Specifies a pointer to user-defined data passed to the event function. | ||
Return Value
| Name | Type | Description | ||||||||||||||||||||
| timerID | int | Specifies the ID that is used to reference the timer in subsequent
function calls. Negative values indicate that an error occurred.
|
Additional Information
Library: Asynchronous Timers
Include file: toolbox\asynctmr.h
LabWindows/CVI compatibility: LabWindows/CVI 5.0 and later
Example
Refer to toolbox\asyncdem.cws for an example of using the NewAsyncTimer function.