cron - Tool for automating the period callback of commands

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 TcllibTrackers  [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 unifieddiffs, 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.

Commands

::cron::at?processname?timecodecommand
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 clockscan 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::cancelprocessname
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::everyprocessnamefrequencycommand
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?timecodecommand
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_coroutineobjectcoroutine?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::taskset::cron::sleepmilliseconds
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::taskdeleteprocess
Delete the process specified the process::cron::taskexistsprocess
Returns true if process is registered with cron.

::cron::taskinfoprocess
Returns a dict describing process. See ::cron::taskset for a description of the options.

::cron::tasksetprocessfieldvalue?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_stepmilliseconds

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_delaymilliseconds

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_sleepseconds?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_setnewtime

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.

Copyright

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

tcllib                                                 2.2                                            cron(3tcl)

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.

Keywords

       cron, odie

Name

       cron - Tool for automating the period callback of commands

Synopsis

       package require Tcl8.69

       package require cron?2.2?::cron::at?processname?timecodecommand::cron::cancelprocessname::cron::everyprocessnamefrequencycommand::cron::in?processname?timecodecommand::cron::object_coroutineobjectcoroutine?info?::cron::sleepmilliseconds::cron::taskdeleteprocess::cron::taskexistsprocess::cron::taskinfoprocess::cron::tasksetprocessfieldvalue?field...??value...?::cron::wake?who?::cron::clock_stepmilliseconds::cron::clock_delaymilliseconds::cron::clock_sleepseconds?offset?::cron::clock_setnewtime

________________________________________________________________________________________________________________