log.h

Go to the documentation of this file.

 
#ifndef NROS_LOG_H
#define NROS_LOG_H
 
#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef enum rcl_log_severity_t {
    RCLC_LOG_SEVERITY_UNSET = 0,
    RCLC_LOG_SEVERITY_TRACE = 5,
    RCLC_LOG_SEVERITY_DEBUG = 10,
    RCLC_LOG_SEVERITY_INFO = 20,
    RCLC_LOG_SEVERITY_WARN = 30,
    RCLC_LOG_SEVERITY_ERROR = 40,
    RCLC_LOG_SEVERITY_FATAL = 50,
    /* NOT a level — a WIDTH PIN (issue 1330). Every ARM EABI compiler defaults
     * to `-fshort-enums` (it is the AAPCS default, not a flag this tree picks),
     * so an enum whose largest value is 50 is packed to ONE byte there. That
     * contradicts both the Rust mirror (`repr(transparent)` over `c_int`) and
     * this enum's own promise above that any `int` a C caller can produce is
     * representable — and it turned the `_Static_assert` below into a hard
     * build error for every cross C/C++ image the day the guard landed.
     * `-fno-short-enums` is not the fix: it would have to reach every consumer
     * in and out of tree, and a TU that forgot would disagree about the width
     * of a type in a shared header, silently. The pin belongs in the header.
     *
     * Trailing underscore: reserved, never emitted, never switched on.
     * `to_facade` is TOTAL, so a caller that somehow passed it resolves to
     * FATAL like any other out-of-range `int` rather than being rejected. */
    RCLC_LOG_SEVERITY_FORCE_INT_WIDTH_ = 0x7fffffff,
} rcl_log_severity_t;
 
/* ── Width guard ──────────────────────────────────────────────────────────────
 * This `enum` is HAND-MIRRORED in Rust (`packages/api/nros-c/src/log.rs`), which
 * is the class `check-ffi-struct-mirrors` polices one layer over. The mirror is
 * `#[repr(transparent)]` over `c_int`; it was `#[repr(u8)]` until phase-417
 * stage 3, so one side passed a byte where the other passed four and the values
 * survived only by how the ABIs in play happen to pass small integers. Nothing
 * asserted the width anywhere in `include/` or `src/`. It does now. */
#if defined(__cplusplus) && __cplusplus >= 201103L
static_assert(sizeof(rcl_log_severity_t) == sizeof(int),
              "rcl_log_severity_t must be int-sized: the Rust mirror is repr(transparent) "
              "over c_int");
static_assert(RCLC_LOG_SEVERITY_INFO == 20, "rcl_log_severity_t must stay on rcutils's numbering");
static_assert(RCLC_LOG_SEVERITY_FATAL == 50, "rcl_log_severity_t must stay on rcutils's numbering");
#elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L
_Static_assert(sizeof(rcl_log_severity_t) == sizeof(int),
               "rcl_log_severity_t must be int-sized: the Rust mirror is repr(transparent) "
               "over c_int");
_Static_assert(RCLC_LOG_SEVERITY_INFO == 20, "rcl_log_severity_t must stay on rcutils's numbering");
_Static_assert(RCLC_LOG_SEVERITY_FATAL == 50,
               "rcl_log_severity_t must stay on rcutils's numbering");
#endif /* static_assert */
 
typedef const void* rclc_logger_t;
 
void rclc_log_emit(rclc_logger_t logger, rcl_log_severity_t severity, const char* message,
                   size_t message_len);
 
void rclc_log_emit_fmt(rclc_logger_t logger, rcl_log_severity_t severity, const char* fmt, ...)
    __attribute__((format(printf, 3, 4)));
 
void rclc_log_emit_at(rclc_logger_t logger, rcl_log_severity_t severity, const char* message,
                      size_t message_len, const char* file, uint32_t line);
 
#define NROS_LOG_FMT_BUFFER_SIZE 256
 
void rclc_log_emit_fmt_at(rclc_logger_t logger, rcl_log_severity_t severity, const char* file,
                          uint32_t line, const char* fmt, ...)
    __attribute__((format(printf, 5, 6)));
 
/* ---- Convenience macros ---- */
/* The macros stage the printf args into a stack buffer inside
 * `rclc_log_emit_fmt_at`, which attaches `__FILE__` / `__LINE__`.
 * Filtering happens on the Rust side: the image's compile-time CEILING
 * (`NROS_LOG_MAX_LEVEL`, issue 1037 — `trace` unless stated) and then the
 * per-logger threshold (`rclc_logger_set_level`), both inside the same check
 * `rclc_logger_is_enabled` answers. The call site still formats; guard it with
 * `rclc_logger_is_enabled` if the arguments are expensive. */
 
#define RCLC_LOG_TRACE(logger, ...)                                                                \
    rclc_log_emit_fmt_at((logger), RCLC_LOG_SEVERITY_TRACE, __FILE__, (uint32_t)__LINE__,          \
                         __VA_ARGS__)
#define RCLC_LOG_DEBUG(logger, ...)                                                                \
    rclc_log_emit_fmt_at((logger), RCLC_LOG_SEVERITY_DEBUG, __FILE__, (uint32_t)__LINE__,          \
                         __VA_ARGS__)
