document supervisor

celery/supervisor.py

@@ -3,7 +3,7 @@ import threading
 import time
 
 PING_TIMEOUT = 30 # seconds
-JOIN_TIMEOUT = 2 
+JOIN_TIMEOUT = 2
 CHECK_INTERVAL = 2
 MAX_RESTART_FREQ = 3
 MAX_RESTART_FREQ_TIME = 10
@@ -15,16 +15,62 @@ def raise_ping_timeout():
 
 class OFASupervisor(object):
     """Process supervisor using the `one_for_all`_ strategy.
-   
+
     .. _`one_for_all`:
         http://erlang.org/doc/design_principles/sup_princ.html#5.3.2
-    
+
+    However, instead of registering a list of processes, you have one
+    process which runs a pool. Makes for an easy implementation.
+
+    :param target: see :attr:`target`.
+    :param args: see :attr:`args`.
+    :param kwargs see :attr:`kwargs`.
+    :param join_timeout see :attr:`join_timeout`.
+    :param max_restart_freq see :attr:`max_restart_freq`.
+    :param max_restart_freq_time see :attr:`max_restart_freq_time`.
+    :param check_interval see :attr:`max_restart_freq_time`.
+
+    .. attribute:: target
+
+        The target callable to be launched in a new process.
+
+    .. attribute:: args
+
+        The positional arguments to apply to :attr:`target`.
+
+    .. attribute:: kwargs
+
+        The keyword arguments to apply to :attr:`target`.
+
+    .. attribute:: join_timeout
+
+        If the process is dead, try to give it a few seconds to join.
+
+    .. attribute:: max_restart_freq
+
+        Limit the number of restarts which can occur in a given time interval.
+
+        The max restart frequency is the number of restarts that can occur
+        within the interval :attr:`max_restart_freq_time`.
+
+        The restart mechanism prevents situations where the process repeatedly
+        dies for the same reason. If this happens both the process and the
+        supervisor is terminated.
+
+    .. attribute:: max_restart_freq_time
+
+        See :attr:`max_restart_freq`.
+
+    .. attribute:: check_interval
+
+        The time in seconds, between process pings.
+
     """
 
     def __init__(self, target, args=None, kwargs=None,
             ping_timeout=PING_TIMEOUT, join_timeout=JOIN_TIMEOUT,
-            max_restart_freq_time=MAX_RESTART_FREQ_TIME,
             max_restart_freq = MAX_RESTART_FREQ,
+            max_restart_freq_time=MAX_RESTART_FREQ_TIME,
             check_interval=CHECK_INTERVAL):
         self.target = target
         self.args = args or []
@@ -37,15 +83,19 @@ class OFASupervisor(object):
         self.restarts_in_frame = 0
 
     def start(self):
+        """Launches the :attr:`target` in a seperate process and starts
+        supervising it."""
         target = self.target
-    
+
         def _start_supervised_process():
+            """Start the :attr:`target` in a new process."""
             process = Process(target=target,
                               args=self.args, kwargs=self.kwargs)
             process.start()
             return process
-    
+
         def _restart(self, process):
+            """Terminate the process and restart."""
             process.join(timeout=self.join_timeout)
             process.terminate()
             self.restarts_in_frame += 1
@@ -61,7 +111,7 @@ class OFASupervisor(object):
                                 "Supervised: Max restart frequency reached")
                 restart_frame = 0
                 self.restarts_in_frame = 0
-                    
+
                 try:
                     proc_is_alive = self.is_alive(process)
                 except TimeoutError:
@@ -74,8 +124,13 @@ class OFASupervisor(object):
                 restart_frame += self.check_interval
         finally:
             process.join()
-        
+
     def _is_alive(self, process):
+        """Sends a ping to the target process to see if it's alive.
+
+        :rtype bool:
+
+        """
         timeout_timer = threading.Timer(self.ping_timeout, raise_ping_timeout)
         try:
             alive = process.is_alive()