1cron(n)                              cron                              cron(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       cron - Tool for automating the period callback of commands
9

SYNOPSIS

11       package require Tcl  8.6
12
13       package require cron  ?2.1?
14
15       ::cron::at ?processname? timecode command
16
17       ::cron::cancel processname
18
19       ::cron::every processname frequency command
20
21       ::cron::in ?processname? timecode command
22
23       ::cron::object_coroutine object coroutine ?info?
24
25       ::cron::sleep milliseconds
26
27       ::cron::task delete process
28
29       ::cron::task exists process
30
31       ::cron::task info process
32
33       ::cron::task set process field value ?field...? ?value...?
34
35       ::cron::wake ?who?
36
37       ::cron::clock_step milliseconds
38
39       ::cron::clock_delay milliseconds
40
41       ::cron::clock_sleep seconds ?offset?
42
43       ::cron::clock_set newtime
44
45______________________________________________________________________________
46

DESCRIPTION

48       The  cron package provides a Pure-tcl set of tools to allow programs to
49       schedule tasks to occur at regular intervals. Rather  than  force  each
50       task  to  issue it's own call to the event loop, the cron system mimics
51       the cron utility in Unix: on task periodically checks to see  if  some‐
52       thing  is  to be done, and issues all commands for a given time step at
53       once.
54
55       Changes in version 2.0
56
57       While cron was originally designed to handle time scales  >  1  second,
58       the  latest  version's internal understand time granularity down to the
59       millisecond, making it easier to integrate  with  other  timed  events.
60       Version  2.0  also understands how to properly integrate coroutines and
61       objects.  It also adds a facility for an external  (or  script  driven)
62       clock. Note that vwait style events won't work very well with an exter‐
63       nal clock.
64

COMMANDS

66       ::cron::at ?processname? timecode command
67              This command registers a command to be called at the time speci‐
68              fied  by  timecode.  If timecode is expressed as an integer, the
69              timecode is assumed to be in unixtime. All other inputs will  be
70              interpreted by clock scan and converted to unix time.  This task
71              can be modified by subsequent calls to this  package's  commands
72              by  referencing  processname.  If processname exists, it will be
73              replaced.  If processname is not given, one is generated and re‐
74              turned by the command.
75
76
77              ::cron::at start_coffee {Tomorrow at 9:00am}  {remote::exec::coffeepot power on}
78              ::cron::at shutdown_coffee {Tomorrow at 12:00pm}  {remote::exec::coffeepot power off}
79
80
81       ::cron::cancel processname
82              This command unregisters the process processname and cancels any
83              pending commands.  Note: processname can be a process created by
84              either ::cron::at or ::cron::every.
85
86
87              ::cron::cancel check_mail
88
89
90       ::cron::every processname frequency command
91              This command registers a command to be called at the interval of
92              frequency.  frequency is given in seconds. This task can be mod‐
93              ified  by  subsequent calls to this package's commands by refer‐
94              encing processname. If processname exists, it will be replaced.
95
96
97              ::cron::every check_mail 900  ::imap_client::check_mail
98              ::cron::every backup_db  3600 {::backup_procedure ::mydb}
99
100
101       ::cron::in ?processname? timecode command
102              This command registers a command to be called after a  delay  of
103              time  specified  by  timecode.  timecode is expressed as an sec‐
104              onds.  This task can be modified by  subsequent  calls  to  this
105              package's  commands  by  referencing processname. If processname
106              exists, it will be replaced.  If processname is not  given,  one
107              is generated and returned by the command.
108
109       ::cron::object_coroutine object coroutine ?info?
110              This command registers a coroutine, associated with object to be
111              called given the parameters  of  info.  If  now  parameters  are
112              given,  the  coroutine  is assumed to be an idle task which will
113              self-terminate. info can be given in any  form  compadible  with
114              ::cron::task set
115
116       ::cron::sleep milliseconds
117              When  run  within  a  coroutine,  this command will register the
118              coroutine for a callback at the appointed time, and  immediately
119              yield.
120
121              If  the  ::cron::time  variable is > 0 this command will advance
122              the internal time, 100ms at a time.
123
124              In all other cases this command will generate a  fictious  vari‐
125              able, generate an after call, and vwait the variable:
126
127
128              set eventid [incr ::cron::eventcount]
129              set var ::cron::event_#$eventid
130              set $var 0
131              ::after $ms "set $var 1"
132              ::vwait $var
133              ::unset $var
134
135
136       Usage:
137
138
139              ::cron::sleep 250
140
141
142       ::cron::task delete process
143              Delete the process specified the process
144
145       ::cron::task exists process
146              Returns true if process is registered with cron.
147
148       ::cron::task info process
149              Returns  a  dict  describing process. See ::cron::task set for a
150              description of the options.
151
152       ::cron::task set process field value ?field...? ?value...?
153
154              If process does not exist, it is created. Options Include:
155
156              command
157                     If coroutine is black, a global command which  implements
158                     this  process.  If coroutine is not black, the command to
159                     invoke to create or recreate the coroutine.
160
161              coroutine
162                     The name of the coroutine (if any) which implements  this
163                     process.
164
165              frequency
166                     If  -1,  this process is terminated after the next event.
167                     If 0 this process should  be  called  during  every  idle
168                     event.  If  positive, this process should generate events
169                     periodically. The frequency is an integer number of  mil‐
170                     liseconds between events.
171
172              object The object associated with this process or coroutine.
173
174              scheduled
175                     If  non-zero,  the  absolute time from the epoch (in mil‐
176                     liseconds) that this process will trigger an  event.   If
177                     zero,  and  the  frequency  is also zero, this process is
178                     called every idle loop.
179
180              running
181                     A boolean flag. If true it indicates  the  process  never
182                     returned  or  yielded during the event loop, and will not
183                     be called again until it does so.
184
185       ::cron::wake ?who?
186              Wake up cron, and arrange for its event loop to  be  run  during
187              the next Idle cycle.
188
189
190              ::cron::wake {I just did something important}
191
192
193       Several  utility  commands are provided that are used internally within
194       cron and for testing cron, but may or may not be useful in the  general
195       cases.
196
197       ::cron::clock_step milliseconds
198
199              Return  a  clock  time  absolute to the epoch which falls on the
200              next border between one second and the next  for  the  value  of
201              milliseconds
202
203       ::cron::clock_delay milliseconds
204
205              Return  a  clock  time  absolute to the epoch which falls on the
206              next border between one second and the next milliseconds in  the
207              future.
208
209       ::cron::clock_sleep seconds ?offset?
210
211              Return  a  clock  time absolute to the epoch which falls exactly
212              seconds in the future. If offset is given it may be positive  or
213              negative,  and  will shift the final time to before or after the
214              second would flip.
215
216       ::cron::clock_set newtime
217
218              Sets the internal clock for cron. This command will advance  the
219              time  in  100ms increment, triggering events, until the internal
220              time catches up with newtime.
221
222              newtime is expressed in absolute milliseconds since  the  begin‐
223              ning of the epoch.
224

BUGS, IDEAS, FEEDBACK

226       This  document,  and the package it describes, will undoubtedly contain
227       bugs and other problems.  Please report such in the  category  odie  of
228       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
229       also report any ideas for enhancements you may have for either  package
230       and/or documentation.
231
232       When proposing code changes, please provide unified diffs, i.e the out‐
233       put of diff -u.
234
235       Note further that  attachments  are  strongly  preferred  over  inlined
236       patches.  Attachments  can  be  made  by  going to the Edit form of the
237       ticket immediately after its creation, and  then  using  the  left-most
238       button in the secondary navigation bar.
239

KEYWORDS

241       cron, odie
242

CATEGORY

244       System
245
247       Copyright (c) 2016-2018 Sean Woods <yoda@etoyoc.com>
248
249
250
251
252tcllib                                2.1                              cron(n)
Impressum