← Back to branch summary

~rdoering/ubuntu/karmic/erlang/fix-535090

« back to all changes in this revision

Viewing changes to lib/kernel/doc/src/wrap_log_reader.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-02-15 16:42:52 UTC
  • mfrom: (1.1.13 upstream)
  • mto: (3.3.1 squeeze)
  • mto: This revision was merged to the branch mainline in revision 17.
  • Revision ID: james.westby@ubuntu.com-20090215164252-dxpjjuq108nz4noa
Upload to unstable after lenny is released.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/kernel/doc/src/wrap_log_reader.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
 
3
 
 
4
<erlref>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>1998</year>
 
8
      <year>2007</year>
 
9
      <holder>Ericsson AB, All Rights Reserved</holder>
 
10
    </copyright>
 
11
    <legalnotice>
 
12
  The contents of this file are subject to the Erlang Public License,
 
13
  Version 1.1, (the "License"); you may not use this file except in
 
14
  compliance with the License. You should have received a copy of the
 
15
  Erlang Public License along with this software. If not, it can be
 
16
  retrieved online at http://www.erlang.org/.
 
17
 
 
18
  Software distributed under the License is distributed on an "AS IS"
 
19
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
20
  the License for the specific language governing rights and limitations
 
21
  under the License.
 
22
 
 
23
  The Initial Developer of the Original Code is Ericsson AB.
 
24
    </legalnotice>
 
25
 
 
26
    <title>wrap_log_reader</title>
 
27
    <prepared>Esko Vierum&auml;ki</prepared>
 
28
    <responsible>Esko Vierum&auml;ki</responsible>
 
29
    <docno></docno>
 
30
    <approved>nobody</approved>
 
31
    <checked>no</checked>
 
32
    <date>98-09-21</date>
 
33
    <rev>A</rev>
 
34
    <file>wrap_log_reader.sgml</file>
 
35
  </header>
 
36
  <module>wrap_log_reader</module>
 
37
  <modulesummary>A function to read internally formatted wrap disk logs</modulesummary>
 
38
  <description>
 
39
    <p><c>wrap_log_reader</c> is a function to read internally formatted
 
40
      wrap disk logs, refer to disk_log(3). <c>wrap_log_reader</c> does not
 
41
      interfere with disk_log activities; there is however a known bug in this
 
42
      version of the <c>wrap_log_reader</c>, see chapter <c>bugs</c> below.
 
43
      </p>
 
44
    <p>A wrap disk log file consists of several files, called index files. 
 
45
      A log file can be opened and closed. It is also possible to open just one index file
 
46
      separately. If an non-existent or a non-internally formatted file is opened,
 
47
      an error message is returned. If the file is corrupt, no attempt to repair it
 
48
      will be done but an error message is returned. 
 
49
      </p>
 
50
    <p>If a log is configured to be distributed, there is a possibility that all items 
 
51
      are not loggen on all nodes. <c>wrap_log_reader</c> does only read the log on
 
52
      the called node, it is entirely up to the user to be sure that all items are read.
 
53
      </p>
 
54
  </description>
 
55
  <funcs>
 
56
    <func>
 
57
      <name>chunk(Continuation)</name>
 
58
      <name>chunk(Continuation, N) -> {Continuation2, Terms} |  {Continuation2, Terms, Badbytes} | {Continuation2, eof} | {error, Reason}</name>
 
59
      <fsummary>Read a chunk of objects written to a wrap log.</fsummary>
 
60
      <type>
 
61
        <v>Continuation = continuation()</v>
 
62
        <v>N = int() > 0 | infinity</v>
 
63
        <v>Continuation2 = continuation()</v>
 
64
        <v>Terms= [term()]</v>
 
65
        <v>Badbytes = integer()</v>
 
66
      </type>
 
67
      <desc>
 
68
        <p>This function makes it possible to efficiently read the
 
69
          terms which have been appended to a log. It minimises disk
 
70
          I/O by reading large 8K chunks from the file.
 
71
          </p>
 
72
        <p>The first time <c>chunk</c> is called an initial
 
73
          continuation returned from the <c>open/1</c>, <c>open/2</c> must be provided.
 
