A service to read internally formatted wrap disk logs.
This module makes it possible to read internally formatted
wrap disk logs, see
disk_log(3)
.
wrap_log_reader
does not
interfere with disk_log
activities; there is however a bug in this
version of the wrap_log_reader
, see section
Known Limitations.
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.
If a log is configured to be distributed, it is possible that all items
are not logged on all nodes. wrap_log_reader
only reads the log on
the called node; it is up to the user to be sure that all items
are read.
Functions
chunk(Continuation) -> chunk_ret()
Continuation = continuation()
chunk(Continuation, N) -> chunk_ret()
Continuation = continuation()
N = infinity | integer() >= 1
chunk_ret() =
{Continuation2, Terms :: [term()]} |
{Continuation2,
Terms :: [term()],
Badbytes :: integer() >= 0} |
{Continuation2, eof} |
{error, Reason :: term()}
Enables to efficiently read the terms that are appended to a log. Minimises disk I/O by reading 64 kilobyte chunks from the file.
The first time chunk()
is called, an initial
continuation returned from open/1
or open/2
must be
provided.
When chunk/3
is called,
controls the
maximum number of terms that are read from the log in each
chunk. Defaults to infinity
, which means that all the
terms contained in the 8K chunk are read. If less than
terms are returned, this does not necessarily
mean that end of file is reached.
Returns a tuple {
, where
is a list
of terms found in the log.
is yet
another continuation that must be passed on to any
subsequent calls to chunk()
. With a series of calls to
chunk()
, it is then possible to extract all terms from a log.
Returns a tuple {
if the log is opened
in read only mode and the read chunk is corrupt.
indicates the number of non-Erlang terms found in the chunk.
Notice that the log is not repaired.
Returns {
when
the end of the log is reached, and {error,
if an error occurs.
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.
close(Continuation) -> ok | {error, Reason}
Continuation = continuation()
Reason = file:posix()
Closes a log file properly.
open(Filename) -> open_ret()
Filename = string() | atom()
open(Filename, N) -> open_ret()
Filename = string() | atom()
N = integer()
open_ret() =
{ok, Continuation :: continuation()} |
{error, Reason :: tuple()}
specifies the name of the file to be
read.
specifies the index of the file to be read.
If
is omitted, the whole wrap log file is read;
if it is specified, only the specified index file is read.
Returns {ok,
if the
log/index file is opened successfully.
is to be used when chunking or closing the file.
Returns {error,
for all errors.
Known Limitations
This version of wrap_log_reader
does not detect if
disk_log
wraps to a new index file between a call to
wrap_log_reader:open()
and the first call to
wrap_log_reader:chunk()
.
If this occurs, the call to chunk()
reads the last logged
items in the log file, as the opened index file was truncated by
disk_log
.