Scroll to navigation

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 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:

  







  

  
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.

  

  
The name of the coroutine (if any) which implements this process.

  

  
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.

  

  
The object associated with this process or coroutine.

  

  
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.

  

  
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






CATEGORY


System






COPYRIGHT


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








  

    2.1
    tcllib