Ubuntu Manpage: cron - Tool for automating the period callback of commands

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 something 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 external clock.

COMMANDS

::cron::at ?processname? timecode command
This command registers a command to be called at the time specified 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 returned 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 modified by subsequent calls to
this package's commands by referencing 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 seconds. 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 variable, 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
milliseconds between events.

object The object associated with this process or coroutine.

scheduled
If non-zero, the absolute time from the epoch (in milliseconds) 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 beginning 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 output 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

COPYRIGHT

       Copyright (c) 2016-2018 Sean Woods <yoda@etoyoc.com>