NewAsyncTimer

int NewAsyncTimer (double interval, int count, int initialState, void *eventFunction, void *callbackData);

Purpose

This function creates a new asynchronous timer and returns a timer ID used to specify the timer in subsequent function calls.

Note  All asynchronous callback functions are executed in a common separate thread from the main process. The following issues must be considered:

  • Any variables referenced or changed by the asynchronous callback are not protected from being referenced or changed by another thread, such as the main process thread. You can use the multithreading utility functions in the Utility Library to protect the variables that are accessed from more than one thread.
  •      
  • A call to create or discard an asynchronous timer will not complete (will block) until all outstanding asynchronous callbacks return.
Caution  The asynchronous timers are implemented using the Windows multimedia timer functions. Therefore, depending on the model of the machine you are working on, the minimum interval value that you can use may differ. If this interval is smaller than the resolution allowed by your system, then unpredictable results may occur. This behavior typically occurs when you set the interval below 10ms.

Parameters

Input
Name Type Description
interval double Specifies the wait interval between timer events (in seconds).
count integer Specifies the number of timer events to be generated before the timer is automatically discarded.

A negative value will make the timer generate events until it is discarded by a call to DiscardAsyncTimer or suspended by a call to SuspendAsyncTimerCallbacks.
Note  A value of zero will return an error.
initialState integer Specifies whether the timer should be running (generating timer events) or suspended once it is created.

The state of a individual timer can be changed by calling SetAsyncTimerAttribute.

The state of all timers can be changed as a whole with calls to ResumeAsyncTimerCallbacks or SuspendAsyncTimerCallbacks.
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 control's 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. Callback data defined by the user also is passed to the event function.

Note  The asynchronous callback function is executed in a separate thread from the the main process. Any variables referenced by or changed by the asynchronous callback are not protected from being referenced or changed by another thread, such as the main process thread. You can use the multithreading utility functions in the Utility Library to protect the variables that are accessed from more than one thread.
callbackData void * Specifies a pointer to user-defined data passed to the event function.

Return Value

Name Type Description
timerID integer Specifies the ID that is used to reference this timer in subsequent function calls. Negative values indicate that an error occurred.

Return Values:
xxThe timer ID (success).
–1The system failed to allocate a timer.
–2No more IDs are available to assign to a new timer.
–3Not enough memory left for this operation.
–4The timer with the given ID was not found.
–5Initialization with a call to NewAsyncTimer was not done.
–6An internal error occurred.
–7The value of a parameter passed to this function was invalid.