RECORDER(3)

🎀 RECORDER(3) — the Recorder Library, bestie 🎀

okay so this page is straight out of the Recorder Library manual, section 3, and it's all about the three little macros that let you declare and define the buffers that record your events. it's giving "instrumentation but make it cute". let's go 💅

---

✨ 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 💖

the RECORDER() macro defines a buffer named recname that stores up to recsize events, and that buffer is for the record(3) function to write into. the rechelp string is the self-documentation — it describes the events that get stored in the buffer. and the way you actually see that self-documentation? you activate the help trace, see recorder_set_trace(3). 👑

the RECORDER_DECLARE() macro declares an event recorder, and it's literally built to live in header files. 📄✨

the RECORDER_DEFINE() macro is just an alias for RECORDER() — no cap. the intention behind having both names is:

• use RECORDER() for event recorders that are local to a file, and
• pair a RECORDER_DECLARE() (in the header file) with a RECORDER_DEFINE() (in a non-header file) for event recorders that get shared across multiple translation units.

these macros should be used at file scope, bestie — like, the exact same place where a function definition or a global variable is allowed to be. 🫶

every single recorder is associated with a trace value, which is an integer value you can read with RECORDER_TRACE(3). see recorder_trace_set(3). 🔥

---

🌸 EXAMPLES 🌸

🍓 example the first: recording your args, then dramatically crashing

this program records its input arguments, and crashes if you pass crash as the first command-line argument. iconically unhinged.

#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]);
    }
}

and when a crash occurs, all those previously recorded events get printed out on the console. 💀➡️🖨️

🧚 example the second: instrumented recursive Fibonacci

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

#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 those trace outputs is the number of events that were recorded. the second column is the time in seconds since the program started. 🕰️

🎀 and you can run it with extra tracing too

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 💀

ngl, if you use these macros incorrectly, you generally get nonsensical compiler diagnostics. the compiler will simply start yelling gibberish at you and you will be like "ma'am what". 😭

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. 🌈

---

⭐ AUTHOR ⭐

written by Christophe de Dinechin 💜

---

and that's the whole page, bestie — version 1.0, dated 2019-03-09, from the RECORDER(3) manual. slay, go record some events, periodt. 💖✨🎀🦋