Monitor work described.

CHANGES.txt

@@ -151,6 +151,14 @@ Next Release
     supervisor will set the umask of the child program.  (Thanks to
     Ian Bicking for the suggestion).
 
+  - A pair of scripts "osx_memmon_eventgen.py" and
+    "osx_memmon_listener.py" have been added to the scripts directory.
+    If they are used together as described in their comments,
+    processes which are consuming "too much" memory will be restarted.
+    The 'eventgen' script only works on OSX (my main development
+    platform) but it should be trivially generalizable to other
+    operating systems.
+
 3.0a2
 
   - Fixed the README.txt example for defining the supervisor RPC

README.txt

@@ -1039,8 +1039,13 @@ Supervisor Events (New in 3.0)
 
 Event Listeners (New in 3.0)
 
-  Supervisor event listeners are subprocesses which are treated almost
-  exactly like supervisor "programs" with the following differences:
+  Event listeners are supervisor subprocesses which take actions when
+  a supervisor event is emitted.  They can perform arbitrary actions
+  (send an email, restart a supervisor process, etc).
+
+  Supervisor event listeners are treated almost exactly like
+  supervisor "programs" with the respect to their configuration with
+  the following differences:
 
   - They are defined using an [eventlistener:x] section in the config
     file instead of a [program:x] section in the configuration file.
@@ -1233,7 +1238,9 @@ Example Event Listener Implementation
         import sys
 
   Other sample event listeners are present within the supervisor
-  package's 'scripts' directory.
+  package's 'scripts' directory, including ones which can monitor
+  supervisor subprocesses and restart a process if it is using "too
+  much" memory.
 
 Event Listener Error Conditions
 
@@ -1392,6 +1399,12 @@ FAQ
   be due to your process' dependence on environment variable settings.
   See "Subprocess Environment" in this document.
 
+  How can I make supervisor restart a process that's using "too much"
+  memory automatically?  See the files scripts/osx_memmon_eventgen.py
+  and scripts/osx_memmon_listener.py for an example of doing just this
+  (These are for Mac OS X only, but they should be easily
+  generalizable to other operating systems).
+
 Maillist, Reporting Bugs, and Viewing the CVS Repository
 
   You may subscribe to the 'Supervisor-users'

TODO.txt

@@ -28,6 +28,23 @@
   -> RESULT 10672\n<... big mess o' XML maybe ...>
   -> READY\n
 
+  Once this works, extend the eventlistener configuration to accept a
+  "handler=" parameter, e.g. "handler=supervisor.process.stdhandler"
+  (the default) or "handler=mypackage.myhandler".  Handlers will
+  accept two arguments: one named "event" which represents the event,
+  and the other named "response", which represents the listener's
+  response to the event.  A handler either executes successfully or
+  raises an exception.  If it raises an exception, the event will be
+  rebuffered.  If it does not, the event is considered successfully
+  processed.  A handler's return value is ignored.  Writing a handler
+  is a "in case of emergency break glass" sort of thing.
+
+  The 'standard' eventlistener handler will essentially do nothing if
+  it receives an "OK" and will raise an exception if it receives a
+  "FAIL" (emulating the current behavior).  A custom monitor process
+  handler, on the other hand, might restart a process if it detected
+  one was using too much memory, or would raise an exception if the
+  serialization returned indicated failure.
 
 - Make it possible to listen on a domain socket *and* an HTTP socket.