Perforce's change review functionality allows users to be notified via email whenever files that they're interested in have been updated in the depot. Since change review is provided via a background Perl script, or daemon, this functionality can be modified. Other daemons can be created to perform entirely different functions.
The primary focus of this chapter is on using the change review daemon; a secondary thread discusses how to create your own daemons. This "daemon creation" topic discusses how a daemon might be created that integrates the Perforce job tracking facilities to an external defect tracking system.
Any user wishing to receive email notification of changed files must provide two pieces of information to the Perforce server: her email address, and a list of the files and directories that she wants to track (or subscribe to). This information is provided via the p4 user form.
Sarah wants to be notified whenever any of the Elm README or document files are changed. She types p4 user and fills in the resulting form with her email address and file review list:
User: sarahm
Email: [email protected]
Update: 04/29/1997 11:52:08
Access: 04/29/1997 11:52:08
FullName: Sarah MacLonnogan
Reviews:
//depot/doc/...
//depot.../README
Once the review daemon is running, she'll be notified by email whenever any of the files in her Review: list are changed. This includes all README files, and all files in the doc subdirectory.
Notification is sent whenever a changelist is submitted by any user that edits, deletes, or adds files that match the p4 user form Reviews: specification.
Change review is implemented via a Perl script, perfreview.perl, which can be downloaded from
This review daemon must be run under Perl 4 or higher; Sendmail is also required. It's usually run from the p4d server account, in the same directory as the p4d server, although it can be installed anywhere. Once it's been installed, do the following:
The review daemon is quite simple. Every time a changelist is submitted to the Perforce depot, email is sent to every user who has subscribed to review any files that are contained in that changelist. (Unlike other job review systems that you may be familiar with, the Perforce system doesn't require the email recipient to respond; the email message is sent for notification purposes only).
The daemon is implemented as follows:
The review daemon needs to keep track of which changelists have already had their descriptions emailed to reviewers; in general, most Perforce daemons will need to keep track of which changelists have already been processed. The p4 review command exists to facilitate this process; it was written solely to support daemon creation and is not likely to be run by an end user.
Every line of output produced by p4 review has the following form:
When used with no parameters, p4 review will output one line for every changelist that has ever been submitted. With the addition of review counter arguments, p4 review can limit its output to only those changelists not already reported. A review counter is simply a named counter; each review counter can separately track which changelists have and haven't yet been reviewed.
Review counters are used in two variants of p4 review:
Review counters work by storing one counter per review counter in the Perforce database. The first variant of p4 review above sets a counter value for a particular review counter; the second variant gets the change information for all changelists numbered above that counter. The review daemon's review counter is called review; the daemon uses
p4 review -t review to get a list of all unreviewed changelists, and uses
p4 review -t review -c lastchangenum to store the highest numbered reviewed change number in the database under the name review.
Perforce can store any number of review counters; each counter is identified by a unique name, which can be up to ten characters long and cannot contain whitespace.
| The review counter names journal, job, and change are used internally by Perforce; use of any of these three names as review counters could corrupt the Perforce database! |
The perfreview.perl daemon's review counter is named review; if you're using perfreview.perl and are writing your own daemon, don't name the review counter review.
The change review daemon runs at the access level of the user who invokes it (typically root), not at the access level of the user receiving email. Thus, if the daemon is edited to perform additional functionality, it should not mail out the contents of files unless it is safe for all users to see those files, since a user needs only list access in order to invoke the p4 user command to subscribe to particular files. (Access levels are covered in Chapter 14.)
To create another daemon, use perfreview.perl as a starting point and change it as needed. One such daemon might upload Perforce job information into an external bug tracking system after changelist submission. It would use the p4 review command with a new review counter to list new changelists, and use p4 fixes to get the list of jobs fixed by the newly submitted changelists. This information might then be fed to the external system, notifying it that certain jobs have been completed.
If you do write a daemon of your own, and would like to share it with other users, please let us know about it at [email protected].
The change review daemon uses two reporting commands that have not yet been discussed; an additional reporting command describes the counters tracked by the p4d server: