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
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
|
<html>
<head>
<title>arch Triggers</title>
</head>
<body>
<a name="arch_Triggers"></a>
<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>
<h2 align=center>arch Triggers</h2>
<small>
<b>up: </b><a href="arch.html#arch">arch</a></br>
<b>next: </b><a href="using-triggers.html#Using_Triggers">Using Triggers</a></br>
<b>prev: </b><a href="revision-lib.html#Revision_Tree_Libraries">Revision Tree Libraries</a></br>
</small>
<br>
<p><a name="index-pt:0"></a>
</p><p>In some circumstances, it is very useful to trigger actions upon the
detection of changes to an archive. For example, you might want to
send an email notification whenever new revisions are checked in.
</p><p>The command <code>notify</code>
provides this capability:
</p><pre>
% larch notify NOTIFICATION-DIR
</pre>
<p>That command reads configuration files found in <code>NOTIFICATION-DIR</code>
.
Those configuration files explain what parts of which repositories to
monitor, and what actions to take upon changes. When changes are
detected, <code>notify</code>
invokes actions.
</p><p>This chapter explains <code>notify</code>
in general. It documents the format of
a <code>NOTIFICATION-DIR</code>
and the configuration files. It explains what
<code>notify</code>
does. Later in the manual is documentation explaining how to
use <code>notify</code>
to achieve certain specific effects.
</p>
<a name="The_Four_notify_Configuration_Files"></a>
<h3 align=center>The Four notify Configuration Files</h3>
<p>|=rules.archives|
|=rules.categories|
|=rules.branches|
|=rules.versions|
</p><p><code>notify</code>
is controlled by four configuration files, found at the root
of a <code>NOTIFICATION-DIR</code>
. These are:
</p><pre>
=rules.archives
Specifies actions to take whenever new categories
are added to specific archives.
</pre>
<pre>
=rules.categories
Specifies actions to take whenever new branches
are added to specific categories.
</pre>
<pre>
=rules.branches
Specifies actions to take whenever new versions
are added to specific branches.
</pre>
<pre>
=rules.versions
Specifies actions to take whenever new revisions
are added to specific versions.
</pre>
<p>Within these files, blank lines are permitted and comments begin with
'#' and continue to the end of line.
</p><p>The file <code>=rules.versions</code>
contains lines with the format:
</p><pre>
VERSION ACTION
</pre>
<p>where <code>VERSION</code>
is a fully-qualified version name, and action a string
(with no whitespace) of the form:
</p><pre>
COMMAND:THUNK
</pre>
<p>Whenever new revisions are detected in <code>VERSION</code>
, <code>notify</code>
invokes:
</p><pre>
larch COMMAND THUNK RVN ...
</pre>
<p>where <code>COMMAND</code>
and <code>THUNK</code>
are from the configuration file, and the
trailing <code>RVN</code>
arguments are a list of fully qualified revision names
of newly detected revisions.
</p><p>The file <code>=rules.branches</code>
is similar. It contains lines of the form:
</p><pre>
BRANCH COMMAND:THUNK VERSION-ACTION
</pre>
<p>Whenever new versions are created in <code>BRANCH</code>
, <code>notify</code>
takes two
actions. First, it invokes:
</p><pre>
larch COMMAND THUNK VSN ...
</pre>
<p>Second, it adds new rules to <code>=rules.versions</code>
of the form:
</p><pre>
VSN VERSION-ACTION
</pre>
<p>The files <code>=rules.categories</code>
and <code>=rules.archives</code>
are similar. The
former contains lines of the form:
</p><pre>
CATEGORY COMMAND:THUNK BRANCH-ACTION VERSION-ACTION
</pre>
<p>and the latter lines of the form:
</p><pre>
ARCHIVE COMMAND:THUNK CATEGORY-ACT BRANCH-ACT VERSION-ACT
</pre>
<p>In addition to the configuration files, <code>notify</code>
maintains its private
state in <code>NOTIFY-DIR</code>
. In particular, it keeps track of what
notifications have already been sent, in order to try to avoid sending
redundant notifications.
</p>
<a name="Triggers_for_Everything_in_a_Repository"></a>
<h3 align=center>Triggers for Everything in a Repository </h3>
<p>Configuring triggers for every category, branch, and version in an
archive is quite simple: you only need to write the <code>=rules.archives</code>
file -- other configuration files will be automatically genrated from
that.
</p><p>The initial <code>=rules.archives</code>
file should contain lines of the form:
</p><pre>
ARCHIVE COMMAND:THUNK CATEGORY-ACT BRANCH-ACT VERSION-ACT
</pre>
<p>for ach set of actions you want to trigger. After creating the config
file, run <code>notify</code>
in that directory. The first run will detect all
categories in the repository, invoke <code>COMMAND</code>
for those, and create a
<code>rules.categories</code>
file with lines:
</p><pre>
CATEGORY CATEGORY-ACT BRANCH-ACT VERSION-ACT
</pre>
<p>Then <code>notify</code>
will read that config file, detect all the branches in
the repository, invoke <code>CATEGORY-ACT</code>
, and create <code>=rules.branches</code>
.
</p><p>Finally, <code>=rules.versions</code>
will be automatically created in a similar
way.
</p><p>Whenever a new category, branch, or version is added to an archive,
the rules files will be automatically updated to reflect the addition
(when <code>notify</code>
is run, of course).
</p>
<a name="Robustness_Issues_with_Triggers"></a>
<h3 align=center>Robustness Issues with Triggers</h3>
<p>Unfortunately, some fundamental physical properties of the universe
make it impossible for <code>notify</code>
to guarantee that actions will be
invoked only once for each new category, branch, version, or revision.
A (presumably rare) well timed interrupt or system failure can cause
<code>notify</code>
to invoke actions more than once for a given change to the
archive.
</p><p>Consequently, actions should be designed to be robust against that
eventuality.
</p><p><code>notify</code>
is designed to be safe in the face of concurrent invocations:
if two processes invoke <code>notify</code>
at the same time, everything should
work wonderfully with no resultant redundant actions or <code>NOTIFY-DIR</code>
corruptions.
</p>
<a name="Scheduling_Triggers_with_cron"></a>
<h3 align=center>Scheduling Triggers with cron</h3>
<p>One strategy for using <code>notify</code>
is to run it from a <code>cron</code>
job.
</p>
<a name="Scheduling_Triggers_Directly"></a>
<h3 align=center>Scheduling Triggers Directly</h3>
<p><a name="index-pt:1"></a>
<a name="index-pt:2"></a>
<a name="index-pt:3"></a>
<a name="index-pt:4"></a>
</p><p>These commands (and only these commands) modify arch repositories in
ways that are significant to <code>notify</code>
:
</p><pre>
make-category
make-branch
make-version
import
commit
</pre>
<p>Corresponding to those commands, are four others:
</p><pre>
% larch my-category-action COMMAND ARGUMENTS...
</pre>
<pre>
% larch my-branch-action COMMAND ARGUMENTS...
</pre>
<pre>
% larch my-version-action COMMAND ARGUMENTS...
</pre>
<pre>
% larch my-revision-action COMMAND ARGUMENTS...
</pre>
<p>which in those invocations, set an action to be taken upon successful
completion of an archive transaction, and in these invocations:
</p><pre>
% larch my-category-action
</pre>
<pre>
% larch my-branch-action
</pre>
<pre>
% larch my-version-action
</pre>
<pre>
% larch my-revision-action
</pre>
<p>report the actions to be taken.
</p><p>The actions have a fairly obvious meaning. After creating a new
branch, for example, the command <code>make-branch</code>
will invoke:
</p><pre>
% COMMAND ARGUMENTS... BRANCH
</pre>
<p>where <code>BRANCH</code>
is a fully qualified branch name.
</p><p>A useful action to take is to invoke <code>notify</code>
directly. Another
useful action (though imposing a greater system administration burden)
is to invoke a script which sends mail to some address, informing the
recipient of the repository change. The recipient can be, for
example, an automated process which invokes <code>notify</code>
.
</p><p>When the repository-modifying commands invoke one of these actions,
they run the action as a <code>daemon</code>
: an asynchronous process with no
controlling terminal, with standard input redirected from <code>/dev/null</code>
,
and with <code>stdout</code>
and <code>stderr</code>
saved in a temporary file. If the
command exits with non-0 status, the output from the command is sent
to the user in an email notice.
</p><p>Once again, the damn constraints of physics, particularly the
prohibition against "action at a distance", impose a constraint: it
is impossible to guarantee the <code>COMMAND</code>
will be invoked and in
(hopefully rare) circumstances, it might not be. <code>COMMANDs</code>
should be
chosen with that constraint in mind.
</p>
<small><i>arch: The arch Revision Control System
</i></small><br>
<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>
</body>
|
