startretrysecs -> startsecs.

doc enhancements.

README.txt

@@ -233,9 +233,6 @@ Configuration File '[supervisord]' Section Settings
   'minprocs' -- The minimum nymber of process descriptors that must be
   available before supervisord will start successfully.  Default: 200.
 
-  'backofflimit' -- The number of times that supervisord will attempt
-  to restart a failing program before giving up.  Default: 3.
-
   'nocleanup' -- prevent supervisord from clearing old "AUTO" log
   files at startup time.  Default: false.
 
@@ -290,7 +287,8 @@ Configuration File '[program:x]' Section Settings
     priority=1
     autostart=true
     autorestart=true
-    startretrysecs=10
+    startsecs=10
+    startretries=3
     exitcodes=0,2
     stopsignal=TERM
     stopwaitsecs=10
@@ -314,27 +312,39 @@ Configuration File '[program:x]' Section Settings
   in them to pass to the program, e.g. ('/path/to/program/name -p "foo
   bar"').
 
-  'priority' -- the relative 'priority' of the program in the start
-  and shutdown ordering.  Lower priorities indicate programs that
-  start first and shut down last at startup and when aggregate
-  commands are used in various clients.  Higher priorities indicate
-  programs that start last and shut down first.  Default: 999.
+  'priority' -- the relative priority of the program in the start and
+  shutdown ordering.  Lower priorities indicate programs that start
+  first and shut down last at startup and when aggregate commands are
+  used in various clients (e.g. "start all"/"stop all").  Higher
+  priorities indicate programs that start last and shut down first.
+  Default: 999.
 
   'autostart' -- If true, this program will start automatically when
   supervisord is started.  Default: true.
 
   'autorestart' -- If true, when the program exits "unexpectedly",
   supervisor will restart it automatically.  "unexpected" exits are
-  those which aren't as a result of a program exit with an "expected"
-  exit code.  Default: true.
-
-  'startretrysecs' -- The total number of seconds spent attempting to
-  continually retry startup of the program due to a startup failure.
-  After this number of seconds, supervisord gives up and puts the
-  process into an ERROR state.  Default: 10.
+  those which happen when the program exits with an "unexpected" exit
+  code (see 'exitcodes').  Default: true.
+
+  'startsecs' -- The total number of seconds which supervisord will
+  spend attempting to restart a program which continually fails at
+  spawn time.  After this number of seconds of continued failure,
+  supervisord gives up and puts the process into an ERROR state.  This
+  limit may never be reached if the program fails more than
+  'startretries' times before 'startsecs' has elapsed.  Default: 10.
+
+  'startretries' -- The number of serial failure attempts that
+  supervisord will allow when attempting to start the program before
+  giving up and puting the process into an ERROR state.  This limit
+  may never be reached if the program requires more than 'startsecs'
+  seconds to retry this number of times.  Default: 3.
 
   'exitcodes' -- The list of 'expected' exit codes for this program.
-  Default: 0,2.
+  A program is considered 'failed' (and will be restarted, if
+  autorestart is set true) if it exits with an exit code which is not
+  in this list and a stop of the program has not been explicitly
+  requested.  Default: 0,2.
 
   'stopsignal' -- The signal used to kill the program when a stop is
   requested.  This can be any of TERM, HUP, INT, QUIT, KILL, USR1, or
@@ -376,14 +386,6 @@ Configuration File '[program:x]' Section Settings
   from process log file rotation.  Set this to 0 to indicate an
   unlimited number of backups.  Default: 10.
 
-Signals
-
-  Killing supervisord with SIGHUP will stop all processes, reload the
-  configuration from the config file, and restart all processes.
-
-  Killing supervisord with SIGUSR2 will rotate the supervisord and
-  child stdout log files.
-
 Examples of Program Configurations
 
   Postgres 8.14::
@@ -412,6 +414,40 @@ Examples of Program Configurations
     [program:slapd]
     command=/path/to/slapd -f /path/to/slapd.conf -h ldap://0.0.0.0:8888
 
+Process States
+
+  A process controlled by supervisord will be in one of the below
+  states at any given time.  You may see these state names in various
+  user interface elements.
+
+  RUNNING  (0)  -- The process is running.
+
+  STOPPING (1) -- The process is stopping due to a stop request.
+
+  STOPPED  (2) -- The process has been stopped due to a stop request.
+
+  KILLED = (3) -- The process was killed by a signal and the signal was
+                  unhandled by the process.
+
+  NOTSTARTED (4) -- The process has not yet been started during the
+                    lifetime of supervisord.
+
+  EXITED  (5) -- The process exited with an exit code.
+
+  STARTING  (6) -- The process is starting due to a start request.
+
+  ERROR  (7) -- The process could not be started due to a spawn error.
+
+  UNKNOWN  (10) -- The process is in an unknown state.
+
+Signals
+
+  Killing supervisord with SIGHUP will stop all processes, reload the
+  configuration from the config file, and restart all processes.
+
+  Killing supervisord with SIGUSR2 will rotate the supervisord and
+  child log files.
+
 Access Control
 
   The UNIX permissions on the socket effectively control who may send

TODO.txt

@@ -5,6 +5,8 @@
 
    - provide "restart all" functionality
 
+- Move 'forever' to process config.
+
 - Rewrite the delay/backoff stuff so humans can understand it.
 
 - Remove backofflimit.

src/supervisor/options.py

@@ -689,8 +689,8 @@ class ServerOptions(Options):
             autostart = datatypes.boolean(autostart)
             autorestart = config.saneget(section, 'autorestart', 'true')
             autorestart = datatypes.boolean(autorestart)
-            startretrysecs = config.saneget(section, 'startretrysecs', 10)
-            startretrysecs = datatypes.integer(startretrysecs)
+            startsecs = config.saneget(section, 'startsecs', 10)
+            startsecs = datatypes.integer(startsecs)
             uid = config.saneget(section, 'user', None)
             if uid is not None:
                 uid = datatypes.name_to_uid(uid)
@@ -723,7 +723,7 @@ class ServerOptions(Options):
                                     priority=priority,
                                     autostart=autostart,
                                     autorestart=autorestart,
-                                    startretrysecs=startretrysecs,
+                                    startsecs=startsecs,
                                     uid=uid,
                                     logfile=logfile,
                                     logfile_backups=logfile_backups,
@@ -1230,7 +1230,7 @@ class UnhosedConfigParser(ConfigParser.RawConfigParser):
 
 class ProcessConfig:
     def __init__(self, name, command, priority, autostart, autorestart,
-                 startretrysecs, uid, logfile, logfile_backups,
+                 startsecs, uid, logfile, logfile_backups,
                  logfile_maxbytes, stopsignal, stopwaitsecs, exitcodes,
                  log_stdout, log_stderr):
         self.name = name
@@ -1238,7 +1238,7 @@ class ProcessConfig:
         self.priority = priority
         self.autostart = autostart
         self.autorestart = autorestart
-        self.startretrysecs = startretrysecs
+        self.startsecs = startsecs
         self.uid = uid
         self.logfile = logfile
         self.logfile_backups = logfile_backups

src/supervisor/supervisord.py

@@ -191,7 +191,7 @@ class Subprocess:
     def record_spawnerr(self, msg):
         self.spawnerr = msg
         self.options.logger.critical("spawnerr: %s" % msg)
-        self.do_backoff(self.config.startretrysecs)
+        self.do_backoff(self.config.startsecs)
         self.governor()
 
     def spawn(self):
@@ -256,7 +256,7 @@ class Subprocess:
                 self.options.close_fd(pipes[fdname])
             self.options.logger.info('spawned: %r with pid %s' % (pname, pid))
             self.spawnerr = None
-            self.do_backoff(self.config.startretrysecs)
+            self.do_backoff(self.config.startsecs)
             self.options.pidhistory[pid] = self
             return pid
         
@@ -339,8 +339,12 @@ class Subprocess:
         """ Back off if respawning too frequently """
         now = time.time()
         if not self.laststart:
-            pass
-        elif now - self.laststart < self.options.backofflimit:
+            # Reset the backoff timer
+            self.options.logger.debug(
+                'resetting backoff and delay for %s' % self.config.name)
+            self.backoff = 0
+            self.delay = 0
+        elif now - self.laststart < self.config.startsecs:
             # Exited rather quickly; slow down the restarts
             self.backoff = self.backoff + 1
             if self.backoff >= self.options.backofflimit:
@@ -360,12 +364,6 @@ class Subprocess:
                 self.config.name,
                 self.backoff))
             self.delay = now + self.backoff
