12.11 control.scheduler - Scheduler ¶

Module: control.scheduler ¶

A scheduler is a device to run tasks in scheduled time.

Each scheduler manages one or more tasks. Each task has attached time to run. A task can be run once, or can be run periodically.

For portable code, you can use SRFI-120 (see srfi.120 - Timer APIs), which is written on top of this module.

Class: <scheduler> ¶

{control.scheduler} A device to run tasks in scheduled time. Each instance of this class have its own thread, and maintains a list of tasks along the information when each task should be run. Tasks can be registered by scheduler-schedule!.

If a task throws an error, a procedure bound to error-handler slot is invoked with the thrown condition as the only argument. If no error-handler is registered, or error-handler throws an error again, then the scheduler stops. The thrown condition is kept in the scheduler and can be retrieved with scheduler-terminate!.

Instance Variable of <scheduler>: error-handler ¶

This slot can be initialized with :error-handler keyword argument. It must be either #f or a procedure that takes one argument. If it is a procedure, it is invoked when a task throws an error, and the argument is the raised condition. The result of error-handler procedure is discarded.

Function: scheduler-running? scheduler ¶

{control.scheduler} Returns #t iff scheduler is running.

Function: scheduler-schedule! scheduler thunk when :optional interval ¶

{control.scheduler} Inserts a new tasks that runs thunk into scheduler. The task can be run once, or periodically.

The when argument specifies when the task should first run. It can be either one of the followings:

<time> object of type-utc or time-tai type

Specifies the aboslute point of time.

<time> object of time-duration type

Specifies the relative time since this procedure is called.

real number

Specifies the relative time in seconds since this procedure is called.

The optional interval argument can be #f, real number or <time> object of time-duration type. If it is #f or 0, the task is one-shot, that is, not repeated. Otherwise, the task is repeated with the specified interval—the real number specifies the number of seconds.

Returns an integer that identifies the task. The task id can be used to cancel or reschedule the task.

Function: scheduler-reschedule! scheduler task-id when :optional interval ¶

{control.scheduler} Change the schedule of the task specified by task-id in the scheduler. The meaning of when and interval argument is the same as scheduler-schedule!.

The same types of values as scheduler-schedule! are allowed for when and interval arguments, as well as a symbol unchanged, which indicates that value is left alone by the operation. Note that omitting interval means task will be non-repeating. If you want to change just the next time the repeating task is executed, pass unchanged to the interval.

If the scheduler doesn’t have a task with task-id, an exception is raised.

Function: scheduler-remove! scheduler task-id ¶

{control.scheduler} Remove the task specified by task-id from the scheduler. If the task is actually removed, #t is returned. If the scheduler doesn’t have a task with task-id, #f is returned.

Function: scheduler-exists? scheduler task-id ¶

{control.scheduler} Returns #t iff the scheduler has the task with task-id in the queue. Note that once the task is executed and not repeating, the task is removed from the queue.

Function: scheduler-terminate! scheduler :key on-error ¶

{control.scheduler} Stop the scheduler. Tasks still in the scheduler’s queue won’t executed, and no new task will be accepted. Once the scheduler is terminated, it can’t be restarted.

If no task has raised an exception, or all exceptions are handled by the error-handler of the scheduler, this procedure returns #t after the scheduler is stopped.

If any task has raised an exception and not handled by the error-handler, the behavior depends on the on-error keyword argumnent, which should be one of the following:

:reraise

The exception is reraised from scheduler-terminate!. This is the default.

:return

The exception is returned from scheduler-terminate!.