RECORDER(3)

💖 RECORDER(3) — the Recorder Library glow-up 💖

okay bestie, welcome to the Recorder Library girlies ✨ this is the page for RECORDER, RECORDER_DEFINE, and RECORDER_DECLARE — the macros that declare and define buffers so you can record events. no cap, this one's cute.

---

🌸 NAME 🌸

RECORDER, RECORDER_DEFINE, RECORDER_DECLARE — declare and define buffers to record events 🫶

---

✨ SYNOPSIS ✨

#include <recorder/recorder.h>

#define RECORDER(recname, recsize, rechelp) ...
#define RECORDER_DEFINE(recname, recsize, rechelp) ...
#define RECORDER_DECLARE(recname) ...

---

💅 DESCRIPTION 💅

so the RECORDER() macro defines a buffer named recname that stores up to recsize events, for the record(3) function to use. the rechelp string is self-documentation — it describes the events that live in the buffer. and the way that self-documentation gets shown?? by activating the help trace, obviously. see recorder_set_trace(3). 💖

the RECORDER_DECLARE() macro declares an event recorder, and it's lowkey perfect for header files.

the RECORDER_DEFINE() macro is literally just an alias for RECORDER(). the intention — the vibe, if you will — is that you'd use RECORDER() for event recorders that are local to a file, or a RECORDER_DECLARE() (in the header file) paired with a RECORDER_DEFINE() (in a non-header file) for event recorders shared across multiple translation units. iconic setup, fr fr. 🌈

these macros should be used at file scope, i.e. where a function definition or a global variable is allowed. no nesting them in random places, bestie, it's giving boundaries.

each recorder is associated with a trace value, which is an integer value you can read using RECORDER_TRACE(3). see recorder_trace_set(3). ⭐

---

🎀 EXAMPLES 🎀

okay so this first program records its input arguments, and crashes if you pass crash as the first command-line argument. chaotic but educational:

#include <recorder/recorder.h>
#include <string.h>

RECORDER(program_args, 32, "Program command-line arguments");
int main(int argc, char **argv)
{
    int a;
    recorder_dump_on_common_signals(0, 0);
    for (a = 0; a < argc; a++)
        record(program_args, "Argument %d is %+s", a, argv[a]);

    if (argc >= 2 && strcmp(argv[1], "crash") == 0)
    {
        char *ptr = NULL;
        strcpy(ptr, argv[1]);
    }
}

when a crash occurs, previously recorded events are printed out on the console. so like, the receipts are right there. 💀

---

and this next one is an instrumented version of the classical recursive Fibonacci computation 🧚 it uses several recorders for different types of events, and activates warnings and errors in a way you can configure by setting an environment variable. main character energy:

#include <recorder/recorder.h>
#include <string.h>
#include <stdio.h>
#include <stdlib.h>

RECORDER(fib_main,    32, "Loops in fib function");
RECORDER(fib_loops,   32, "Loops in fib function");
RECORDER(fib_warning, 32, "Warnings in fib function");
RECORDER(fib_error,   32, "Errors in fib function");

int fib(int n)
{
    if (n <= 1) {
        if (n < 0)
            record(fib_error, "fib is undefined for negative value %d", n);
        return n;
    }
    record(fib_loops, "Computing fib(%d)", n);
    int result = fib(n-1) + fib(n-2);
    record(fib_loops, "Computed fib(%d) = %d", n, result);
    return result;
}

int main(int argc, char **argv)
{
    int a;
    recorder_dump_on_common_signals(0, 0);
    recorder_trace_set(".*_warning=35 .*_error");
    recorder_trace_set(getenv("FIB_TRACES"));
    for (a = 1; a < argc; a++) {
        int n = atoi(argv[a]);
        if (n >= RECORDER_TRACE(fib_warning))
            record(fib_warning, "Computing for %d may take a while", n);
        printf("fib(%d) = %d0, n, fib(n));
        if (n >= RECORDER_TRACE(fib_warning))
            record(fib_warning, "Computation for %d finally completed", n);
    }
}

this program will produce an output similar to the following:

% fib 1 2 3 4 10 20 30 35 10 40 -1
fib(1) = 1
fib(2) = 1
fib(3) = 2
fib(4) = 3
fib(10) = 55
fib(20) = 6765
fib(30) = 832040
[2714667 0.177725] fib_warning: Computing for 35 may take a while
fib(35) = 9227465
[32575370 1.859156] fib_warning: Computation for 35 finally completed
fib(10) = 55
[32575547 1.859171] fib_warning: Computing for 40 may take a while
fib(40) = 102334155
[363735828 20.527882] fib_warning: Computation for 40 finally completed
[363735829 20.527887] fib_error: fib is undefined for negative value -1
fib(-1) = -1

the first column in trace outputs is the number of events that were recorded. THe second column is the time in seconds since the program started. (yes, both columns are essential, don't skip them 🙈)

---

the same program can also be run with additional tracing or warnings, for example:

% FIB_TRACES="recorder_location fib_loops fib_warning=3" /tmp/fib 3 4
/tmp/fib.c:33:[82 0.000496] fib_warning: Computing for 3 may take a while
/tmp/fib.c:18:[83 0.000561] fib_loops: Computing fib(3)
/tmp/fib.c:18:[84 0.000570] fib_loops: Computing fib(2)
/tmp/fib.c:20:[85 0.000575] fib_loops: Computed fib(2) = 1
/tmp/fib.c:20:[86 0.000581] fib_loops: Computed fib(3) = 2
fib(3) = 2
/tmp/fib.c:36:[87 0.000590] fib_warning: Computation for 3 finally completed
/tmp/fib.c:33:[88 0.000596] fib_warning: Computing for 4 may take a while
/tmp/fib.c:18:[89 0.000601] fib_loops: Computing fib(4)
/tmp/fib.c:18:[90 0.000607] fib_loops: Computing fib(3)
/tmp/fib.c:18:[91 0.000612] fib_loops: Computing fib(2)
/tmp/fib.c:20:[92 0.000619] fib_loops: Computed fib(2) = 1
/tmp/fib.c:20:[93 0.000625] fib_loops: Computed fib(3) = 2
/tmp/fib.c:18:[94 0.000664] fib_loops: Computing fib(2)
/tmp/fib.c:20:[95 0.000707] fib_loops: Computed fib(2) = 1
/tmp/fib.c:20:[96 0.000724] fib_loops: Computed fib(4) = 3
fib(4) = 3
/tmp/fib.c:36:[97 0.000741] fib_warning: Computation for 4 finally completed

---

💀 BUGS 💀

incorrect use of the macros generally results in nonsensical compiler diagnostics. like, the compiler will yell at you but the yelling will make no sense. we love that for us. 😭

bugs should be reported using https://github.com/c3d/recorder/issues.

---

🔥 SEE ALSO 🔥

• record(3), record_fast(3)
• recorder_trace_set(3), RECORDER_TRACE(3)
• recorder_dump(3), recorder_dump_for(3)
• recorder_configure_output(3), recorder_configure_show(3)
• recorder_configure_format(3), recorder_configure_type(3)

additional documentation and tutorials can be found at https://github.com/c3d/recorder. go read 'em, bestie, they're a whole vibe 📚

---

👑 AUTHOR 👑

written by Christophe de Dinechin 💜

---

and that's a wrap!! this page is version 1.0, dated 2019-03-09, straight from the Recorder Library itself. slay, you now know your recorders. periodt. 🎀✨🦋 mwah, go record some events 💖🌸