cron(3tcl) cron cron(3tcl)
______________________________________________________________________________
NAME
cron - Tool for automating the period callback of commands
SYNOPSIS
package require Tcl 8.6
package require cron ?2.1?
::cron::at ?processname? timecode command
::cron::cancel processname
::cron::every processname frequency command
::cron::in ?processname? timecode command
::cron::object_coroutine object coroutine ?info?
::cron::sleep milliseconds
::cron::task delete process
::cron::task exists process
::cron::task info process
::cron::task set process field value ?field...? ?value...?
::cron::wake ?who?
::cron::clock_step milliseconds
::cron::clock_delay milliseconds
::cron::clock_sleep seconds ?offset?
::cron::clock_set newtime
______________________________________________________________________________
DESCRIPTION
The cron package provides a Pure-tcl set of tools to allow programs to
schedule tasks to occur at regular intervals. Rather than force each
task to issue it's own call to the event loop, the cron system mimics
the cron utility in Unix: on task periodically checks to see if some-
thing is to be done, and issues all commands for a given time step at
once.
Changes in version 2.0
While cron was originally designed to handle time scales > 1 second,
the latest version's internal understand time granularity down to the
millisecond, making it easier to integrate with other timed events.
Version 2.0 also understands how to properly integrate coroutines and
objects. It also adds a facility for an external (or script driven)
clock. Note that vwait style events won't work very well with an exter-
nal clock.
COMMANDS
::cron::at ?processname? timecode command
This command registers a command to be called at the time speci-
fied by timecode. If timecode is expressed as an integer, the
timecode is assumed to be in unixtime. All other inputs will be
interpreted by clock scan and converted to unix time. This task
can be modified by subsequent calls to this package's commands
by referencing processname. If processname exists, it will be
replaced. If processname is not given, one is generated and re-
turned by the command.
::cron::at start_coffee {Tomorrow at 9:00am} {remote::exec::coffeepot power on}
::cron::at shutdown_coffee {Tomorrow at 12:00pm} {remote::exec::coffeepot power off}
::cron::cancel processname
This command unregisters the process processname and cancels any
pending commands. Note: processname can be a process created by
either ::cron::at or ::cron::every.
::cron::cancel check_mail
::cron::every processname frequency command
This command registers a command to be called at the interval of
frequency. frequency is given in seconds. This task can be mod-
ified by subsequent calls to this package's commands by refer-
encing processname. If processname exists, it will be replaced.
::cron::every check_mail 900 ::imap_client::check_mail
::cron::every backup_db 3600 {::backup_procedure ::mydb}
::cron::in ?processname? timecode command
This command registers a command to be called after a delay of
time specified by timecode. timecode is expressed as an sec-
onds. This task can be modified by subsequent calls to this
package's commands by referencing processname. If processname
exists, it will be replaced. If processname is not given, one
is generated and returned by the command.
::cron::object_coroutine object coroutine ?info?
This command registers a coroutine, associated with object to be
called given the parameters of info. If now parameters are
given, the coroutine is assumed to be an idle task which will
self-terminate. info can be given in any form compadible with
::cron::task set
::cron::sleep milliseconds
When run within a coroutine, this command will register the
coroutine for a callback at the appointed time, and immediately
yield.
If the ::cron::time variable is > 0 this command will advance
the internal time, 100ms at a time.
In all other cases this command will generate a fictious vari-
able, generate an after call, and vwait the variable:
set eventid [incr ::cron::eventcount]
set var ::cron::event_#$eventid
set $var 0
::after $ms "set $var 1"
::vwait $var
::unset $var
Usage:
::cron::sleep 250
::cron::task delete process
Delete the process specified the process
::cron::task exists process
Returns true if process is registered with cron.
::cron::task info process
Returns a dict describing process. See ::cron::task set for a
description of the options.
::cron::task set process field value ?field...? ?value...?
If process does not exist, it is created. Options Include:
command
If coroutine is black, a global command which implements
this process. If coroutine is not black, the command to
invoke to create or recreate the coroutine.
coroutine
The name of the coroutine (if any) which implements this
process.
frequency
If -1, this process is terminated after the next event.
If 0 this process should be called during every idle
event. If positive, this process should generate events
periodically. The frequency is an integer number of mil-
liseconds between events.
object The object associated with this process or coroutine.
scheduled
If non-zero, the absolute time from the epoch (in mil-
liseconds) that this process will trigger an event. If
zero, and the frequency is also zero, this process is
called every idle loop.
running
A boolean flag. If true it indicates the process never
returned or yielded during the event loop, and will not
be called again until it does so.
::cron::wake ?who?
Wake up cron, and arrange for its event loop to be run during
the next Idle cycle.
::cron::wake {I just did something important}
Several utility commands are provided that are used internally within
cron and for testing cron, but may or may not be useful in the general
cases.
::cron::clock_step milliseconds
Return a clock time absolute to the epoch which falls on the
next border between one second and the next for the value of
milliseconds
::cron::clock_delay milliseconds
Return a clock time absolute to the epoch which falls on the
next border between one second and the next milliseconds in the
future.
::cron::clock_sleep seconds ?offset?
Return a clock time absolute to the epoch which falls exactly
seconds in the future. If offset is given it may be positive or
negative, and will shift the final time to before or after the
second would flip.
::cron::clock_set newtime
Sets the internal clock for cron. This command will advance the
time in 100ms increment, triggering events, until the internal
time catches up with newtime.
newtime is expressed in absolute milliseconds since the begin-
ning of the epoch.
BUGS, IDEAS, FEEDBACK
This document, and the package it describes, will undoubtedly contain
bugs and other problems. Please report such in the category odie of
the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
also report any ideas for enhancements you may have for either package
and/or documentation.
When proposing code changes, please provide unified diffs, i.e the out-
put of diff -u.
Note further that attachments are strongly preferred over inlined
patches. Attachments can be made by going to the Edit form of the
ticket immediately after its creation, and then using the left-most
button in the secondary navigation bar.
KEYWORDS
cron, odie
CATEGORY
System
COPYRIGHT
Copyright (c) 2016-2018 Sean Woods <yoda@etoyoc.com>
tcllib 2.1 cron(3tcl)