From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/kernel/doc/src/wrap_log_reader.xml | 157 +++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 lib/kernel/doc/src/wrap_log_reader.xml (limited to 'lib/kernel/doc/src/wrap_log_reader.xml') 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 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + wrap_log_reader + Esko Vierumäki + Esko Vierumäki + + nobody + no + 98-09-21 + A + wrap_log_reader.sgml +
+ wrap_log_reader + A function to read internally formatted wrap disk logs + +

wrap_log_reader is a function to read internally formatted + wrap disk logs, refer to disk_log(3). wrap_log_reader does not + interfere with disk_log activities; there is however a known bug in this + version of the wrap_log_reader, see chapter bugs below. +

+

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. +

+

If a log is configured to be distributed, there is a possibility that all items + are not loggen on all nodes. wrap_log_reader does only read the log on + the called node, it is entirely up to the user to be sure that all items are read. +

+ + + + chunk(Continuation) + chunk(Continuation, N) -> {Continuation2, Terms} | {Continuation2, Terms, Badbytes} | {Continuation2, eof} | {error, Reason} + Read a chunk of objects written to a wrap log. + + Continuation = continuation() + N = int() > 0 | infinity + Continuation2 = continuation() + Terms= [term()] + Badbytes = integer() + + +

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. +

+

The first time chunk is called an initial + continuation returned from the open/1, open/2 must be provided. +

+

When chunk/3 is called, N controls the + maximum number of terms that are read from the log in each + chunk. Default is infinity, which means that all the + terms contained in the 8K chunk are read. If less than + N terms are returned, this does not necessarily mean + that end of file is reached. +

+

The chunk function returns a tuple + {Continuation2, Terms}, where Terms is a list + of terms found in the log. Continuation2 is yet + another continuation which must be passed on into any + subsequent calls to chunk. With a series of calls to + chunk it is then possible to extract all terms from a + log. +

+

The chunk function returns a tuple + {Continuation2, Terms, Badbytes} if the log is opened + in read only mode and the read chunk is corrupt. Badbytes + indicates the number of non-Erlang terms found in the chunk. + Note also that the log is not repaired. +

+

chunk returns {Continuation2, eof} when the end of the log is + reached, and {error, Reason} if an error occurs. +

+

The returned continuation may or may not be valid in the next call to + chunk. 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. +

+ + + + close(Continuation) -> ok + Close a log + + Continuation = continuation() + + +

This function closes a log file properly. +

+ + + + open(Filename) -> OpenRet + open(Filename, N) -> OpenRet + Open a log file + + File = string() | atom() + N = integer() + OpenRet = {ok, Continuation} | {error, Reason} + Continuation = continuation() + + +

Filename specifies the name of the file which is to be read.

+

N specifies the index of the file which is to be read. + If N is omitted the whole wrap log file will be read; if it + is specified only the specified index file will be read. +

+

The open function returns {ok, Continuation} if the + log/index file was successfully opened. The Continuation + is to be used when chunking or closing the file. +

+

The function returns {error, Reason} for all errors. +

+ + + + +
+ Bugs +

This version of the wrap_log_reader does not detect if the disk_log + wraps to a new index file between a wrap_log_reader:open and the first + wrap_log_reader:chunk. + 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 disk_log. +

+
+ +
+ See Also +

disk_log(3)

+
+ + -- cgit v1.2.3