1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
[comment {-*- tcl -*- doctools manpage}]
[vset PACKAGE_VERSION 2.2]
[manpage_begin cron n [vset PACKAGE_VERSION]]
[keywords {cron}]
[keywords {odie}]
[copyright {2016-2018 Sean Woods <yoda@etoyoc.com>}]
[moddesc {cron}]
[titledesc {Tool for automating the period callback of commands}]
[category System]
[require Tcl "8.6 9"]
[require cron [opt [vset PACKAGE_VERSION]]]
[description]
[para]
The [package 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.
[para]
Changes in version 2.0
[para]
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.
[section Commands]
[list_begin definitions]
[call [cmd ::cron::at] [arg ?processname?] [arg timecode] [arg command]]
This command registers a [arg command] to be called at the time specified by [arg timecode].
If [arg timecode] is expressed as an integer, the timecode is assumed to be in unixtime. All
other inputs will be interpreted by [cmd {clock scan}] and converted to unix time.
This task can be modified by subsequent calls to
this package's commands by referencing [arg processname]. If [arg processname] exists,
it will be replaced.
If [arg processname] is not given, one is generated and returned by the command.
[example_begin]
::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}
[example_end]
[call [cmd ::cron::cancel] [arg processname]]
This command unregisters the process [arg processname] and cancels any pending commands.
Note: processname can be a process created by either [cmd ::cron::at] or [cmd ::cron::every].
[example_begin]
::cron::cancel check_mail
[example_end]
[call [cmd ::cron::every] [arg processname] [arg frequency] [arg command]]
This command registers a [arg command] to be called at the interval of [arg frequency].
[arg frequency] is given in seconds. This task can be modified by subsequent calls to
this package's commands by referencing [arg processname]. If [arg processname] exists,
it will be replaced.
[example_begin]
::cron::every check_mail 900 ::imap_client::check_mail
::cron::every backup_db 3600 {::backup_procedure ::mydb}
[example_end]
[call [cmd ::cron::in] [arg ?processname?] [arg timecode] [arg command]]
This command registers a [arg command] to be called after a delay of time specified by [arg timecode].
[arg timecode] is expressed as an seconds.
This task can be modified by subsequent calls to
this package's commands by referencing [arg processname]. If [arg processname] exists,
it will be replaced.
If [arg processname] is not given, one is generated and returned by the command.
[call [cmd ::cron::object_coroutine] [arg object] [arg coroutine] [arg ?info?]]
This command registers a [arg coroutine], associated with [arg object] to be called
given the parameters of [arg info]. If now parameters are given, the coroutine is assumed
to be an idle task which will self-terminate. [arg info] can be given in any form compadible with
[cmd {::cron::task set}]
[call [cmd ::cron::sleep] [arg milliseconds]]
When run within a coroutine, this command will register the coroutine for a callback
at the appointed time, and immediately yield.
[para]
If the ::cron::time variable is > 0 this command will advance the internal time,
100ms at a time.
[para]
In all other cases this command will generate a fictious variable, generate an
after call, and vwait the variable:
[example {
set eventid [incr ::cron::eventcount]
set var ::cron::event_#$eventid
set $var 0
::after $ms "set $var 1"
::vwait $var
::unset $var
}]
[para]
Usage:
[example_begin]
::cron::sleep 250
[example_end]
[call [cmd {::cron::task delete}] [arg process]]
Delete the process specified the [arg process]
[call [cmd {::cron::task exists}] [arg process]]
Returns true if [arg process] is registered with cron.
[call [cmd {::cron::task info}] [arg process]]
Returns a dict describing [arg process]. See [cmd {::cron::task set}] for a description of the options.
[call [cmd {::cron::task set}] [arg process] [arg field] [arg value] [arg ?field...?] [arg ?value...?]]
[para]
If [arg process] does not exist, it is created. Options Include:
[list_begin definitions]
[def [cmd command]]
If [cmd coroutine] is black, a global command which implements this process. If [cmd coroutine] is not
black, the command to invoke to create or recreate the coroutine.
[def [cmd coroutine]]
The name of the coroutine (if any) which implements this process.
[def [cmd 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.
[def [cmd object]]
The object associated with this process or coroutine.
[def [cmd scheduled]]
If non-zero, the absolute time from the epoch (in milliseconds) that this process will trigger an event.
If zero, and the [cmd frequency] is also zero, this process is called every idle loop.
[def [cmd 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.
[list_end]
[call [cmd ::cron::wake] [arg ?who?]]
Wake up cron, and arrange for its event loop to be run during the next Idle cycle.
[example_begin]
::cron::wake {I just did something important}
[example_end]
[list_end]
[para]
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.
[list_begin definitions]
[call [cmd ::cron::clock_step] [arg milliseconds]]
[para]
Return a clock time absolute to the epoch which falls on the next
border between one second and the next for the value of [arg milliseconds]
[call [cmd ::cron::clock_delay] [arg milliseconds]]
[para]
Return a clock time absolute to the epoch which falls on the next
border between one second and the next [arg milliseconds] in the future.
[call [cmd ::cron::clock_sleep] [arg seconds] [arg ?offset?]]
[para]
Return a clock time absolute to the epoch which falls exactly [arg 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.
[call [cmd ::cron::clock_set] [arg newtime]]
[para]
Sets the internal clock for cron. This command will advance the time in 100ms
increment, triggering events, until the internal time catches up with [arg newtime].
[para]
[arg newtime] is expressed in absolute milliseconds since the beginning of the epoch.
[list_end]
[para]
[vset CATEGORY odie]
[include ../common-text/feedback.inc]
[manpage_end]
|
