wrap_log_reader
(kernel)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.
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()}
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,
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
terms are returned, this does not necessarily mean
that end of file is reached.
The chunk
function returns a tuple
{
, where
is a list
of terms found in the log.
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
{
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.
Note also that the log is not repaired.
chunk
returns {
when the end of the log is
reached, and {error,
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 | {error, Reason}
Continuation = continuation()
Reason = file:posix()
This function 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 which is to be read.
specifies the index of the file which is to be read.
If
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,
if the
log/index file was successfully opened. The
is to be used when chunking or closing the file.
The function returns {error,
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
.