logger.h

Why a plugin needs one more than an application does

An application that misbehaves can be run from a terminal. A plugin cannot: it is loaded into somebody else's process, on somebody else's machine, and the only channel back is the user. "It crashes sometimes when I load a preset" is the entire bug report you get, and without a log it is also the entire evidence.

So this exists to be READ BY SOMEBODY ELSE: appended to a file the user can find, capped so it cannot fill a disk, and readable back so a plugin can put a "copy diagnostics" button in its editor.

The audio thread, which is the whole design problem

The interesting failures are in process(). That is exactly where a logger must not be used: opening a file, formatting a string and taking a mutex are each enough to blow a buffer deadline, and the dropout would be caused by the diagnostic rather than by the bug.

The conventional logger has no answer to that -- a virtual call to a subclass that writes a file, and calling it from an audio callback is simply a mistake. Which means the one place you most want a trace is the one place you cannot have one.

So there are two doors. write() is for any ordinary thread and does the obvious thing. writeFromAudioThread() copies at most kMaxLine bytes into a fixed ring and returns: no allocation, no lock, no syscall, nothing that can block. drain() moves whatever accumulated to the file, and is called from the editor's clock alongside everything else that crosses that boundary.

A message that arrives while the ring is full is DROPPED and counted. Dropped with a number attached is a fact; dropped silently is a lie, and blocking until there is room is the dropout this whole arrangement exists to avoid.