11.26 srfi.120 - Timer APIs

Module: srfi.120 ¶

This srfi provides a device to run tasks in a specified time.

In Gauche, this is a thin wrapper of control.scheduler module (see control.scheduler - Scheduler, for the details). Use this module if you need portability.

Function: make-timer :optional error-handler ¶

[SRFI-120]{srfi.120} Create a new timer, with error-handler as an error hander. The error-handler argument must be #f or a procedure that takes one argument. If it is a procedure, it is called when the task thunk raises an error, with the raised condition as an argument. Its return value is ignored. If omitted, #f is assumed.

In Gauche, returned timer object is just an instance of <scheduler>, and error-handler is set in its error-handler slot. See control.scheduler - Scheduler, for the details.

Function: timer? obj ¶

[SRFI-120]{srfi.120} Returns #t iff obj is a timer (an instance of <scheduler>).

Same as scheduler? in control.scheduler (see control.scheduler - Scheduler).

Function: timer-cancel! timer ¶

[SRFI-120]{srfi.120} Stops the timer. No tasks in the queue will be executed, and no new tasks is accepted. Once timer is canceled, it can’t be restarted.

If the timer’s tasks ever raised an error, and either the timer doesn’t have an error handler, or an error handler itself raises an error, then the condition object is kept in the timer and reraised from this procedure.

See also scheduler-terminate! in control.scheduler (see control.scheduler - Scheduler).

Function: timer-schedule! timer thunk when :optional period ¶

[SRFI-120]{srfi.120} Creates a new task to run thunk in the timer, at when. The when argument specifies the relative time from the moment this procedure is called. It must be either an integer as the number of milliseconds, or a time delta object created by make-timer-delta.

If the period argument is given and non zero, the task will be repeated in every period. It must be a nonnegative integer in milliseconds or a time delta object. If it is zero, task is non-repeating.

Retuns a task-id, which can be used to reschedule or remove the task later. The srfi specifies a task id to be any printable Scheme object; Gauche uses an integer.

Note: In Gauche, a time delta object is a SRFI-19 time-duration time (see Time types).

This is implemented on top of scheduler-schedule! in control.scheduler (see control.scheduler - Scheduler), but note that the unit of when and period is different from it.

Function: timer-reschedule! timer task-id when :optional period ¶

[SRFI-120]{srfi.120} Change the timing when task identified by task-id in timer is executed. The task-id should be the object returned from previous timer-schedule! on the same timer.

The semantics of when and period are the same as timer-schedule!.

If there’s no task with task-id in timer (including the case that the task was one-shot and already run), an error is thrown. (The behavior is undefined in the srfi).

This procedure returns task-id.

This is implemented on top of scheduler-reschedule! in control.scheduler (see control.scheduler - Scheduler), but note that the unit of when and period is different from it.

Function: timer-task-remove! timer task-id ¶

[SRFI-120]{srfi.120} Removes the task specified by task-id from the timer. Returns #t if the task is actually removed, #f if the timer doesn’t have the specified task.

Function: timer-task-exists? timer task-id ¶

[SRFI-120]{srfi.120} Returns #t iff the timer has a task specified by task-id. A non-repeated task is automatically removed from timer once executed.

Function: make-timer-delta n unit ¶

[SRFI-120]{srfi.120} A constructor for time-delta object. It can be passed to when and period arguments of timer-schedule! and timer-reschedule!.

In Gauche, a time-delta object is an instance of <time> with time-duration type (see Time types). The srfi doesn’t specify the concrete implementation, though, so portable code should use this procedure.

n is an integer, and unit must be one of the following symbols: h (hour), m (minute), s (second), ms (millisecond), us (microsecond) or ns (nanosecond).

Function: timer-delta? obj ¶

[SRFI-120]{srfi.120} Returns #t iff obj is a time-delta object, which is, in Gauche, an instance of <time> object with time-duration type.