DESCRIPTION

(Note, the queue() function is currently an experimental feature, with behavior subject to change. If you use this function, please send feedback to CSS.)

The queue() function schedules commands to be run once at a fixed time in the future or to repeat at an interval. Commands from the queue will normally run while spec is waiting for keyboard input. If spec is otherwise occupied commands in the queue will be deferred until the next opportunity spec has to check the queue. However, a queue("check") can be issued within running statements to give commands that are due a chance to run.

queue(cmd, interval)

Schedules cmd to be run every interval seconds.

queue(cmd, epoch_time*)

Schedule cmd to be run just once at epoch_time. The epoch time is the number of seconds from the UNIX epoch of 00:00 GMT 1/1/1970.

queue("list")

Lists commands in the queue, sorted by next run time, along with the configured repetition interval.

queue("check")

Runs commands that are due or overdue.

queue(cmd, "delete")

Deletes cmd from the queue. The argument cmd may contain the *, ? and [] metacharacters. A * matches any string, while a ? matches any single character. With the [...] pattern, any string that contains the characters within the square brackets is matched. Two characters separated by a hyphen specify a range of characters that will match. An initial ^ negates the enclosed character set.

Note, values in the second argument less than 1000 days worth of seconds are considered intervals. Numbers larger than that are considered epoch times. Epoch times in the past produce an error message. To schedule a command to run at num seconds in the future, use:

queue(cmd, time() + num)

Calling queue() with the same cmd as already active with a new interval or epoch_time will replace the existing item in the queue with the new scheduled interval or time.

Although there is no limit to length or complexity of the cmd argument, it is recommended to define macros for long commands and pass the macro name to queue().

The following functions and commands are generally not allowed in the cmd argument:

dofile()        qdofile()       spec_menu()
getval()        getsval()       input()         yesno()
mcount()        tcount()
move_all        move_cnt        reconfig        sync

However, if spec is running in daemonized mode (see the daemon help file), only dofile() and qdofile() are disallowed.

Note, if it is necessary to read and act on content from files with queue(), use eval() on strings read using getline().

The command queue is checked while spec is waiting for keyboard input at several places: at the main prompt, with the input() function (other than when called with a numeric argument), with the getval(), getsval() and yesno() functions and in the spec_menu() function. The queue is also checked while perusing help files and while waiting for unix() subshells to complete (if they run for longer than one second).

In daemonized mode, the command queue will be checked if spec is otherwise unoccupied.

When spec is busy executing commands, the queue will not be checked and commands may not run at their scheduled time. Past due commands will be run with the queue check that occurs when the activity that prevented the checks completes. Commands that are scheduled to repeat will have the next execution set to a time at the specified interval from the time at which the command does run. Thus, the resulting intervals may not be evenly spaced. The queue("check") command can be run within the commands or macros that are blocking the queue checks to run overdue queued commands.

The unix() command is allowed in a queued command, but those commands will not run if there is a current unix() command running.

If there is an error while executing a repeating command, it will be deleted from the queue. An exit statement will not cause a command to be deleted. A keyboard ^C may interrupt a command executing from the queue. If that happens three consecutive times, the command will be deleted from the queue.

The command queue is not saved in the spec user state file. If restarting a spec session, command queues need to be reinitialized.