aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/wrap_log_reader.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/kernel/doc/src/wrap_log_reader.xml')
-rw-r--r--lib/kernel/doc/src/wrap_log_reader.xml154
1 files changed, 77 insertions, 77 deletions
diff --git a/lib/kernel/doc/src/wrap_log_reader.xml b/lib/kernel/doc/src/wrap_log_reader.xml
index c021f42cac..7fb9c1c023 100644
--- a/lib/kernel/doc/src/wrap_log_reader.xml
+++ b/lib/kernel/doc/src/wrap_log_reader.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1998</year><year>2013</year>
+ <year>1998</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -26,39 +26,43 @@
<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>
+ <approved></approved>
+ <checked></checked>
+ <date>1998-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>
+ <modulesummary>A service 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>
+ <p>This module makes it possible to read internally formatted
+ wrap disk logs, see
+ <seealso marker="disk_log"><c>disk_log(3)</c></seealso>.
+ <c>wrap_log_reader</c> does not
+ interfere with <c>disk_log</c> activities; there is however a bug in this
+ version of the <c>wrap_log_reader</c>, see section
+ <seealso marker="#bugs">Known Limitations</seealso>.</p>
+ <p>A wrap disk log file consists of many files, called index files. A log
+ file can be opened and closed. Also, a single index file can be opened
+ separately. If a non-existent or non-internally formatted file is opened,
+ an error message is returned. If the file is corrupt, no attempt is made
+ to repair it, but an error message is returned.</p>
+ <p>If a log is configured to be distributed, it is possible that all items
+ are not logged on all nodes. <c>wrap_log_reader</c> only reads the log on
+ the called node; it is up to the user to be sure that all items
+ are read.</p>
</description>
+
<datatypes>
<datatype>
<name name="continuation"/>
- <desc><p>Continuation returned by
- <c>open/1,2</c> or <c>chunk/1,2</c>.</p>
+ <desc>
+ <p>Continuation returned by <c>open/1,2</c> or <c>chunk/1,2</c>.</p>
</desc>
</datatype>
</datatypes>
+
<funcs>
<func>
<name name="chunk" arity="1"/>
@@ -66,87 +70,83 @@
<fsummary>Read a chunk of objects written to a wrap log.</fsummary>
<type name="chunk_ret"/>
<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>Enables to efficiently read the
+ terms that are appended to a log. Minimises disk
+ I/O by reading 64 kilobyte chunks from the file.</p>
+ <p>The first time <c>chunk()</c> is called, an initial
+ continuation returned from <c>open/1</c> or <c>open/2</c> must be
+ provided.</p>
<p>When <c>chunk/3</c> is called, <c><anno>N</anno></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
+ chunk. Defaults to <c>infinity</c>, which means that all the
terms contained in the 8K chunk are read. If less than
- <c><anno>N</anno></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>{<anno>Continuation2</anno>, <anno>Terms</anno>}</c>, where <c><anno>Terms</anno></c> is a list
+ <c><anno>N</anno></c> terms are returned, this does not necessarily
+ mean that end of file is reached.</p>
+ <p>Returns a tuple <c>{<anno>Continuation2</anno>,
+ <anno>Terms</anno>}</c>, where <c><anno>Terms</anno></c> is a list
of terms found in the log. <c><anno>Continuation2</anno></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>{<anno>Continuation2</anno>, <anno>Terms</anno>, <anno>Badbytes</anno>}</c> if the log is opened
- in read only mode and the read chunk is corrupt. <c><anno>Badbytes</anno></c>
+ another continuation that must be passed on to 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>Returns a tuple <c>{<anno>Continuation2</anno>,
+ <anno>Terms</anno>, <anno>Badbytes</anno>}</c> if the log is opened
+ in read only mode and the read chunk is corrupt.
+ <c><anno>Badbytes</anno></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>{<anno>Continuation2</anno>, eof}</c> when the end of the log is
- reached, and <c>{error, <anno>Reason</anno>}</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>
+ Notice that the log is not repaired.</p>
+ <p>Returns <c>{<anno>Continuation2</anno>, eof}</c> when
+ the end of the log is reached, and <c>{error, <anno>Reason</anno>}</c>
+ if an error occurs.</p>
+ <p>The returned continuation either is or is not valid in the next call
+ to this function. This is because the log can wrap and delete
+ the file into which the continuation points. To ensure
+ this does not occur, the log can be blocked during the search.</p>
</desc>
</func>
+
<func>
<name name="close" arity="1"/>
- <fsummary>Close a log</fsummary>
+ <fsummary>Close a log.</fsummary>
<desc>
- <p>This function closes a log file properly.
- </p>
+ <p>Closes a log file properly.</p>
</desc>
</func>
+
<func>
<name name="open" arity="1"/>
<name name="open" arity="2"/>
- <fsummary>Open a log file</fsummary>
+ <fsummary>Open a log file.</fsummary>
<type name="open_ret"/>
<desc>
- <p><c><anno>Filename</anno></c> specifies the name of the file which is to be read. </p>
- <p><c><anno>N</anno></c> specifies the index of the file which is to be read.
- If <c><anno>N</anno></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, <anno>Continuation</anno>}</c> if the
- log/index file was successfully opened. The <c><anno>Continuation</anno></c>
- is to be used when chunking or closing the file.
- </p>
- <p>The function returns <c>{error, <anno>Reason</anno>}</c> for all errors.
- </p>
+ <p><c><anno>Filename</anno></c> specifies the name of the file to be
+ read.</p>
+ <p><c><anno>N</anno></c> specifies the index of the file to be read.
+ If <c><anno>N</anno></c> is omitted, the whole wrap log file is read;
+ if it is specified, only the specified index file is read.</p>
+ <p>Returns <c>{ok, <anno>Continuation</anno>}</c> if the
+ log/index file is opened successfully.
+ <c><anno>Continuation</anno></c>
+ is to be used when chunking or closing the file.</p>
+ <p>Returns <c>{error, <anno>Reason</anno>}</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>
+ <title>Known Limitations</title>
+ <marker id="bugs"/>
+ <p>This version of <c>wrap_log_reader</c> does not detect if
+ <c>disk_log</c> wraps to a new index file between a call to
+ <c>wrap_log_reader:open()</c> and the first call to
+ <c>wrap_log_reader:chunk()</c>.
+ If this occurs, the call to <c>chunk()</c> reads the last logged
+ items in the log file, as the opened index file was truncated by
+ <c>disk_log</c>.</p>
</section>
<section>
<title>See Also</title>
- <p><seealso marker="disk_log">disk_log(3)</seealso></p>
+ <p><seealso marker="disk_log"><c>disk_log(3)</c></seealso></p>
</section>
</erlref>