log.h

Go to the documentation of this file.

#pragma once
 
#include "fl/system/sketch_macros.h"
#include "fl/stl/static_assert.h"  // FL_STATIC_ASSERT for the printf-form ban
#include "fl/stl/strstream.h"  // IWYU pragma: keep - Required by FL_WARN/FL_ERROR/FL_DBG macros
#include "fl/stl/stdio.h"      // IWYU pragma: keep - fl::print / fl::println for log output
#include "fl/stl/chrono.h"       // IWYU pragma: keep - Required by FL_WARN_EVERY/FL_DBG_EVERY/FL_PRINT_EVERY macros
#include "fl/stl/compiler_control.h"  // IWYU pragma: keep - FL_NO_INLINE for log_emit
 
// =============================================================================
// FL_LOG_*_ENABLED -> FASTLED_LOG_*_ENABLED backward compatibility
// =============================================================================
// Users can now use the shorter FL_LOG_*_ENABLED defines. The old
// FASTLED_LOG_*_ENABLED names still work for backward compatibility.
#if defined(FL_LOG_SPI_ENABLED) && !defined(FASTLED_LOG_SPI_ENABLED)
    #define FASTLED_LOG_SPI_ENABLED
#endif
#if defined(FL_LOG_RMT_ENABLED) && !defined(FASTLED_LOG_RMT_ENABLED)
    #define FASTLED_LOG_RMT_ENABLED
#endif
#if defined(FL_LOG_PARLIO_ENABLED) && !defined(FASTLED_LOG_PARLIO_ENABLED)
    #define FASTLED_LOG_PARLIO_ENABLED
#endif
#if defined(FL_LOG_AUDIO_ENABLED) && !defined(FASTLED_LOG_AUDIO_ENABLED)
    #define FASTLED_LOG_AUDIO_ENABLED
#endif
#if defined(FL_LOG_INTERRUPT_ENABLED) && !defined(FASTLED_LOG_INTERRUPT_ENABLED)
    #define FASTLED_LOG_INTERRUPT_ENABLED
#endif
#if defined(FL_LOG_FLEXIO_ENABLED) && !defined(FASTLED_LOG_FLEXIO_ENABLED)
    #define FASTLED_LOG_FLEXIO_ENABLED
#endif
#if defined(FL_LOG_OBJECTFLED_ENABLED) && !defined(FASTLED_LOG_OBJECTFLED_ENABLED)
    #define FASTLED_LOG_OBJECTFLED_ENABLED
#endif
 
// Conditional include for async logger functions (only when logging features are enabled)
#if defined(FASTLED_LOG_SPI_ENABLED) || defined(FASTLED_LOG_RMT_ENABLED) || defined(FASTLED_LOG_PARLIO_ENABLED) || defined(FASTLED_LOG_AUDIO_ENABLED) || defined(FASTLED_LOG_INTERRUPT_ENABLED)
    #include "fl/log/async_logger.h"  // IWYU pragma: keep - Required by FL_LOG_*_ASYNC_* macros
#include "fl/stl/noexcept.h"
#endif
 
// =============================================================================
// FL_LOG_LEVEL - compile-time log level. Each `FL_WARN(...)` call site
// bakes a `__FILE__ + __LINE__ + message` literal into `.flash.rodata`; on
// ESP32 that pool is ~37-58 KB (FastLED #2773, #2886, #4712).
// =============================================================================
//
// Levels (higher = more output):
//
//   * 0 (off)    -> FL_ERROR/FL_WARN/FL_INFO/FL_PRINT/FL_DBG and
//                   FL_WARN_LIT/FL_LOG_LIT expand to no-ops.
//   * 1 (errors) -> FL_ERROR (real failures) and FL_PRINT (output the sketch
//                   asked for explicitly) fire; FL_WARN/FL_INFO/FL_DBG
//                   compile out. FL_WARN_LIT/FL_LOG_LIT (one literal, no
//                   stream machinery; used by the LPC845 bring-up check)
//                   stay live.
//   * 2 (full)   -> everything above plus FL_WARN/FL_INFO, and FL_DBG under
//                   its own FASTLED_HAS_DBG gate.
//
// FL_ERROR/FL_WARN/FL_INFO/FL_PRINT additionally require
// SKETCH_HAS_LARGE_MEMORY (AVR/ATtiny/LPC845 never run the full pipeline).
//
// Resolution order:
//
//   1. `FASTLED_TESTING`                 -> 2 (host tests need diagnostics)
//   2. `FL_LOG_LEVEL` set by user        -> that value
//   3. `FASTLED_LOG_VERBOSITY` set (legacy knob, kept for back-compat)
//                                        -> 0 stays 0; any value >= 1 maps
//                                           to 2, because
//                                           `-DFASTLED_LOG_VERBOSITY=1` has
//                                           always meant "full logs"
//   4. `NDEBUG` (release builds)         -> 0
//   5. otherwise (e.g. Arduino IDE)      -> 1 (errors only, #4712)
//
// To restore full logs add `-DFL_LOG_LEVEL=2` to the build flags, or
// `#define FL_LOG_LEVEL 2` before `#include <FastLED.h>`. The legacy
// `-DFASTLED_LOG_VERBOSITY=1` still works. Per-channel logging defines
// (`FASTLED_LOG_RMT_ENABLED`, ...) keep their own `#define`s.
#ifdef FASTLED_TESTING
  #undef FL_LOG_LEVEL
  #define FL_LOG_LEVEL 2
