NAME

       wrap_log_reader - A function to read internally formatted wrap disk logs

DESCRIPTION

       wrap_log_reader  is  a  function  to  read  internally  formatted wrap disk logs, refer to
       disk_log(3erl). 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.

DATA TYPES

       continuation()

              Continuation returned by open/1,2 or chunk/1,2.

EXPORTS

       chunk(Continuation) -> chunk_ret()

       chunk(Continuation, N) -> chunk_ret()

              Types:

                 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, 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 | {error, Reason}

              Types:

                 Continuation = continuation()
                 Reason = file:posix()

              This function closes a log file properly.

       open(Filename) -> open_ret()

       open(Filename, N) -> open_ret()

              Types:

                 Filename = string() | atom()
                 N = integer()
                 open_ret() = {ok, Continuation :: continuation()}
                            | {error, Reason :: tuple()}

              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(3erl)