-        else:
-            # Reset the backoff timer
-            self.options.logger.debug(
-                'resetting backoff and delay for %s' % self.config.name)
-            self.backoff = 0
-            self.delay = 0
 
     def reportstatus(self):
         self.options.logger.debug('reportstatus called')

src/supervisor/tests.py

@@ -70,7 +70,7 @@ user=root
 logfile=/tmp/cat.log
 stopsignal=KILL
 stopwaitsecs=5
-startretrysecs=5
+startsecs=5
 
 [program:cat2]
 command=/bin/cat
@@ -120,7 +120,7 @@ exitcodes=0,1,127
         self.assertEqual(cat.priority, 1)
         self.assertEqual(cat.autostart, True)
         self.assertEqual(cat.autorestart, True)
-        self.assertEqual(cat.startretrysecs, 5)
+        self.assertEqual(cat.startsecs, 5)
         self.assertEqual(cat.uid, 0)
         self.assertEqual(cat.logfile, '/tmp/cat.log')
         self.assertEqual(cat.stopsignal, signal.SIGKILL)
@@ -1053,6 +1053,7 @@ class SubprocessTests(unittest.TestCase):
         options = DummyOptions()
         config = DummyPConfig('test', '/test')
         instance = self._makeOne(options, config)
+        instance.laststart = 100
         instance.record_spawnerr('foo')
         self.assertEqual(instance.spawnerr, 'foo')
         self.assertEqual(options.logger.data[0], 'spawnerr: foo')
@@ -2066,7 +2067,7 @@ class DummyProcess:
 
 class DummyPConfig:
     def __init__(self, name, command, priority=999, autostart=True,
-                 autorestart=True, startretrysecs=10,
+                 autorestart=True, startsecs=10,
                  uid=None, logfile=None, logfile_backups=0,
                  logfile_maxbytes=0, log_stdout=True, log_stderr=False,
                  stopsignal=signal.SIGTERM, stopwaitsecs=10,
@@ -2076,7 +2077,7 @@ class DummyPConfig:
         self.priority = priority
         self.autostart = autostart
         self.autorestart = autorestart
-        self.startretrysecs = startretrysecs
+        self.startsecs = startsecs
         self.uid = uid
         self.logfile = logfile
         self.logfile_backups = logfile_backups