#elif !defined(FL_LOG_LEVEL)
  #if defined(FASTLED_LOG_VERBOSITY)
    #if FASTLED_LOG_VERBOSITY >= 1
      #define FL_LOG_LEVEL 2
    #else
      #define FL_LOG_LEVEL 0
    #endif
  #elif defined(NDEBUG)
    #define FL_LOG_LEVEL 0
  #else
    #define FL_LOG_LEVEL 1
  #endif
#endif
 
// Error-level gate: the log pipeline is linked and FL_ERROR / FL_PRINT fire.
// Callers guarding error-only helpers (one-shot flags, names used in
// FL_ERROR messages) use this.
#if SKETCH_HAS_LARGE_MEMORY && (FL_LOG_LEVEL >= 1)
  #define FASTLED_LOG_RUNTIME_ENABLED 1
#else
  #define FASTLED_LOG_RUNTIME_ENABLED 0
#endif
 
// Public resolved gate for FL_WARN / FL_INFO call sites and their supporting
// helpers. Requires the full level (2).
#if SKETCH_HAS_LARGE_MEMORY && (FL_LOG_LEVEL >= 2)
  #define FL_HAS_WARN 1
#else
  #define FL_HAS_WARN 0
#endif
 
// Lite gate for FL_WARN_LIT / FL_LOG_LIT - string-literal-only macros that
// route through fl::println without the sstream / operator<< / log_emit
// chain. These are intentionally usable on Low-memory targets (LPC845,
// AVR, ATtiny) where the full FL_WARN pipeline is too expensive - the
// caller pays for one `fl::println(const char*)` symbol and the literal
// bytes, nothing more. Live at level >= 1. See FastLED #3002.
#if FL_LOG_LEVEL >= 1
  #define FASTLED_LOG_LITE_ENABLED 1
#else
  #define FASTLED_LOG_LITE_ENABLED 0
#endif
 
// =============================================================================
// Forward Declarations
// =============================================================================
 
// Forward declare println to avoid pulling in full fl/stl/cstdio.h machinery
// This prevents ~5KB memory bloat for simple applications
#ifndef FL_PRINTLN_DECLARED
#define FL_PRINTLN_DECLARED
namespace fl {
    void println(const char* str) FL_NO_EXCEPT;
}
#endif
 
// =============================================================================
// Debug Output Helpers
// =============================================================================
 
namespace fl {
// ".build/src/fl/dbg.h" -> "src/fl/dbg.h"
// "blah/blah/blah.h" -> "blah.h"
const char *fastled_file_offset(const char *file) FL_NO_EXCEPT;
} // namespace fl
 
// =============================================================================
// Centralised log emit (#2963 Proposal B, Option 3)
// =============================================================================
//
// `fl::detail::log_emit(kind, file, line, body)` consumes the
// user-supplied sstream (passed by rvalue reference) and **rewrites
// it in place** to hold the full prefixed message:
//
//   "<file>(<line>): <KIND>: <user payload>"
//
// then emits via `fl::println(body.c_str())`.
//
// Lifetime-safe variant of Path C's "Option 1" attempt. The body
// sstream temporary lives in the **caller's** frame - its
// lifetime extends to the end of the FL_WARN/FL_ERROR/FL_INFO
// full expression, exactly as the OLD inline macro's temporary
// did. So `body.c_str()` passed to `println` has the same
// async-handler-safe lifetime as before: whatever the test
// harness or platform println did synchronously continues to
// work, and async deferred-flush handlers still see a live
// pointer until the semicolon.
//
// The legacy macro inlined the entire
//   `<< file << "(" << line << "): KIND: " << X`
// chain at every FL_WARN site (1,372 sites × ~30-50 B of inlined
// prefix-format code). With this helper, the prefix-format chain
// is compiled ONCE into libFastLED - each call site only emits
// the `fl::sstream() << X` ctor + the user's payload chain + a
// single `log_emit` call.
namespace fl { namespace detail {
enum class log_kind : fl::u8 {
    WARN  = 0,
    ERROR = 1,
    INFO  = 2,
};
 
const char* log_kind_name(log_kind kind) FL_NO_EXCEPT FL_NO_INLINE;
void log_emit_prefix(log_kind kind, const char* file, int line) FL_NO_EXCEPT FL_NO_INLINE;
void log_emit_newline() FL_NO_EXCEPT FL_NO_INLINE;
 
// Takes `body` by non-const lvalue reference (not `&&`) because the
// macro's `fl::sstream() << X` expression has type `sstream&` (the
// returned lvalue ref from chained operator<<). The underlying
// temporary's lifetime is the FL_WARN full-expression's, so mutating
// it through this lvalue ref is well-defined and the c_str() handed
// to println outlives the call exactly as the OLD inline macro's
// `(fl::sstream() << ...).c_str()` did.
//
// `FL_NO_INLINE` enforces the centralisation. Without it, at -O2
// with LTO the compiler often inlines `log_emit` at every FL_WARN
// site - defeating the whole point of moving the prefix chain
// out-of-line. The noinline attribute is what makes this proposal
// actually win bytes; bare centralisation alone isn't enough.
void log_emit(log_kind kind, const char* file, int line, fl::sstream& body) FL_NO_EXCEPT FL_NO_INLINE;
void log_emit_literal(log_kind kind, const char* file, int line,
                      const char* body) FL_NO_EXCEPT FL_NO_INLINE;
 
// A one-argument log macro cannot distinguish `"literal"` from
// `"prefix" << value` by argument count. log_seed makes that distinction in
// the expression's type instead: a lone string literal remains a lightweight
// log_literal, while a subsequent << materializes an sstream. This preserves
// legacy stream syntax without charging literal call sites for an sstream.
template <fl::size N>
class log_literal {
public:
    explicit log_literal(const char (&text)[N]) FL_NO_EXCEPT : mText(text) {}
 
