NAME

       wrap_log_reader - A service to read internally formatted wrap disk logs.

DESCRIPTION

       This  module  makes  it  possible  to  read  internally  formatted  wrap  disk  logs,  see
       disk_log(3erl). 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.

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()}

              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, N 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 N terms are  returned,  this  does
              not necessarily mean that end of file is reached.

              Returns a tuple {Continuation2, Terms}, where Terms is a list of terms found in the
              log. Continuation2 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 {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. Notice that the log is not repaired.

              Returns {Continuation2, eof} when the end  of  the  log  is  reached,  and  {error,
              Reason} 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}

              Types:

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

              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 to be read.

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

              Returns   {ok,   Continuation}  if  the  log/index  file  is  opened  successfully.
              Continuation is to be used when chunking or closing the file.

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

SEE ALSO

       disk_log(3erl)