The IDL_TimerSet() function registers a timer request. IDL timer requests are one- shot timers. To have a timer go off repeatedly, your callback function must make a new request each time it is called to set up the next timer.

void IDL_TimerSet(length, callback, from_callback, context)

where:

length

The length of time to delay before issuing the alarm, in microseconds. Other activity on the system, overhead incurred in managing the timers, and non-realtime attributes of the operating system can cause the actual duration of the timer to be longer than requested.

callback

Under UNIX:

  • If callback is non-NULL, the timer request is queued and IDL_TimerSet() returns immediately. When the alarm is due, the function pointed at by callback is called.
  • If callback is NULL (and not from_callback), the request is queued and IDL_TimerSet() blocks until the requested time expires.

Note: When called, the callback function will be running in signal scope, meaning that it has been called from a signal handler running asynchronously from the rest of the program. There are significant restrictions on what code running in signal scope is allowed to do. Most common C library functions (such as printf()) are disallowed. Consult a book on UNIX programming or your system documentation for details.

Under Windows, callback should always be NULL. IDL_TimerSet() does not support non-blocking timers on these platforms.

from_callback

Set this argument to TRUE if this invocation is from a callback function previously set up via a call to IDL_TimerSet(). Set this argument to FALSE if this is the first invocation. In other words, this argument should only be TRUE if you call IDL_TimerSet() from within a timer callback.

context

This argument is a pointer to a variable of type IDL_TIMER_CONTEXT, an opaque IDL data type that uniquely identifies a timer request. If this is a top level request (if from_callback is FALSE), the context pointed at will be assigned a unique value that identifies the request.

If this request is coming from within a timer callback in order to make another request on the same timer, the context pointed at should contain the value from the previous request.

If context is NULL, no context value is returned.

Note: It is an error to queue more than one request using the same callback. The results are undefined.

For the timer module to perform adequately, the time request must be large compared to the run-time of the called function. Re-queuing an extremely short request repeatedly will cause any other requests to starve.