    const char* c_str() const FL_NO_EXCEPT { return mText; }
 
    template <typename T>
    fl::sstream operator<<(const T& value) const FL_NO_EXCEPT {
        fl::sstream body;
        body << mText << value;
        return body;
    }
 
private:
    const char* mText;
};
 
class log_seed {
public:
    template <fl::size N>
    log_literal<N> operator<<(const char (&text)[N]) const FL_NO_EXCEPT {
        return log_literal<N>(text);
    }
 
    template <typename T>
    fl::sstream operator<<(const T& value) const FL_NO_EXCEPT {
        fl::sstream body;
        body << value;
        return body;
    }
};
 
template <fl::size N>
inline void log_emit_auto(log_kind kind, const char* file, int line,
                          const log_literal<N>& body) FL_NO_EXCEPT {
    // Treat a one-argument literal as data, not as a printf format string.
    // This preserves legacy FL_WARN("100% loaded") behavior while still
    // avoiding an sstream at the call site.
    log_emit_literal(kind, file, line, body.c_str());
}
 
inline void log_emit_auto(log_kind kind, const char* file, int line,
                          fl::sstream& body) FL_NO_EXCEPT {
    log_emit(kind, file, line, body);
}
 
inline void log_emit_auto(log_kind kind, const char* file, int line,
                          fl::sstream&& body) FL_NO_EXCEPT {
    log_emit(kind, file, line, body);
}
 
template <fl::size N>
inline void print_emit_auto(const log_literal<N>& body) FL_NO_EXCEPT {
    fl::println(body.c_str());
}
 
inline void print_emit_auto(fl::sstream& body) FL_NO_EXCEPT {
    fl::println(body.c_str());
}
 
inline void print_emit_auto(fl::sstream&& body) FL_NO_EXCEPT {
    fl::println(body.c_str());
}
 
template <typename Logger, fl::size N>
inline void async_log_emit_auto(Logger& logger,
                                const log_literal<N>& body) FL_NO_EXCEPT {
    logger.push(body.c_str());
}
 
template <typename Logger>
inline void async_log_emit_auto(Logger& logger,
                                fl::sstream& body) FL_NO_EXCEPT {
    logger.push(body.str());
}
 
template <typename Logger>
inline void async_log_emit_auto(Logger& logger,
                                fl::sstream&& body) FL_NO_EXCEPT {
    logger.push(body.str());
}
 
} } // namespace fl::detail
 
// =============================================================================
// Unified-dispatch helpers for FL_WARN / FL_ERROR / FL_INFO / FL_PRINT (#3272)
// =============================================================================
// `FL_WARN(...)` takes exactly one argument, a literal or a stream chain:
//
//   FL_WARN("plain literal")            // 1 literal -> direct format path
//   FL_WARN("foo " << x << " bar")      // 1 stream expression -> sstream
//   FL_WARN("got %d items", n)          // 2+ args -> compile error (#4709)
//
// Macro-level dispatch (rather than C++ overload resolution) is required
// because the single-arg stream form is a chained `<<` expression - it
// only compiles when the macro injects `fl::sstream()` as the LHS.
// Routing through a function call would force the `<<` chain to evaluate
// standalone, which fails (`const char*` has no `operator<<(float)`).
//
// The dispatch recognizes up to 16 arguments so the banned form gets a clear
// static_assert instead of a preprocessor error. The
// filler list `_FL_M*15, _FL_S` is positioned so the (17 - argc)-th element
// of the merged list lands at the `NAME` slot:
//   1 user arg  -> NAME = _FL_S  (lazy literal/stream dispatch)
//   2..16 args -> NAME = _FL_M  (multi  -> banned printf form)
#define _FL_VA_PICK17( \
    _1, _2, _3, _4, _5, _6, _7, _8, \
    _9, _10, _11, _12, _13, _14, _15, _16, \
    NAME, ...) NAME
 
#define _FL_VA_DISPATCH(_S, _M, ...) \
    _FL_VA_PICK17(__VA_ARGS__, \
        _M, _M, _M, _M, _M, _M, _M, _M, \
        _M, _M, _M, _M, _M, _M, _M, _S)
 
