Idle Callbacks and Timeouts (XForms (Forms Library) - Version 1.2 (Rev. 4) A Graphical User Interface Toolkit for X)

Next: Global Variables and Macros, Previous: Signals, Up: Part V Overview of Main Functions [Contents][Index]

### 32.7 Idle Callbacks and Timeouts

For application programs that need to perform some light, but semi-continuous or periodic tasks, idle callback and timeouts (also `FL_TIMER` objects) can be utilized.

To register an idle callback with the system, use the following routine

    typedef int (*FL_APPEVENT_CB)(XEvent *, void *);
    FL_APPEVENT_CB fl_set_idle_callback(FL_APPEVENT_CB callback,
                                        void *user_data);

where `callback` is the function that will get called whenever the main loop is idle. The time interval between invocations of the idle callback can vary considerably depending on interface activity and other factors. A range between 50 and 300 msec should be expected. While the idle callback is executed it won’t be called again (i.e., no call of any XForms function from within the idle callback function will call the idle callback function), so it does not need to be reentrant.

It is possible to change what the library considers to be "idle" with the following function:

    void fl_set_idle_delta(long msec);

Here `msec` is the minimum time interval of inactivity after which the main loop is considered to be in an idle state. However it should be noted that under some conditions an idle callback can be called sooner than the minimum interval.

If the timing of the idle callback is of concern, timeouts should be used. Timeouts are similar to idle callbacks but with the property that the user can specify a minimum time interval that must elapse before the callback is called. The precision of timeouts tends to be quite a bit better than that of idle callbacks since they internally get prefered treatent. To register a timeout callback, the following routine can be used

    typedef void (*FL_TIMEOUT_CALLBACK)(int, void *);
    int fl_add_timeout(long msec, FL_TIMEOUT_CALLBACK callback,
                       void *data);

The function returns the timeout ID (note: the function will not return 0 and -1, so the application can use these values to mark invalid or expired timeouts). When the time interval specified by the `msec` argument (in milli-second) is elapsed, the timeout is removed and the callback function is called with the timeout ID as the first argument. Although a timeout offers some control over the timing, due to performance and CPU load compromises, while the resolution can be better than 10 ms under favourable conditions, it can also be much worse, occasionally up to 150 ms.

To remove a timeout before it triggers, use the following routine

    void fl_remove_timeout(int id);

where `id` is the timeout ID returned by `fl_add_timeout()`. See Timer Object, for the usage of `FL_TIMER` object. For tasks that need more accurate timing the use of signal should be considered.

Next: Global Variables and Macros, Previous: Signals, Up: Part V Overview of Main Functions [Contents][Index]