74
          </p>
 
75
        <p>When <c>chunk/3</c> is called, <c>N</c> controls the
 
76
          maximum number of terms that are read from the log in each
 
77
          chunk.  Default is <c>infinity</c>, which means that all the
 
78
          terms contained in the 8K chunk are read. If less than
 
79
          <c>N</c> terms are returned, this does not necessarily mean
 
80
          that end of file is reached.
 
81
          </p>
 
82
        <p>The <c>chunk</c> function returns a tuple
 
83
          <c>{Continuation2, Terms}</c>, where <c>Terms</c> is a list
 
84
          of terms found in the log. <c>Continuation2</c> is yet
 
85
          another continuation which must be passed on into any
 
86
          subsequent calls to <c>chunk</c>. With a series of calls to
 
87
          <c>chunk</c> it is then possible to extract all terms from a
 
88
          log.
 
89
          </p>
 
90
        <p>The <c>chunk</c> function returns a tuple
 
91
          <c>{Continuation2, Terms, Badbytes}</c> if the log is opened
 
92
          in read only mode and the read chunk is corrupt. <c>Badbytes</c> 
 
93
          indicates the number of non-Erlang terms found in the chunk.
 
94
          Note also that the log is not repaired.
 
95
          </p>
 
96
        <p><c>chunk</c> returns <c>{Continuation2, eof}</c> when the end of the log is
 
97
          reached, and <c>{error, Reason}</c> if an error occurs.
 
98
          </p>
 
99
        <p>The returned continuation may or may not be valid in the next call to
 
100
          <c>chunk</c>.  This is because the log may wrap and delete
 
101
          the file into which the continuation points. To make sure
 
102
          this does not happen, the log can be blocked during the
 
103
          search.
 
104
          </p>
 
105
      </desc>
 
106
    </func>
 
107
    <func>
 
108
      <name>close(Continuation) -> ok </name>
 
109
      <fsummary>Close a log</fsummary>
 
110
      <type>
 
111
        <v>Continuation = continuation()</v>
 
112
      </type>
 
113
      <desc>
 
114
        <p>This function closes a log file properly.
 
115
          </p>
 
116
      </desc>
 
117
    </func>
 
118
    <func>
 
119
      <name>open(Filename) -> OpenRet</name>
 
120
      <name>open(Filename, N) -> OpenRet</name>
 
121
      <fsummary>Open a log file</fsummary>
 
122
      <type>
 
123
        <v>File = string() | atom()</v>
 
124
        <v>N = integer()</v>
 
125
        <v>OpenRet = {ok, Continuation} | {error, Reason} </v>
 
126
        <v>Continuation = continuation()</v>
 
127
      </type>
 
128
      <desc>
 
129
        <p><c>Filename</c> specifies the name of the file which is to be read. </p>
 
130
        <p><c>N</c> specifies the index of the file which is to be read. 
 
131
          If <c>N</c> is omitted the whole wrap log file will be read; if it
 
132
          is specified only the specified index file will be read.\011     
 
133
          </p>
 
134
        <p>The <c>open</c> function returns <c>{ok, Continuation}</c> if the
 
135
          log/index file was successfully opened. The <c>Continuation</c>
 
136
          is to be used when chunking or closing the file. 
 
137
          </p>
 
138
        <p>The function returns <c>{error, Reason}</c> for all errors.
 
139
          </p>
 
140
      </desc>
 
141
    </func>
 
142
  </funcs>
 
143
 
 
144
  <section>
 
145
    <title>Bugs</title>
 
146
    <p>This version of the <c>wrap_log_reader</c> does not detect if the <c>disk_log</c>
 
147
      wraps to a new index file between a <c>wrap_log_reader:open</c> and the first 
 
148
      <c>wrap_log_reader:chunk</c>.
 
149
      In this case the chuck will actually read the last logged items in the log file,
 
150
      because the opened index file was truncated by the <c>disk_log</c>.
 
151
      </p>
 
152
  </section>
 
153
 
 
154
  <section>
 
155
    <title>See Also</title>
 
156
    <p><seealso marker="disk_log">disk_log(3)</seealso></p>
 
157
  </section>
 
158
</erlref>
 
159