The Hackerlab at regexps.com

Driving Process Automation with arch Notifiers

up: arch Meets hello-world
next: The arch Changeset Format
prev: Speeding up arch with Revision Tree Libraries

Active Development Warning: The features described in this chapter are likely to change in incompatible ways before the 1 .0 release of arch .

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.

The command notify provides this capability:

        % larch notify NOTIFICATION-DIR

That command reads configuration files found in NOTIFICATION-DIR . Those configuration files explain what parts of which repositories to monitor, and what actions to take upon changes. When changes are detected, notify invokes actions.

This chapter explains notify in general. It documents the format of a NOTIFICATION-DIR and the configuration files. It explains what notify does.

The Four notify Configuration Files

|=rules.archives| |=rules.categories| |=rules.branches| |=rules.versions|

notify is controlled by four configuration files, found at the root of a NOTIFICATION-DIR . These are:


        =rules.archives
                Specifies actions to take whenever new categories
                are added to specific archives.

        =rules.categories
                Specifies actions to take whenever new branches
                are added to specific categories.

        =rules.branches
                Specifies actions to take whenever new versions
                are added to specific branches.

        =rules.versions
                Specifies actions to take whenever new revisions
                are added to specific versions.


Within these files, blank lines are permitted and comments begin with '#' and continue to the end of line.

The file =rules.versions contains lines with the format:

        VERSION         ACTION

where VERSION is a fully-qualified version name, and action a string (with no whitespace) of the form:

        COMMAND:THUNK

Whenever new revisions are detected in VERSION , notify invokes:

        larch COMMAND THUNK RVN ...

where COMMAND and THUNK are from the configuration file, and the trailing RVN arguments are a list of fully qualified revision names of newly detected revisions.

The file =rules.branches is similar. It contains lines of the form:

        BRANCH COMMAND:THUNK VERSION-ACTION

Whenever new versions are created in BRANCH , notify takes two actions. First, it invokes:

        larch COMMAND THUNK VSN ...

Second, it adds new rules to =rules.versions of the form:

        VSN     VERSION-ACTION

The files =rules.categories and =rules.archives are similar. The former contains lines of the form:

        CATEGORY COMMAND:THUNK BRANCH-ACTION VERSION-ACTION

and the latter lines of the form:

        ARCHIVE COMMAND:THUNK CATEGORY-ACT BRANCH-ACT VERSION-ACT

In addition to the configuration files, notify maintains its private state in NOTIFY-DIR . In particular, it keeps track of what notifications have already been sent, in order to try to avoid sending redundant notifications.

Notifiers for Everything in a Repository

Configuring notifiers for every category, branch, and version in an archive is quite simple: you only need to write the =rules.archives file -- other configuration files will be automatically generated from that.

The initial =rules.archives file should contain lines of the form:

        ARCHIVE COMMAND:THUNK CATEGORY-ACT BRANCH-ACT VERSION-ACT

for each set of actions you want to trigger. After creating the config file, run notify in that directory. The first run will detect all categories in the repository, invoke COMMAND for those, and create a rules.categories file with lines:

        CATEGORY CATEGORY-ACT BRANCH-ACT VERSION-ACT

Then notify will read that config file, detect all the branches in the repository, invoke CATEGORY-ACT , and create =rules.branches .

Finally, =rules.versions will be automatically created in a similar way.

Whenever a new category, branch, or version is added to an archive, the rules files will be automatically updated to reflect the addition (when notify is run, of course).

Mailing Out Notices

These commands can be used in notifier rules to send mail announcing new additions to an archive:

        mail-new-categories
        mail-new-branches
        mail-new-versions
        mail-new-revisions

This command, if invoked for new revisions, can be used to add those revisions to the revision library registered with my-revision-library :

        notify-library

Finally, the noop command can be used as a place-holder for notifier events where no actions is needed.

Putting those commands together, you can create an =rules.archives file that sends out announcements and updates a revision library for an archive (long lines wrapped for legibility):

/*insert

        lord@emf.net--2003              mail-new-categories:lord \
                                        mail-new-branches:lord \
                                        mail-new-versions:lord \
                                        mail-new-revisions:lord

        lord@emf.net--2003              noop:notify-library:lord \
                                        noop:notify-library:lord \
                                        noop:notify-library:lord \
                                        notify-library:lord

/*end-insert

Robustness Issues with Notifiers

Unfortunately, some fundamental physical properties of the universe make it impossible for notify 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 notify to invoke actions more than once for a given change to the archive.

Consequently, actions should be designed to be robust against that eventuality.

notify is designed to be safe in the face of concurrent invocations: if two processes invoke notify at the same time, everything should work wonderfully with no resultant redundant actions or NOTIFY-DIR corruptions.

Scheduling Notifiers with cron

One strategy for using notify is to run it from a cron job.

Scheduling Notifiers From arch Commands

These commands (and only these commands) modify arch repositories in ways that are significant to notify :

        make-category
        make-branch
        make-version
        import
        commit
        tag

If you register a notifier directory with the command my-notifier :

        % larch my-notifier NOTIFIER-DIR

then the commands listed above will, after completing their work, spawn a detached daemon process that runs larch notify in that directory. Note that the start times and exit status of those daemons are recorded in ~/.arch-params/log-file which can be useful when trying to debug problems. You may want to clear that file from time-to-time.

arch Meets hello-world: A Tutorial Introduction to The arch Revision Control System
The Hackerlab at regexps.com