// printf-style log formatting is banned (#4709). `FL_WARN("x=%d", x)` links
// the whole fl::printf engine (format spec parser, width, integer/float
// formatters) into every image that logs; on Teensy 4 that code lives in
// RAM1. Every log macro's multi-argument form therefore fails to compile,
// including the no-op variants used on small platforms, so a sketch fails
// the same way on every board. Use stream form: `FL_WARN("x=" << x)`, and
// `fl::to_hex(v)` in place of `%x`.
#define _FL_LOG_PRINTF_BANNED(...) do { \
    FL_STATIC_ASSERT(sizeof(#__VA_ARGS__) == 0, \
        "FastLED: printf-style log formatting is not allowed; use stream " \
        "form, e.g. FL_WARN(\"x=\" << x). See FastLED#4709."); \
} while(0)
#define _FL_LOG_NOOP_S(X) do { } while(0)
// Compile-time check for no-op log variants: one argument is accepted and
// dropped, more than one is the banned printf form.
#define _FL_LOG_CHECK(...) _FL_VA_DISPATCH(_FL_LOG_NOOP_S, _FL_LOG_PRINTF_BANNED, __VA_ARGS__)(__VA_ARGS__)
 
// =============================================================================
// Error Macros (FL_ERROR)
// =============================================================================
 
// Per-kind dispatch helpers - _FL_*_S = single-arg stream form; _FL_*_M = banned printf form.
#define _FL_ERROR_S(X) ::fl::detail::log_emit_auto( \
    ::fl::detail::log_kind::ERROR, \
    ::fl::fastled_file_offset(__FILE__), int(__LINE__), \
    ::fl::detail::log_seed() << X)
#define _FL_ERROR_M(...) _FL_LOG_PRINTF_BANNED(__VA_ARGS__)
 
#ifndef FASTLED_ERROR
// FASTLED_ERROR: Stream-style (<<) only; printf-style is a compile error (#4709). Dispatch via
// argument-count dispatch - see #3272.
#define FASTLED_ERROR(...) _FL_VA_DISPATCH(_FL_ERROR_S, _FL_ERROR_M, __VA_ARGS__)(__VA_ARGS__)
#define FASTLED_ERROR_IF(COND, ...) do { if (COND) FASTLED_ERROR(__VA_ARGS__); } while(0)
#endif
 
#ifndef FL_ERROR
#if FASTLED_LOG_RUNTIME_ENABLED
// FL_ERROR: one literal or `"foo " << x` stream expression; `"foo %d", x` is a
// compile error (#4709).
#define FL_ERROR(...) _FL_VA_DISPATCH(_FL_ERROR_S, _FL_ERROR_M, __VA_ARGS__)(__VA_ARGS__)
#define FL_ERROR_IF(COND, ...) do { if (COND) FL_ERROR(__VA_ARGS__); } while(0)
#else
// No-op macros - memory-constrained platform or FL_LOG_LEVEL=0.
// Args are dropped entirely (matching pre-#3272 behaviour of FL_*_F). See
// commit notes - earlier draft used `sstream_noop()` type-check but that
// forced evaluation of args declared only under FASTLED_LOG_*_ENABLED.
#define FL_ERROR(...) _FL_LOG_CHECK(__VA_ARGS__)
#define FL_ERROR_IF(COND, ...) _FL_LOG_CHECK(__VA_ARGS__)
#endif
#endif
 
// =============================================================================
// Warning Macros (FL_WARN)
// =============================================================================
 
// Per-kind dispatch helpers - _FL_WARN_S = single-arg stream form; _FL_WARN_M = banned printf form.
#define _FL_WARN_S(X) ::fl::detail::log_emit_auto( \
    ::fl::detail::log_kind::WARN, \
    ::fl::fastled_file_offset(__FILE__), int(__LINE__), \
    ::fl::detail::log_seed() << X)
#define _FL_WARN_M(...) _FL_LOG_PRINTF_BANNED(__VA_ARGS__)
 
#ifndef FASTLED_WARN
// FASTLED_WARN: Stream-style (<<) only; printf-style is a compile error (#4709). Dispatch via
// argument-count dispatch - see #3272.
#define FASTLED_WARN(...) _FL_VA_DISPATCH(_FL_WARN_S, _FL_WARN_M, __VA_ARGS__)(__VA_ARGS__)
#define FASTLED_WARN_IF(COND, ...) do { if (COND) FASTLED_WARN(__VA_ARGS__); } while(0)
#endif
 
#ifndef FL_WARN
#if FL_HAS_WARN
// FL_WARN: one literal or `"foo " << x` stream expression; `"foo %d", x` is a
// compile error (#4709).
#define FL_WARN(...) _FL_VA_DISPATCH(_FL_WARN_S, _FL_WARN_M, __VA_ARGS__)(__VA_ARGS__)
#define FL_WARN_IF(COND, ...) do { if (COND) FL_WARN(__VA_ARGS__); } while(0)
 
// FL_WARN_ONCE: Emits warning only once per unique location (static flag per call site)
// Uses static bool flag initialized to false - first call prints, subsequent calls no-op
#define FL_WARN_ONCE(...) do { \
    static bool _warned = false; \
    if (!_warned) { \
        _warned = true; \
        FL_WARN(__VA_ARGS__); \
    } \
} while(0)
 
// FL_WARN_FMT: Alias for FL_WARN (kept for backwards compatibility)
#define FL_WARN_FMT(...) FL_WARN(__VA_ARGS__)
#define FL_WARN_FMT_IF(COND, ...) FL_WARN_IF(COND, __VA_ARGS__)
 
// FL_WARN_LIT: defined below outside the FL_HAS_WARN block -
// gated on FASTLED_LOG_LITE_ENABLED so it stays available on Low-memory
// targets. See "Lite-variant literal macros" section below.
 
