1cron(n) cron cron(n)
2
3
4
5______________________________________________________________________________
6
8 cron - Tool for automating the period callback of commands
9
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 milleseconds
38
39 ::cron::clock_delay milleseconds
40
41 ::cron::clock_sleep seconds ?offset?
42
43 ::cron::clock_set newtime
44
45______________________________________________________________________________
46
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
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
74 returned 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 command If coroutine is black, a global command which implements
156 this process. If coroutine is not black, the command to invoke
157 to create or recreate the coroutine. coroutine The name of the
158 coroutine (if any) which implements this process. frequency If
159 -1, this process is terminated after the next event. If 0 this
160 process should be called during every idle event. If positive,
161 this process should generate events periodically. The frequency
162 is an interger number of milleseconds between events. object
163 The object associated with this process or coroutine. scheduled
164 If non-zero, the absolute time from the epoch (in milleseconds)
165 that this process will trigger an event. If zero, and the fre‐
166 quency is also zero, this process is called every idle loop.
167 running A boolean flag. If true it indicates the process never
168 returned or yielded during the event loop, and will not be
169 called again until it does so.
170
171 ::cron::wake ?who?
172 Wake up cron, and arrange for its event loop to be run during
173 the next Idle cycle.
174
175
176 ::cron::wake {I just did something important}
177
178
179 Several utility commands are provided that are used internally within
180 cron and for testing cron, but may or may not be useful in the general
181 cases.
182
183 ::cron::clock_step milleseconds
184
185 Return a clock time absolute to the epoch which falls on the
186 next border between one second and the next for the value of
187 milleseconds
188
189 ::cron::clock_delay milleseconds
190
191 Return a clock time absolute to the epoch which falls on the
192 next border between one second and the next milleseconds in the
193 future.
194
195 ::cron::clock_sleep seconds ?offset?
196
197 Return a clock time absolute to the epoch which falls exactly
198 seconds in the future. If offset is given it may be positive or
199 negative, and will shift the final time to before or after the
200 second would flip.
201
202 ::cron::clock_set newtime
203
204 Sets the internal clock for cron. This command will advance the
205 time in 100ms increment, triggering events, until the internal
206 time catches up with newtime.
207
208 newtime is expressed in absolute milleseconds since the begin‐
209 ning of the epoch.
210
212 This document, and the package it describes, will undoubtedly contain
213 bugs and other problems. Please report such in the category odie of
214 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
215 also report any ideas for enhancements you may have for either package
216 and/or documentation.
217
218 When proposing code changes, please provide unified diffs, i.e the out‐
219 put of diff -u.
220
221 Note further that attachments are strongly preferred over inlined
222 patches. Attachments can be made by going to the Edit form of the
223 ticket immediately after its creation, and then using the left-most
224 button in the secondary navigation bar.
225
227 cron, odie
228
230 System
231
233 Copyright (c) 2016-2018 Sean Woods <yoda@etoyoc.com>
234
235
236
237
238tcllib 2.1 cron(n)