wrap_log_reader(3)

✨ wrap_log_reader ✨

okay so this is a manual page for wrap_log_reader, which lives in the Erlang Module Definition corner of the universe 💖

---

💫 NAME 💫

wrap_log_reader — a service to read internally formatted wrap disk logs. bestie, it reads logs. that's the whole vibe 🎀

---

🌸 DESCRIPTION 🌸

This module makes it possible to read internally formatted wrap disk logs, see disk_log. wrap_log_reader does not interfere with disk_log activities — iconic behaviour, honestly, it minds its own business 💅. there is however a bug in this version of the wrap_log_reader, see section Known Limitations. yeah. we'll get to that 🙈

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 — it does not fix things, it simply tells you. lowkey respectful.

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 — so it's up to you, the user, to be sure that all items are read. no cap, that part is on you 🫶

🌈 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/1 and the first call to wrap_log_reader:chunk/1. If this occurs, the call to chunk/1 reads the last logged items in the log file, as the opened index file was truncated by disk_log. 💀 yeah. that's the bug. noted, logged, moving on.

---

🦋 DATA TYPES 🦋

chunk_ret() ::
          {Continuation2 :: term(), Terms :: [term()]} |
          {Continuation2 :: term(),
           Terms :: [term()],
           Badbytes :: non_neg_integer()} |
          {Continuation2 :: term(), eof} |
          {error, Reason :: term()}.

• -opaque continuation() — the continuation returned by open/1,2 or chunk/1,2. it's opaque, so like… don't peek, just pass it along 💜

open_ret() ::
          {ok, Continuation :: continuation()} |
          {error, Reason :: tuple()}.

---

👑 FUNCTIONS 👑

chunk(Continuation, N) -> chunk_ret()

with

Continuation :: continuation(),
N :: infinity | pos_integer().

Enables you to efficiently read the terms that are appended to a log 🔥. It minimises disk I/O by reading 64 kilobyte chunks from the file. efficiency queen.

The first time chunk/2 is called, an initial continuation returned from open/1 or open/2 must be provided ✨.

When chunk/2 is called, N controls the maximum number of terms that are read from the log in each chunk. infinity 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 👀 (do not assume, bestie).

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. slay, a little relay race 🏃♀️

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. it saw the mess and left it there 😭

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 — protecting your peace fr fr 🫶

close(Continuation) -> ok | {error, Reason}

with

Continuation :: continuation(),
Reason :: file:posix().

Closes a log file properly. clean exit, we love to see it 💖

open(Filename) -> open_ret()

with

Filename :: string() | atom().

Equivalent to open(Filename, ...) except that the whole wrap log file is read. everything. all of it. periodt 🎀

open(Filename, N) -> open_ret()

with

Filename :: string() | atom(),
N :: integer().

Filename specifies the name of the file to be read.

N specifies the index of the file to be read. Use open/1 to read the entire wrap log.

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.

---

reminder bestie: if a file is missing or not internally formatted, you get an error message. if it's corrupt, it does not get repaired, you just get an error. and that Known Limitations bug where disk_log wraps to a new index file between open/1 and the first chunk/1? still real. stay safe out there 🦋

---

okay that's the whole page!! brought to you with love by Ericsson AB, rocking kernel 11.0.3 — that's the wrap_log_reader(3) energy, mwah 💅💖✨