// FL_WARN_EVERY: Rate-limited warning that prints at most once per interval
// Uses static timestamp to track last print time - throttles output in tight loops
#define FL_WARN_EVERY(MILLIS, ...) do { \
    static fl::u32 _last_warn_time = 0; \
    fl::u32 _now = fl::millis(); \
    if (_now - _last_warn_time >= (MILLIS)) { \
        _last_warn_time = _now; \
        FL_WARN(__VA_ARGS__); \
    } \
} while(0)
#else
// No-op macros - memory-constrained platform or FL_LOG_LEVEL < 2.
// Args dropped entirely - see the corresponding FL_ERROR section above for
// the rationale (pre-existing call sites declare some args only under
// FASTLED_LOG_*_ENABLED, so any `if(false)` type-check would force a build
// error).
#define FL_WARN(...) _FL_LOG_CHECK(__VA_ARGS__)
#define FL_WARN_IF(COND, ...) _FL_LOG_CHECK(__VA_ARGS__)
#define FL_WARN_ONCE(...) _FL_LOG_CHECK(__VA_ARGS__)
#define FL_WARN_FMT(...) _FL_LOG_CHECK(__VA_ARGS__)
#define FL_WARN_FMT_IF(COND, ...) _FL_LOG_CHECK(__VA_ARGS__)
#define FL_WARN_EVERY(MILLIS, ...) _FL_LOG_CHECK(__VA_ARGS__)
#endif
#endif
 
// Lite-variant literal macros: gated on FASTLED_LOG_LITE_ENABLED so they
// remain usable on Low-memory targets where the full FL_WARN chain is a
// no-op. Use these at well-known WARN sites where the message is a fixed
// string and the byte budget matters (FastLED #2856 item 3.2, #3002).
#ifndef FL_WARN_LIT
#if FASTLED_LOG_LITE_ENABLED
#define FL_WARN_LIT(LITERAL) fl::println(LITERAL)
#define FL_LOG_LIT(LITERAL)  fl::println(LITERAL)
#else
#define FL_WARN_LIT(LITERAL) do { } while(0)
#define FL_LOG_LIT(LITERAL)  do { } while(0)
#endif
#endif
 
// =============================================================================
// Info Macros (FL_INFO)
// =============================================================================
 
// Per-kind dispatch helpers - _FL_INFO_S = single-arg stream form; _FL_INFO_M = banned printf form.
#define _FL_INFO_S(X) ::fl::detail::log_emit_auto( \
    ::fl::detail::log_kind::INFO, \
    ::fl::fastled_file_offset(__FILE__), int(__LINE__), \
    ::fl::detail::log_seed() << X)
#define _FL_INFO_M(...) _FL_LOG_PRINTF_BANNED(__VA_ARGS__)
 
#ifndef FASTLED_INFO
// FASTLED_INFO: Stream-style (<<) only; printf-style is a compile error (#4709). Dispatch via
// argument-count dispatch - see #3272.
#define FASTLED_INFO(...) _FL_VA_DISPATCH(_FL_INFO_S, _FL_INFO_M, __VA_ARGS__)(__VA_ARGS__)
#define FASTLED_INFO_IF(COND, ...) do { if (COND) FASTLED_INFO(__VA_ARGS__); } while(0)
#endif
 
#ifndef FL_INFO
#if FL_HAS_WARN
// FL_INFO: one literal or stream expression; printf-style is a compile error
// (#4709).
#define FL_INFO(...) _FL_VA_DISPATCH(_FL_INFO_S, _FL_INFO_M, __VA_ARGS__)(__VA_ARGS__)
#define FL_INFO_IF(COND, ...) do { if (COND) FL_INFO(__VA_ARGS__); } while(0)
 
// FL_INFO_ONCE: Emits info only once per unique location (static flag per call site)
// Uses static bool flag initialized to false - first call prints, subsequent calls no-op
#define FL_INFO_ONCE(...) do { \
    static bool _infoed = false; \
    if (!_infoed) { \
        _infoed = true; \
        FL_INFO(__VA_ARGS__); \
    } \
} while(0)
#else
// No-op macros - memory-constrained platform or FL_LOG_LEVEL < 2.
#define FL_INFO(...) _FL_LOG_CHECK(__VA_ARGS__)
#define FL_INFO_IF(COND, ...) _FL_LOG_CHECK(__VA_ARGS__)
#define FL_INFO_ONCE(...) _FL_LOG_CHECK(__VA_ARGS__)
#endif
#endif
 
// =============================================================================
// Debug Macros (FL_DBG)
// =============================================================================
 
#if defined(FL_IS_WASM) || !defined(RELEASE) || defined(FASTLED_TESTING)
#define FASTLED_FORCE_DBG 1
#endif
 
// Reusable no-op macro for disabled debug output - avoids linker symbol pollution
#define FL_DBG_NO_OP(X) do { if (false) { fl::sstream_noop() << X; } } while(0)
 
