[Supervisor-checkins] r800 - supervisor_manual/trunk/chapters

[Mike Naberezny]

Author: Mike Naberezny <mike at maintainable.com>
Date: Mon Aug 11 01:36:55 2008
New Revision: 800

Log:
Document the 'wait' option for supervisor.stopAllProcesses() and supervisor.stopProcessGroup().

Modified:
   supervisor_manual/trunk/chapters/api-process-control.xml

Modified: supervisor_manual/trunk/chapters/api-process-control.xml
==============================================================================
--- supervisor_manual/trunk/chapters/api-process-control.xml	(original)
+++ supervisor_manual/trunk/chapters/api-process-control.xml	Mon Aug 11 01:36:55 2008
@@ -422,6 +422,13 @@
               Group name to stop
             </entry>
           </row>
+          <row>
+            <entry>boolean</entry>
+            <entry>wait</entry>
+            <entry>
+              Wait for stop to complete before returning? (optional, default True)
+            </entry>
+          </row>
         </tbody>
       </tgroup>
     </table>
@@ -436,10 +443,10 @@
           </row>
         </thead>
           <tbody>
-              <row>
-                <entry>boolean</entry>
-                <entry>Always <code>TRUE</code></entry>                    
-              </row>
+            <row>
+              <entry>boolean or array&lt;struct&gt;</entry>
+              <entry>See below</entry>                    
+            </row>
           </tbody>
       </tgroup>
     </table>      
@@ -455,17 +462,30 @@
        If name of the group (<code>name</code> argument) is not recognized, 
        the fault <code>BAD_NAME</code> will be raised.
     </para>
+
+    <para>
+      If <code>wait=True</code>, Supervisor hold the HTTP request until each
+      process has been stopped (or tries to stop have been exhausted).
+    </para>
+
+    <para>
+      The return value will then be an array of structs, where each struct
+      contains the keys <code>group</code> (group name), <code>name</code>
+      (process name), <code>description</code> (process description), and
+      <code>status</code> (fault code).
+    </para>
       
     <para>
-       If any process cannot be stopped then the fault <code>FAILED</code>
-       will be raised. This is abnormal and results in Supervisor being in a
-       potentially unstable condition.
+       If any process cannot be stopped then the fault code for
+       <code>FAILED</code> will be reported in its return struct. This is
+       abnormal and results in Supervisor being in a potentially unstable
+       condition.
     </para>
-    
+
     <para>
-      This method is asynchronous.  It will return before the processes have
-      been killed.  Once each process has been killed, they will be
-      removed from Supervisor’s process table.
+      If <code>wait=False</code>, the method will return immediately without
+      waiting for Supervisor to stop any of the processes.  The return value 
+      will always be boolean True.
     </para>
   </sect2>
 
@@ -562,6 +582,13 @@
           </row>
         </thead>
         <tbody>
+          <row>
+            <entry>boolean</entry>
+            <entry>wait</entry>
+            <entry>
+              Wait for stop to complete before returning? (optional, default True)
+            </entry>
+          </row>
         </tbody>
       </tgroup>
     </table>
@@ -576,10 +603,10 @@
           </row>
         </thead>
           <tbody>
-              <row>
-                <entry>boolean</entry>
-                <entry>Always <code>TRUE</code></entry>                    
-              </row>
+            <row>
+              <entry>boolean or array&lt;struct&gt;</entry>
+              <entry>See below</entry>                    
+            </row>
           </tbody>
       </tgroup>
     </table>      
@@ -589,18 +616,31 @@
       is the equivalent of calling <code>supervisor.stopProcess()</code> on
       every running process. 
     </para>
-      
+
     <para>
-       If any process cannot be stopped then the fault <code>FAILED</code>
-       will be raised. This is abnormal and results in Supervisor being in a
-       potentially unstable condition.
+      If <code>wait=True</code>, Supervisor hold the HTTP request until each
+      process has been stopped (or tries to stop have been exhausted).
+    </para>
+
+    <para>
+      The return value will then be an array of structs, where each struct
+      contains the keys <code>group</code> (group name), <code>name</code>
+      (process name), <code>description</code> (process description), and
+      <code>status</code> (fault code).
     </para>
       
     <para>
-      This method is asynchronous.  It will return before the processes have
-      been killed.  Once each process has been killed, they will be
-      removed from Supervisor’s process table.
-    </para>    
+       If any process cannot be stopped then the fault code for
+       <code>FAILED</code> will be reported in its return struct. This is
+       abnormal and results in Supervisor being in a potentially unstable
+       condition.
+    </para>
+
+    <para>
+      If <code>wait=False</code>, the method will return immediately without
+      waiting for Supervisor to stop any of the processes.  The return value 
+      will always be boolean True.
+    </para>
   </sect2>
 
   <sect2 id="api.process-control.supervisor-sendProcessStdin">