log.h File Reference

Logging infrastructure and macros. More...

#include <cstdarg>
#include <cstdio>

Go to the source code of this file.

Classes
class	fz::Logger

Macros
#define	FZ_LOG(level, ...)
#define	FZ_PRINT(...)   ::fz::Logger::print(__VA_ARGS__)

Enumerations
enum class	fz::LogLevel : int {   TRACE = 0 , DEBUG = 1 , INFO = 2 , WARN = 3 ,   SILENT = 255 }

Detailed Description

Logging infrastructure and macros.

FZGPUModules logging infrastructure

Design goals:

1. Zero overhead when disabled — FZ_LOG calls below the compile-time threshold expand to ((void)0); arguments are never evaluated.
2. Zero overhead in release builds by default — FZ_LOG_MIN_LEVEL defaults to INFO (2), so TRACE and DEBUG calls compile out completely.
3. Flexible output — a single callback receives all log messages; the caller decides where they go (stderr, file, test buffer, etc.).
4. Explicit diagnostic helpers (printDAG, printBufferLifetimes) always produce output via FZ_PRINT, which uses the callback if set or stdout.

Compile-time control (set via CMake -DFZ_LOG_MIN_LEVEL=N or \#define before including this header):

FZ_LOG_MIN_LEVEL=0 (TRACE) — all log calls compiled in FZ_LOG_MIN_LEVEL=1 (DEBUG) — TRACE compiled out FZ_LOG_MIN_LEVEL=2 (INFO) — TRACE+DEBUG compiled out ← default FZ_LOG_MIN_LEVEL=3 (WARN) — only WARN compiled in FZ_LOG_MIN_LEVEL=255 (SILENT) — all log calls compiled out

Runtime control: fz::Logger::setCallback(cb) — set output sink (nullptr = silent) fz::Logger::setMinLevel(level) — runtime filter (≥ compile-time floor) fz::Logger::enableStderr(level) — convenience: log ≥ level to stderr

Usage: FZ_LOG(INFO, "finalize: %zu stages", n); FZ_LOG(DEBUG, "buffer %s allocated %.1f KB", tag, kb); FZ_LOG(TRACE, "execute: input=%zu output=%zu", in, out); FZ_LOG(WARN, "outlier overflow: %u > capacity", count);

FZ_PRINT(" node [%d] %s", id, name); // always outputs (diagnostic)

Macro Definition Documentation

FZ_LOG

#define FZ_LOG	(		level,
			...
	)

Value:

    do {                                                                        \
        if constexpr (static_cast<int>(::fz::LogLevel::level) >=               \
                      static_cast<int>(FZ_LOG_MIN_LEVEL)) {                     \
            ::fz::Logger::log(::fz::LogLevel::level, __VA_ARGS__);              \
        }                                                                       \
    } while (0)

FZ_LOG(LEVEL, fmt, ...) — primary logging macro.

If the level's integer value is below FZ_LOG_MIN_LEVEL the entire call — including all arguments — is compiled out via if constexpr. No function call, no string evaluation, no branch at runtime.

Example: FZ_LOG(DEBUG, "allocated %s: %.1f KB", tag.c_str(), sz / 1024.0); FZ_LOG(WARN, "outlier overflow: %u > %u capacity", actual, max);

FZ_PRINT

#define FZ_PRINT

(

...

)

::fz::Logger::print(__VA_ARGS__)

FZ_PRINT(fmt, ...) — always-output diagnostic macro.

Not filtered by FZ_LOG_MIN_LEVEL. Use for explicitly-called diagnostic functions (printDAG, printBufferLifetimes) where the caller has opted in to output and silence would be confusing.

Routes through the Logger callback if one is set; falls back to stdout.

Enumeration Type Documentation

LogLevel

enum class fz::LogLevel : int

strong

Enumerator
TRACE	Per-stage execute(), per-chunk details — very verbose.
DEBUG	Pipeline construction, buffer allocation, data stats.
INFO	High-level milestones: finalize, compress, decompress.
WARN	Unexpected but recoverable: outlier overflow, fallbacks.
SILENT	Compile-time sentinel — do not pass to log()