GNU Emacs Lisp Reference Manual

34.7: Timers for Delayed Execution

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

Function: run-at-time time repeat function &rest args

This function arranges to call function with arguments args at time time. The argument function is a function to call later, and args are the arguments to give it when it is called. The time time is specified as a string.

Absolute times may be specified in a wide variety of formats; The form `hour:min:sec timezone month/day/year', where all fields are numbers, works; the format that current-time-string returns is also allowed.

To specify a relative time, use numbers followed by units. For example:

`1 min'

denotes 1 minute from now.

`1 min 5 sec'

denotes 65 seconds from now.

`1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year'

denotes exactly 103 months, 123 days, and 10862 seconds from now.

If time is an integer, that specifies a relative time measured in seconds.

The argument repeat specifies how often to repeat the call. If repeat is nil, there are no repetitions; function is called just once, at time. If repeat is an integer, it specifies a repetition period measured in seconds. In any case, repeat has no effect on when first call takes place---time specifies that.

The function run-at-time returns a timer value that identifies the particular scheduled future action. You can use this value to call cancel-timer.

Function: cancel-timer timer

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