#define RCLC_LOG_INFO(logger, ...)                                                                 \
    rclc_log_emit_fmt_at((logger), RCLC_LOG_SEVERITY_INFO, __FILE__, (uint32_t)__LINE__,           \
                         __VA_ARGS__)
#define RCLC_LOG_WARN(logger, ...)                                                                 \
    rclc_log_emit_fmt_at((logger), RCLC_LOG_SEVERITY_WARN, __FILE__, (uint32_t)__LINE__,           \
                         __VA_ARGS__)
#define RCLC_LOG_ERROR(logger, ...)                                                                \
    rclc_log_emit_fmt_at((logger), RCLC_LOG_SEVERITY_ERROR, __FILE__, (uint32_t)__LINE__,          \
                         __VA_ARGS__)
#define RCLC_LOG_FATAL(logger, ...)                                                                \
    rclc_log_emit_fmt_at((logger), RCLC_LOG_SEVERITY_FATAL, __FILE__, (uint32_t)__LINE__,          \
                         __VA_ARGS__)
 
void rclc_log_init(void);
 
rclc_logger_t rclc_log_default_logger(void);
 
/* -------------------------------------------------------------------------
 * phase-417 W4.d — named loggers, per-logger levels, sinks, throttle.
 *
 * Every entry point below is a thin forwarder onto `nros_log` (RFC-0019: the
 * Rust API is the implementation, C delegates). No level table, no throttle
 * arithmetic and no sink list lives on this side.
 * ------------------------------------------------------------------------- */
 
rclc_logger_t rclc_log_get_logger(const char* name);
 
size_t rclc_logger_get_name(rclc_logger_t logger, char* buf, size_t buf_len);
 
bool rclc_logger_set_level(rclc_logger_t logger, rcl_log_severity_t severity);
 
rclc_logger_t rclc_logger_get_child(rclc_logger_t logger, const char* suffix);
 
rcl_log_severity_t rclc_logger_get_level(rclc_logger_t logger);
 
void rclc_log_set_default_level(rcl_log_severity_t severity);
 
rcl_log_severity_t rclc_log_get_default_level(void);
 
bool rclc_logger_is_enabled(rclc_logger_t logger, rcl_log_severity_t severity);
 
typedef void (*rclc_log_sink_fn)(void* user_data, rcl_log_severity_t severity,
                                 const char* logger_name, size_t logger_name_len,
                                 const char* message, size_t message_len, const char* file,
                                 size_t file_len, uint32_t line, uint64_t timestamp_ns);
 
bool rclc_log_add_sink(rclc_log_sink_fn sink, void* user_data);
 
bool rclc_log_timestamp_available(void);
 
bool rclc_log_throttle_admit(uint64_t* last_ns, uint64_t interval_ms);
 
/* ---- Throttled convenience macros ---- */
/* One `static uint64_t` per call site, which is what makes the window
 * per-SITE and not per-logger — the same shape as `rclcpp`'s
 * `RCLCPP_INFO_THROTTLE`. Statements, not expressions (they declare storage),
 * so they need their own `;` and cannot be used inside a comma expression.
 *
 * Severity is tested BEFORE the window: a record the logger's level already
 * filters must not consume the window, or a raised-then-lowered log level
 * loses its first record for a whole interval. */
 
#define RCLC_LOG_THROTTLE_AT(logger, severity, interval_ms, ...)                                   \
    do {                                                                                           \
        static uint64_t _nros_log_throttle_last = 0;                                               \
        if (rclc_logger_is_enabled((logger), (severity)) &&                                        \
            rclc_log_throttle_admit(&_nros_log_throttle_last, (uint64_t)(interval_ms))) {          \
            rclc_log_emit_fmt_at((logger), (severity), __FILE__, (uint32_t)__LINE__, __VA_ARGS__); \
        }                                                                                          \
    } while (0)
 
#define RCLC_LOG_TRACE_THROTTLE(logger, interval_ms, ...)                                          \
    RCLC_LOG_THROTTLE_AT((logger), RCLC_LOG_SEVERITY_TRACE, (interval_ms), __VA_ARGS__)
#define RCLC_LOG_DEBUG_THROTTLE(logger, interval_ms, ...)                                          \
    RCLC_LOG_THROTTLE_AT((logger), RCLC_LOG_SEVERITY_DEBUG, (interval_ms), __VA_ARGS__)
#define RCLC_LOG_INFO_THROTTLE(logger, interval_ms, ...)                                           \
    RCLC_LOG_THROTTLE_AT((logger), RCLC_LOG_SEVERITY_INFO, (interval_ms), __VA_ARGS__)
#define RCLC_LOG_WARN_THROTTLE(logger, interval_ms, ...)                                           \
    RCLC_LOG_THROTTLE_AT((logger), RCLC_LOG_SEVERITY_WARN, (interval_ms), __VA_ARGS__)
#define RCLC_LOG_ERROR_THROTTLE(logger, interval_ms, ...)                                          \
    RCLC_LOG_THROTTLE_AT((logger), RCLC_LOG_SEVERITY_ERROR, (interval_ms), __VA_ARGS__)
#define RCLC_LOG_FATAL_THROTTLE(logger, interval_ms, ...)                                          \
    RCLC_LOG_THROTTLE_AT((logger), RCLC_LOG_SEVERITY_FATAL, (interval_ms), __VA_ARGS__)
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* NROS_LOG_H */