// Debug printing control:
// - FASTLED_DISABLE_DBG=1: Explicitly disable FL_DBG output (highest priority)
// - FL_LOG_LEVEL < 2: Disable FL_DBG (needs the full log level)
// - FASTLED_FORCE_DBG: Force enable FL_DBG (auto-set for debug builds)
// - SKETCH_HAS_LARGE_MEMORY: Enable FL_DBG when platform has enough memory
//
// Priority: FASTLED_DISABLE_DBG > FL_LOG_LEVEL > FASTLED_FORCE_DBG > SKETCH_HAS_LARGE_MEMORY
#if defined(FASTLED_DISABLE_DBG) && FASTLED_DISABLE_DBG
// Explicit disable takes highest priority - useful for reducing serial spam
#define FASTLED_HAS_DBG 0
#define _FASTLED_DGB(X) FL_DBG_NO_OP(X)
#elif FL_LOG_LEVEL < 2
// FL_DBG needs the full log level (2). See #2773 item 2.3 and #4712.
#define FASTLED_HAS_DBG 0
#define _FASTLED_DGB(X) FL_DBG_NO_OP(X)
#elif !defined(FASTLED_FORCE_DBG) && !SKETCH_HAS_LARGE_MEMORY
// By default, debug printing is disabled to prevent memory bloat in simple applications
#define FASTLED_HAS_DBG 0
#define _FASTLED_DGB(X) FL_DBG_NO_OP(X)
#else
// Explicit debug mode enabled - uses fl::println()
#define FASTLED_HAS_DBG 1
#define _FASTLED_DGB(X) ::fl::detail::log_emit_auto( \
    ::fl::detail::log_kind::INFO, \
    ::fl::fastled_file_offset(__FILE__), int(__LINE__), \
    ::fl::detail::log_seed() << X)
#define _FL_DBG_M(...) _FL_LOG_PRINTF_BANNED(__VA_ARGS__)
#endif
 
#ifndef _FL_DBG_M
#define _FL_DBG_M(...) _FL_LOG_PRINTF_BANNED(__VA_ARGS__)
#endif
#define FASTLED_DBG(...) _FL_VA_DISPATCH(_FASTLED_DGB, _FL_DBG_M, __VA_ARGS__)(__VA_ARGS__)
 
#ifndef FASTLED_DBG_IF
#define FASTLED_DBG_IF(COND, ...) do { if (COND) FASTLED_DBG(__VA_ARGS__); } while(0)
#endif // FASTLED_DBG_IF
 
// Short-form aliases for convenience (following pattern from warn.h)
#ifndef FL_DBG
#define FL_DBG FASTLED_DBG
#define FL_DBG_IF FASTLED_DBG_IF
 
// FL_DBG_EVERY: Rate-limited debug output that prints at most once per interval
// Uses static timestamp to track last print time - throttles output in tight loops
#if FASTLED_HAS_DBG
#define FL_DBG_EVERY(MILLIS, ...) do { \
    static fl::u32 _last_dbg_time = 0; \
    fl::u32 _now = fl::millis(); \
    if (_now - _last_dbg_time >= (MILLIS)) { \
        _last_dbg_time = _now; \
        FL_DBG(__VA_ARGS__); \
    } \
} while(0)
#else
#define FL_DBG_EVERY(MILLIS, ...) _FL_LOG_CHECK(__VA_ARGS__)
#endif
#endif
 
// =============================================================================
// AsyncLogger Class (in fl/log/async_logger.h)
// =============================================================================
// AsyncLogger, LogCategory enum, and accessor functions are now in fl/log/async_logger.h
// This provides template-based lazy instantiation with linker-friendly auto-registration

 
// =============================================================================
// General Logging Macros
// =============================================================================

// Per-form dispatch helpers - _FL_PRINT_S = stream; _FL_PRINT_M = printf.
// Unlike FL_WARN, no "<file>(<line>): WARN:" prefix is prepended.
#define _FL_PRINT_S(X) ::fl::detail::print_emit_auto(::fl::detail::log_seed() << X)
#define _FL_PRINT_M(...) _FL_LOG_PRINTF_BANNED(__VA_ARGS__)
 
#ifndef FL_PRINT
#if FASTLED_LOG_RUNTIME_ENABLED
// FL_PRINT: one literal or stream expression; printf-style is a compile error (#4709).
// No "WARN:" / "file(line):" prefix (unlike FL_WARN). See #3272.
#define FL_PRINT(...) _FL_VA_DISPATCH(_FL_PRINT_S, _FL_PRINT_M, __VA_ARGS__)(__VA_ARGS__)
 
// FL_PRINT_EVERY: Rate-limited print that outputs at most once per interval
// Uses static timestamp to track last print time - throttles output in tight loops
#define FL_PRINT_EVERY(MILLIS, ...) do { \
    static fl::u32 _last_print_time = 0; \
    fl::u32 _now = fl::millis(); \
    if (_now - _last_print_time >= (MILLIS)) { \
        _last_print_time = _now; \
        FL_PRINT(__VA_ARGS__); \
    } \
} while(0)
#else
// No-op macro for memory-constrained platforms
#define FL_PRINT(...) _FL_LOG_CHECK(__VA_ARGS__)
#define FL_PRINT_EVERY(MILLIS, ...) _FL_LOG_CHECK(__VA_ARGS__)
#endif
#endif
 
// =============================================================================
// Hardware Interface Logging Categories
// =============================================================================


#ifdef FASTLED_LOG_SPI_ENABLED
    #define FL_LOG_SPI(...) FL_WARN(__VA_ARGS__)
#else
    #define FL_LOG_SPI(...) _FL_LOG_CHECK(__VA_ARGS__)
#endif

