The R13B03 release.OTP_R13B03

1 files changed, 157 insertions, 0 deletions

diff --git a/lib/kernel/doc/src/wrap_log_reader.xml b/lib/kernel/doc/src/wrap_log_reader.xml
new file mode 100644
index 0000000000..18664a029f
--- /dev/null
+++ b/lib/kernel/doc/src/wrap_log_reader.xml
@@ -0,0 +1,157 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>1998</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>wrap_log_reader</title>
+    <prepared>Esko Vierum&auml;ki</prepared>
+    <responsible>Esko Vierum&auml;ki</responsible>
+    <docno></docno>
+    <approved>nobody</approved>
+    <checked>no</checked>
+    <date>98-09-21</date>
+    <rev>A</rev>
+    <file>wrap_log_reader.sgml</file>
+  </header>
+  <module>wrap_log_reader</module>
+  <modulesummary>A function to read internally formatted wrap disk logs</modulesummary>
+  <description>
+    <p><c>wrap_log_reader</c> is a function to read internally formatted
+      wrap disk logs, refer to disk_log(3). <c>wrap_log_reader</c> does not
+      interfere with disk_log activities; there is however a known bug in this
+      version of the <c>wrap_log_reader</c>, see chapter <c>bugs</c> below.
+      </p>
+    <p>A wrap disk log file consists of several files, called index files. 
+      A log file can be opened and closed. It is also possible to open just one index file
+      separately. If an non-existent or a non-internally formatted file is opened,
+      an error message is returned. If the file is corrupt, no attempt to repair it
+      will be done but an error message is returned. 
+      </p>
+    <p>If a log is configured to be distributed, there is a possibility that all items 
+      are not loggen on all nodes. <c>wrap_log_reader</c> does only read the log on
+      the called node, it is entirely up to the user to be sure that all items are read.
+      </p>
+  </description>
+  <funcs>
+    <func>
+      <name>chunk(Continuation)</name>
+      <name>chunk(Continuation, N) -> {Continuation2, Terms} |  {Continuation2, Terms, Badbytes} | {Continuation2, eof} | {error, Reason}</name>
+      <fsummary>Read a chunk of objects written to a wrap log.</fsummary>
+      <type>
+        <v>Continuation = continuation()</v>
+        <v>N = int() > 0 | infinity</v>
+        <v>Continuation2 = continuation()</v>
+        <v>Terms= [term()]</v>
+        <v>Badbytes = integer()</v>
+      </type>
+      <desc>
+        <p>This function makes it possible to efficiently read the
+          terms which have been appended to a log. It minimises disk
+          I/O by reading large 8K chunks from the file.
+          </p>
+        <p>The first time <c>chunk</c> is called an initial
+          continuation returned from the <c>open/1</c>, <c>open/2</c> must be provided.
+          </p>
+        <p>When <c>chunk/3</c> is called, <c>N</c> controls the
+          maximum number of terms that are read from the log in each
+          chunk.  Default is <c>infinity</c>, which means that all the
+          terms contained in the 8K chunk are read. If less than
+          <c>N</c> terms are returned, this does not necessarily mean
+          that end of file is reached.
+          </p>
+        <p>The <c>chunk</c> function returns a tuple
+          <c>{Continuation2, Terms}</c>, where <c>Terms</c> is a list
+          of terms found in the log. <c>Continuation2</c> is yet
+          another continuation which must be passed on into any
+          subsequent calls to <c>chunk</c>. With a series of calls to
+          <c>chunk</c> it is then possible to extract all terms from a
+          log.
+          </p>
+        <p>The <c>chunk</c> function returns a tuple
+          <c>{Continuation2, Terms, Badbytes}</c> if the log is opened
+          in read only mode and the read chunk is corrupt. <c>Badbytes</c> 
+          indicates the number of non-Erlang terms found in the chunk.
+          Note also that the log is not repaired.
+          </p>
+        <p><c>chunk</c> returns <c>{Continuation2, eof}</c> when the end of the log is
+          reached, and <c>{error, Reason}</c> if an error occurs.
+          </p>
+        <p>The returned continuation may or may not be valid in the next call to
+          <c>chunk</c>.  This is because the log may wrap and delete
+          the file into which the continuation points. To make sure
+          this does not happen, the log can be blocked during the
+          search.
+          </p>
+      </desc>
+    </func>
+    <func>
+      <name>close(Continuation) -> ok </name>
+      <fsummary>Close a log</fsummary>
+      <type>
+        <v>Continuation = continuation()</v>
+      </type>
+      <desc>
+        <p>This function closes a log file properly.
+          </p>
+      </desc>
+    </func>
+    <func>
+      <name>open(Filename) -> OpenRet</name>
+      <name>open(Filename, N) -> OpenRet</name>
+      <fsummary>Open a log file</fsummary>
+      <type>
+        <v>File = string() | atom()</v>
+        <v>N = integer()</v>
+        <v>OpenRet = {ok, Continuation} | {error, Reason} </v>
+        <v>Continuation = continuation()</v>
+      </type>
+      <desc>
+        <p><c>Filename</c> specifies the name of the file which is to be read. </p>
+        <p><c>N</c> specifies the index of the file which is to be read. 
+          If <c>N</c> is omitted the whole wrap log file will be read; if it
+          is specified only the specified index file will be read.
+          </p>
+        <p>The <c>open</c> function returns <c>{ok, Continuation}</c> if the
+          log/index file was successfully opened. The <c>Continuation</c>
+          is to be used when chunking or closing the file. 
+          </p>
+        <p>The function returns <c>{error, Reason}</c> for all errors.
+          </p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>Bugs</title>
+    <p>This version of the <c>wrap_log_reader</c> does not detect if the <c>disk_log</c>
+      wraps to a new index file between a <c>wrap_log_reader:open</c> and the first 
+      <c>wrap_log_reader:chunk</c>.
+      In this case the chuck will actually read the last logged items in the log file,
+      because the opened index file was truncated by the <c>disk_log</c>.
+      </p>
+  </section>
+
+  <section>
+    <title>See Also</title>
+    <p><seealso marker="disk_log">disk_log(3)</seealso></p>
+  </section>
+</erlref>
+