bionic (3) wrap_log_reader.3erl.gz

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)