#if defined(FASTLED_LOG_RMT_ENABLED) && FL_HAS_WARN
    #define FL_HAS_RMT_LOG 1
    #define FL_LOG_RMT(...) FL_WARN(__VA_ARGS__)
#else
    #define FL_HAS_RMT_LOG 0
    #define FL_LOG_RMT(...) _FL_LOG_CHECK(__VA_ARGS__)
#endif

#ifdef FASTLED_LOG_PARLIO_ENABLED
    #define FL_LOG_PARLIO(...) FL_WARN(__VA_ARGS__)
#else
    #define FL_LOG_PARLIO(...) _FL_LOG_CHECK(__VA_ARGS__)
#endif

#ifdef FASTLED_LOG_AUDIO_ENABLED
    #define FL_LOG_AUDIO(...) FL_WARN(__VA_ARGS__)
#else
    #define FL_LOG_AUDIO(...) _FL_LOG_CHECK(__VA_ARGS__)
#endif

#ifdef FASTLED_LOG_INTERRUPT_ENABLED
    #define FL_LOG_INTERRUPT(...) FL_WARN(__VA_ARGS__)
#else
    #define FL_LOG_INTERRUPT(...) _FL_LOG_CHECK(__VA_ARGS__)
#endif

#ifdef FASTLED_LOG_FLEXIO_ENABLED
    #define FL_LOG_FLEXIO(...) FL_WARN(__VA_ARGS__)
#else
    #define FL_LOG_FLEXIO(...) _FL_LOG_CHECK(__VA_ARGS__)
#endif

#ifdef FASTLED_LOG_OBJECTFLED_ENABLED
    #define FL_LOG_OBJECTFLED(...) FL_WARN(__VA_ARGS__)
#else
    #define FL_LOG_OBJECTFLED(...) _FL_LOG_CHECK(__VA_ARGS__)
#endif

 
// =============================================================================
// Async Logging Infrastructure (ISR-Safe)
// =============================================================================


// Per-form dispatch helpers - _S = stream form, _M = banned printf form. Pushes the
// composed message to the caller-provided AsyncLogger instance.
#define _FL_LOG_ASYNC_S(logger, X) do { \
    ::fl::detail::async_log_emit_auto((logger), ::fl::detail::log_seed() << X); \
} while(0)
#define _FL_LOG_ASYNC_M(logger, ...) _FL_LOG_PRINTF_BANNED(__VA_ARGS__)
 
// Unified async-log dispatch (#3272). Single-arg payload -> stream form (legacy
// compatible); two-or-more args -> compile error (#4709).
#define FL_LOG_ASYNC(logger, ...) _FL_VA_DISPATCH(_FL_LOG_ASYNC_S, _FL_LOG_ASYNC_M, __VA_ARGS__)(logger, __VA_ARGS__)

#define FL_LOG_ASYNC_ISR(logger, msg) \
    do { \
        (logger).push(msg); \
    } while(0)
 
// -----------------------------------------------------------------------------
// SPI Async Logging
// -----------------------------------------------------------------------------
 
#ifdef FASTLED_LOG_SPI_ENABLED
    #define FL_LOG_SPI_ASYNC_ISR(X) FL_LOG_ASYNC_ISR(fl::get_spi_async_logger_isr(), X)
    #define FL_LOG_SPI_ASYNC_MAIN(...) FL_LOG_ASYNC(fl::get_spi_async_logger_main(), __VA_ARGS__)
    #define FL_LOG_SPI_ASYNC_FLUSH() do { \
        fl::get_spi_async_logger_isr().flush(); \
        fl::get_spi_async_logger_main().flush(); \
    } while(0)
#else
    #define FL_LOG_SPI_ASYNC_ISR(X) FL_DBG_NO_OP(X)
    #define FL_LOG_SPI_ASYNC_MAIN(...) do { } while(0)
    #define FL_LOG_SPI_ASYNC_FLUSH() do {} while(0)
#endif
 
// -----------------------------------------------------------------------------
// RMT Async Logging
// -----------------------------------------------------------------------------
 
#ifdef FASTLED_LOG_RMT_ENABLED
    #define FL_LOG_RMT_ASYNC_ISR(X) FL_LOG_ASYNC_ISR(fl::get_rmt_async_logger_isr(), X)
    #define FL_LOG_RMT_ASYNC_MAIN(...) FL_LOG_ASYNC(fl::get_rmt_async_logger_main(), __VA_ARGS__)
    #define FL_LOG_RMT_ASYNC_FLUSH() do { \
        fl::get_rmt_async_logger_isr().flush(); \
        fl::get_rmt_async_logger_main().flush(); \
    } while(0)
#else
    #define FL_LOG_RMT_ASYNC_ISR(X) FL_DBG_NO_OP(X)
    #define FL_LOG_RMT_ASYNC_MAIN(...) do { } while(0)
    #define FL_LOG_RMT_ASYNC_FLUSH() do {} while(0)
#endif
 
// -----------------------------------------------------------------------------
// PARLIO Async Logging
// -----------------------------------------------------------------------------
 
