58.7 Timers for Delayed Execution

You can set up a timer to call a function at a specified future time.

Function: add-timeout secs function object &optional resignal

This function adds a timeout, to be signaled after the timeout period has elapsed. secs is a number of seconds, expressed as an integer or a float. function will be called after that many seconds have elapsed, with one argument, the given object. If the optional resignal argument is provided, then after this timeout expires, add-timeout will automatically be called again with resignal as the first argument.

This function returns an object which is the id of this particular timeout. You can pass that object to disable-timeout to turn off the timeout before it has been signalled.

The number of seconds may be expressed as a floating-point number, in which case some fractional part of a second will be used. Caveat: the usable timeout granularity will vary from system to system.

Adding a timeout causes a timeout event to be returned by next-event, and the function will be invoked by dispatch-event, so if SXEmacs is in a tight loop, the function will not be invoked until the next call to sit-for or until the return to top-level (the same is true of process filters).

WARNING: if you are thinking of calling add-timeout from inside of a callback function as a way of resignalling a timeout, think again. There is a race condition. That’s why the resignal argument exists.

NOTE: In FSF Emacs, this function is called run-at-time and has different semantics.

Function: disable-timeout id

Cancel the requested action for id, which should be a value previously returned by add-timeout. This cancels the effect of that call to add-timeout; the arrival of the specified time will not cause anything special to happen.

NOTE: In FSF Emacs, this function is called cancel-timer.