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

[Mike Naberezny]

Author: Mike Naberezny <mike at maintainable.com>
Date: Mon Oct 13 14:37:01 2008
New Revision: 819

Log:
Document tailProcessStdoutLog() and tailProcessStderrLog().

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

Modified: supervisor_manual/trunk/chapters/api-process-logging.xml
==============================================================================
--- supervisor_manual/trunk/chapters/api-process-logging.xml	(original)
+++ supervisor_manual/trunk/chapters/api-process-logging.xml	Mon Oct 13 14:37:01 2008
@@ -7,7 +7,7 @@
     controlling.  This data can be read through the API.
   </para>
 
-  <sect2 id="api.process-logging.readstdoutprocesslog">
+  <sect2 id="api.process-logging.readprocessstdoutlog">
     <title>supervisor.readProcessStdoutLog()</title>
 
     <para>
@@ -153,7 +153,7 @@
     </note>
   </sect2>
 
-  <sect2 id="api.process-logging.readstdoutprocesslog">
+  <sect2 id="api.process-logging.readprocessstderrlog">
     <title>supervisor.readProcessStderrLog()</title>
 
     <para>
@@ -167,6 +167,111 @@
       that it reads the log for the process' <code>STDERR</code> file descriptor.
     </para>
   </sect2>
+  
+  <sect2 id="api.process-logging.tailProcessStdoutLog">
+    <title>supervisor.tailProcessStdoutLog()</title>
+
+    <para>
+      <programlisting><![CDATA[
+supervisor.tailProcessStdoutLog(namespec, offset, length)
+]]></programlisting>
+    </para>
+
+    <table>
+      <title>supervisor.tailProcessStdoutLog() Parameters</title>
+      <tgroup cols="2">
+        <thead>
+          <row>
+            <entry>Type</entry>
+            <entry>Name</entry>
+            <entry>Description</entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry>string</entry>
+            <entry>namespec</entry>
+            <entry>Name of the group and process</entry>
+          </row>
+          <row>
+            <entry>integer</entry>
+            <entry>offset</entry>
+            <entry>
+              Character offset to read from, with 0 being the first character
+              of the log.
+            </entry>
+          </row>
+          <row>
+            <entry>integer</entry>
+            <entry>length</entry>
+            <entry>
+              Number of characters to read.  If zero, no characters are returned.
+            </entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+
+    <table>
+      <title>supervisor.tailProcessStdoutLog() Return Value</title>
+      <tgroup cols="2">
+        <thead>
+          <row>
+            <entry>Type</entry>
+            <entry>Description</entry>
+          </row>
+        </thead>
+          <tbody>
+              <row>
+                <entry>array</entry>
+                <entry><code>[string chars, int offset, boolean overflow]</code></entry>                    
+              </row>
+          </tbody>
+      </tgroup>
+    </table>      
+    
+    <para>
+      The <code>tailProcessStdoutLog()</code> method provides a more efficient way 
+      to tail the STDOUT log than <code>readProcessStdoutLog()</code>.  Use 
+      <code>readProcessStdoutLog()</code> to read chunks and poll with 
+      <code>tailProcessStdoutLog()</code> to tail.
+    </para>
+    
+    <para>
+      Call the method by passing <code>length</code> for the number of characters to read
+      from <code>namespec</code>'s STDOUT log, starting at byte <code>offset</code>
+      where 0 is the beginning of the log.  If the total log size is greater than 
+      <code>offset + length</code>, the overflow flag is set and the <code>offset</code> 
+      is automatically increased to position the buffer at the end of the log.  If less 
+      than <code>length</code> characters are available, the maximum number of 
+      available characters from the offset will be returned.
+    </para>
+    
+    <para>
+      The return value is an array where the first element is a string containing any
+      characters read.  The second element is always the last offset in the log + 1, which
+      would be passed back to <code>tailProcessStdoutLog()</code> on the next poll.  The
+      last element is the overflow flag, where <code>True</code> indicates an overflow occurred 
+      and some data was missed.  If an error occurs, the return value will be 
+      <code>["", offset, False]</code>.
+    </para>
+
+  </sect2>
+
+  <sect2 id="api.process-logging.tailprocessstderrlog">
+    <title>supervisor.tailProcessStderrLog()</title>
+
+    <para>
+      <programlisting><![CDATA[
+supervisor.tailProcessStdoutLog(namespec, offset, length)
+]]></programlisting>
+    </para>
+
+    <para>
+      This method has the same behavior as <code>supervisor.tailProcessStdoutLog()</code> except
+      that it tails the log for the process' <code>STDERR</code> file descriptor.
+    </para>
+  </sect2>
 
   <sect2 id="api.process-logging.clearprocesslogs">
     <title>supervisor.clearProcessLogs()</title>