#ifdef FASTLED_LOG_PARLIO_ENABLED
    #define FL_LOG_PARLIO_ASYNC_ISR(X) FL_LOG_ASYNC_ISR(fl::get_parlio_async_logger_isr(), X)
    #define FL_LOG_PARLIO_ASYNC_MAIN(...) FL_LOG_ASYNC(fl::get_parlio_async_logger_main(), __VA_ARGS__)
    #define FL_LOG_PARLIO_ASYNC_FLUSH() do { \
        fl::get_parlio_async_logger_isr().flush(); \
        fl::get_parlio_async_logger_main().flush(); \
    } while(0)
#else
    #define FL_LOG_PARLIO_ASYNC_ISR(X) FL_DBG_NO_OP(X)
    #define FL_LOG_PARLIO_ASYNC_MAIN(...) do { } while(0)
    #define FL_LOG_PARLIO_ASYNC_FLUSH() do {} while(0)
#endif
 
// -----------------------------------------------------------------------------
// AUDIO Async Logging
// -----------------------------------------------------------------------------
 
#ifdef FASTLED_LOG_AUDIO_ENABLED
    #define FL_LOG_AUDIO_ASYNC_ISR(X) FL_LOG_ASYNC_ISR(fl::get_audio_async_logger_isr(), X)
    #define FL_LOG_AUDIO_ASYNC_MAIN(...) FL_LOG_ASYNC(fl::get_audio_async_logger_main(), __VA_ARGS__)
    #define FL_LOG_AUDIO_ASYNC_FLUSH() do { \
        fl::get_audio_async_logger_isr().flush(); \
        fl::get_audio_async_logger_main().flush(); \
    } while(0)
#else
    #define FL_LOG_AUDIO_ASYNC_ISR(X) FL_DBG_NO_OP(X)
    #define FL_LOG_AUDIO_ASYNC_MAIN(...) do { } while(0)
    #define FL_LOG_AUDIO_ASYNC_FLUSH() do {} while(0)
#endif
 
// -----------------------------------------------------------------------------
// INTERRUPT Async Logging
// -----------------------------------------------------------------------------
 
#ifdef FASTLED_LOG_INTERRUPT_ENABLED
    #define FL_LOG_INTERRUPT_ASYNC_ISR(X) FL_LOG_ASYNC_ISR(fl::get_interrupt_async_logger_isr(), X)
    #define FL_LOG_INTERRUPT_ASYNC_MAIN(...) FL_LOG_ASYNC(fl::get_interrupt_async_logger_main(), __VA_ARGS__)
    #define FL_LOG_INTERRUPT_ASYNC_FLUSH() do { \
        fl::get_interrupt_async_logger_isr().flush(); \
        fl::get_interrupt_async_logger_main().flush(); \
    } while(0)
#else
    #define FL_LOG_INTERRUPT_ASYNC_ISR(X) FL_DBG_NO_OP(X)
    #define FL_LOG_INTERRUPT_ASYNC_MAIN(...) do { } while(0)
    #define FL_LOG_INTERRUPT_ASYNC_FLUSH() do {} while(0)
#endif
 
// -----------------------------------------------------------------------------
// FLEXIO Async Logging
// -----------------------------------------------------------------------------
 
#ifdef FASTLED_LOG_FLEXIO_ENABLED
    #define FL_LOG_FLEXIO_ASYNC_ISR(X) FL_LOG_ASYNC_ISR(fl::get_flexio_async_logger_isr(), X)
    #define FL_LOG_FLEXIO_ASYNC_MAIN(...) FL_LOG_ASYNC(fl::get_flexio_async_logger_main(), __VA_ARGS__)
    #define FL_LOG_FLEXIO_ASYNC_FLUSH() do { \
        fl::get_flexio_async_logger_isr().flush(); \
        fl::get_flexio_async_logger_main().flush(); \
    } while(0)
#else
    #define FL_LOG_FLEXIO_ASYNC_ISR(X) FL_DBG_NO_OP(X)
    #define FL_LOG_FLEXIO_ASYNC_MAIN(...) do { } while(0)
    #define FL_LOG_FLEXIO_ASYNC_FLUSH() do {} while(0)
#endif
 
// -----------------------------------------------------------------------------
// OBJECTFLED Async Logging
// -----------------------------------------------------------------------------
 
#ifdef FASTLED_LOG_OBJECTFLED_ENABLED
    #define FL_LOG_OBJECTFLED_ASYNC_ISR(X) FL_LOG_ASYNC_ISR(fl::get_objectfled_async_logger_isr(), X)
    #define FL_LOG_OBJECTFLED_ASYNC_MAIN(...) FL_LOG_ASYNC(fl::get_objectfled_async_logger_main(), __VA_ARGS__)
    #define FL_LOG_OBJECTFLED_ASYNC_FLUSH() do { \
        fl::get_objectfled_async_logger_isr().flush(); \
        fl::get_objectfled_async_logger_main().flush(); \
    } while(0)
#else
    #define FL_LOG_OBJECTFLED_ASYNC_ISR(X) FL_DBG_NO_OP(X)
    #define FL_LOG_OBJECTFLED_ASYNC_MAIN(...) do { } while(0)
    #define FL_LOG_OBJECTFLED_ASYNC_FLUSH() do {} while(0)
#endif
 
// -----------------------------------------------------------------------------
// Background Flush Service
// -----------------------------------------------------------------------------

namespace fl {
    void async_log_service() FL_NO_EXCEPT;

    void configureAsyncLogService(u32 interval_ms = 16, fl::size messages_per_tick = 5) FL_NO_EXCEPT;
}