diff options
Diffstat (limited to 'lib/kernel/doc/src/wrap_log_reader.xml')
| -rw-r--r-- | lib/kernel/doc/src/wrap_log_reader.xml | 157 |
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äki</prepared> + <responsible>Esko Vierumä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> + |