logger.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Jarosław Pelczar <jarek@jpelczar.com>
//
// SPDX-License-Identifier: BSD-2-Clause
 
#pragma once
 
#include "../reloco.hpp"
#include "sink.hpp"
#include "sync.hpp"
#include <cstddef>
#include <string_view>
#include <utility>
 
namespace microfmt::log {
 
namespace detail {
 
struct identity_decorator {
  [[nodiscard]] constexpr const log_msg &operator()(const log_msg &msg) const noexcept RELOCO_LIFETIMEBOUND {
    return msg;
  }
};
 
} // namespace detail
 
template <size_t MaxSinks = 4, size_t MsgBufferCapacity = 256, typename Mutex = detail::null_mutex,
          typename Sink = log_sink, typename Decorator = detail::identity_decorator>
// NOLINTNEXTLINE(reloco-pointer-annotation): a logger is an owner of its sinks; the name is documented to be static
class basic_logger {
  // Tiny RAII lock guard so this header doesn't need to pull in <mutex>
  // merely for std::lock_guard; works with any BasicLockable Mutex,
  // including std::mutex if the caller already includes <mutex>.
  struct RELOCO_POINTER lock_guard {
    explicit lock_guard(Mutex &m) noexcept : m_(m) { m_.lock(); }
    ~lock_guard() noexcept { m_.unlock(); }
    lock_guard(const lock_guard &) = delete;
    lock_guard &operator=(const lock_guard &) = delete;
 
    Mutex &m_;
  };
 
public:
  explicit constexpr basic_logger(microfmt::string_view name) noexcept : name_(name) {}
 
  template <typename... Sinks>
    requires(sizeof...(Sinks) <= MaxSinks)
  explicit constexpr basic_logger(microfmt::string_view name, Sinks... sinks) noexcept
      : name_(name), sinks_{sinks...}, sink_count_(sizeof...(Sinks)) {}
 
  bool add_sink(Sink s) noexcept {
    lock_guard guard(mutex_);
    if (sink_count_ >= MaxSinks)
      return false;
    sinks_[sink_count_++] = s;
    return true;
  }
 
  void set_level(level l) noexcept { level_ = l; }
  [[nodiscard]] constexpr level get_level() const noexcept { return level_; }
  [[nodiscard]] constexpr microfmt::string_view name() const & noexcept RELOCO_LIFETIMEBOUND { return name_; }
 
  [[nodiscard]] constexpr microfmt::string_view name() const && = delete;
 
  [[nodiscard]] bool should_log(level l) const noexcept { return l >= level_; }
 
  void log(const log_msg &msg) const noexcept {
    if (!should_log(msg.lvl) || sink_count_ == 0) {
      return;
    }
    dispatch(msg);
  }
 
  // NOLINTBEGIN(reloco-banned-std-type): std::source_location is the portable C++20 interop type
  // (reloco::call_location_ref is freestanding-only)
  template <typename... Args> void log(level lvl, microfmt::string_view fmt_str, const Args &...args) const noexcept {
    log_impl(std::source_location::current(), lvl, fmt_str, args...);
  }
 
  template <typename StrProvider, typename... Args>
  void log(level lvl, compile_string_holder<StrProvider> fmt_str, const Args &...args) const noexcept {
    log_impl(std::source_location::current(), lvl, fmt_str, args...);
  }
  // NOLINTEND(reloco-banned-std-type)
 
  template <typename... Args> void trace(microfmt::string_view fmt, const Args &...args) const noexcept {
    log(level::trace, fmt, args...);
  }
 
  template <typename StrProvider, typename... Args>
  void trace(compile_string_holder<StrProvider> fmt, const Args &...args) const noexcept {
    log(level::trace, fmt, args...);
  }
 
  template <typename... Args> void debug(microfmt::string_view fmt, const Args &...args) const noexcept {
    log(level::debug, fmt, args...);
  }
 
  template <typename StrProvider, typename... Args>
  void debug(compile_string_holder<StrProvider> fmt, const Args &...args) const noexcept {
    log(level::debug, fmt, args...);
  }
 
  template <typename... Args> void info(microfmt::string_view fmt, const Args &...args) const noexcept {
    log(level::info, fmt, args...);
  }
 
  template <typename StrProvider, typename... Args>
  void info(compile_string_holder<StrProvider> fmt, const Args &...args) const noexcept {
    log(level::info, fmt, args...);
  }
 
  template <typename... Args> void warn(microfmt::string_view fmt, const Args &...args) const noexcept {
    log(level::warn, fmt, args...);
  }
 
  template <typename StrProvider, typename... Args>
  void warn(compile_string_holder<StrProvider> fmt, const Args &...args) const noexcept {
    log(level::warn, fmt, args...);
  }
 
  template <typename... Args> void error(microfmt::string_view fmt, const Args &...args) const noexcept {
    log(level::err, fmt, args...);
  }
 
  template <typename StrProvider, typename... Args>
  void error(compile_string_holder<StrProvider> fmt, const Args &...args) const noexcept {
    log(level::err, fmt, args...);
  }
 
  template <typename... Args> void critical(microfmt::string_view fmt, const Args &...args) const noexcept {
    log(level::critical, fmt, args...);
  }
 
  template <typename StrProvider, typename... Args>
  void critical(compile_string_holder<StrProvider> fmt, const Args &...args) const noexcept {
    log(level::critical, fmt, args...);
  }
 
  void flush() const noexcept {
    lock_guard guard(mutex_);
    for (size_t i = 0; i < sink_count_; ++i) {
      sinks_[i].flush();
    }
  }
 
  // NOLINTBEGIN(reloco-banned-std-type): std::source_location is the portable C++20 interop type
  // (reloco::call_location_ref is freestanding-only)
  template <typename... Args>
  void log_loc(std::source_location loc, level lvl, microfmt::string_view fmt_str, const Args &...args) const noexcept {
    log_impl(loc, lvl, fmt_str, args...);
  }
 
  template <typename StrProvider, typename... Args>
  void log_loc(std::source_location loc, level lvl, compile_string_holder<StrProvider> fmt_str,
               const Args &...args) const noexcept {
    log_impl(loc, lvl, fmt_str, args...);
  }
 
private:
  template <typename Format, typename... Args>
  void log_impl(std::source_location loc, level lvl, Format fmt_str, const Args &...args) const noexcept {
    if (!should_log(lvl) || sink_count_ == 0) {
      return;
    }
 
    // Format payload into internal line buffer
    buffer_sink<MsgBufferCapacity> buf;
    auto sink_stream = buf.as_sink();
    format_to(sink_stream, fmt_str, args...);
 
    log_msg msg{.logger_name = name_, .lvl = lvl, .time = microfmt::instant::now(), .payload = buf.view(), .loc = loc};
 
    dispatch(msg);
  }
  // NOLINTEND(reloco-banned-std-type)
 
protected:
  [[nodiscard]] Decorator &decorator() & noexcept RELOCO_LIFETIMEBOUND { return decorator_; }
  [[nodiscard]] const Decorator &decorator() const & noexcept RELOCO_LIFETIMEBOUND { return decorator_; }
 
  [[nodiscard]] const Decorator &decorator() const && = delete;
 
  template <typename Msg> void dispatch(const Msg &msg) const noexcept {
    decltype(auto) decorated = decorator_(msg);
    lock_guard guard(mutex_);
    for (size_t i = 0; i < sink_count_; ++i) {
      sinks_[i].log(decorated);
    }
  }
 
private:
  microfmt::string_view name_{};
  level level_{level::info};
  // NOLINTNEXTLINE(reloco-mutable-member): logging is logically const; sinks hold their own synchronisation
  mutable microfmt::array<Sink, MaxSinks> sinks_{};
  size_t sink_count_{0};
  mutable Mutex mutex_{};
  Decorator decorator_{};
};
 
using logger = basic_logger<4, 256>;
 
// The process-default logger API is a nullable `logger *` by contract (nullptr = unset); callers null-check it.
RELOCO_BEGIN_UNSAFE_CODE
namespace detail {
 
inline logger *&configured_default_logger() noexcept {
  static logger *instance = nullptr;
  return instance;
}
 
#if defined(MICROFMT_ENABLE_DEFAULT_LOGGER) && !defined(MICROFMT_DEFAULT_LOG_SINK_BACKEND_CUSTOM)
inline stdout_color_sink<256> &default_console_sink() noexcept {
  static stdout_color_sink<256> sink_instance;
  return sink_instance;
}
 
inline logger &built_in_default_logger() noexcept {
  static logger instance("app", default_console_sink().as_sink());
  return instance;
}
#endif
 
} // namespace detail
 
} // namespace microfmt::log
 
#if defined(MICROFMT_ENABLE_DEFAULT_LOGGER) && defined(MICROFMT_DEFAULT_LOG_SINK_BACKEND_CUSTOM)
// MICROFMT_DEFAULT_LOG_SINK_BACKEND_CUSTOM opts out of the stdout backend
// above entirely, in favor of a platform-appropriate replacement (an OS's
// native logging facility, an RTOS/bare-metal console, ...) supplying the
// same `microfmt::log::detail::built_in_default_logger() noexcept ->
// logger &` entry point via a fixed include path, exactly like reloco's
// `detail/porting/mutex.hpp` does for `RELOCO_MUTEX_BACKEND_CUSTOM` (see
// `reloco/mutex.hpp`). Included unconditionally at this exact point --
// outside every namespace (the enclosing `namespace microfmt::log` is
// closed just above, and reopened just below), exactly like reloco's own
// fixed-path includes -- so nothing about where else this header is
// included from matters, and the included file is free to open/close
// `namespace microfmt::log`/`detail` itself, completely self-contained
// (never nested inside an already-open same-named namespace, which would
// otherwise silently declare a spurious `microfmt::log::microfmt::log`).
// Supplying the whole function (not merely a sink helper) gives a port
// full control over the resulting `logger` too -- its name, sink
// count/capacity, locking policy -- exactly as it would have if it wrote
// `built_in_default_logger()` itself. This file does not ship in this
// repository (only `detail/porting/default_log_sink.template.hpp`, an
// unused documentation-only scaffold, does), so you supply it yourself,
// most conveniently through the `JPLCZ_MICROFMT_PORTING_HEADERS` CMake
// variable (see `CMakeLists.txt`), which copies it into that exact path
// and bakes `MICROFMT_DEFAULT_LOG_SINK_BACKEND_CUSTOM` into a generated
// `detail/porting/microfmt_generated_config.hpp` that `microfmt_config.hpp` picks
// up automatically for every consumer of the plain `include/` tree, not
// merely a consumer linking the `jplcz_microfmt` CMake target -- or by
// placing it there manually and defining the macro yourself if not using
// CMake. See `detail/porting/README.md` and `docs/porting.md`.
#include "../detail/porting/default_log_sink.hpp"
#endif
 
namespace microfmt::log {
 
[[nodiscard]] inline logger *default_logger() noexcept {
  logger *configured = detail::configured_default_logger();
  if (configured != nullptr) {
    return configured;
  }
 
#if defined(MICROFMT_ENABLE_DEFAULT_LOGGER)
  return &detail::built_in_default_logger();
#else
  return nullptr;
#endif
}
 
inline void set_default_logger(logger *instance) noexcept { detail::configured_default_logger() = instance; }
 
template <typename... Args> inline void trace(microfmt::string_view fmt, const Args &...args) noexcept {
  if (logger *instance = default_logger(); instance != nullptr) {
    instance->trace(fmt, args...);
  }
}
 
template <typename StrProvider, typename... Args>
inline void trace(compile_string_holder<StrProvider> fmt, const Args &...args) noexcept {
  if (logger *instance = default_logger(); instance != nullptr) {
    instance->trace(fmt, args...);
  }
}
 
template <typename... Args> inline void debug(microfmt::string_view fmt, const Args &...args) noexcept {
  if (logger *instance = default_logger(); instance != nullptr) {
    instance->debug(fmt, args...);
  }
}
 
template <typename StrProvider, typename... Args>
inline void debug(compile_string_holder<StrProvider> fmt, const Args &...args) noexcept {
  if (logger *instance = default_logger(); instance != nullptr) {
    instance->debug(fmt, args...);
  }
}
 
template <typename... Args> inline void info(microfmt::string_view fmt, const Args &...args) noexcept {
  if (logger *instance = default_logger(); instance != nullptr) {
    instance->info(fmt, args...);
  }
}
 
template <typename StrProvider, typename... Args>
inline void info(compile_string_holder<StrProvider> fmt, const Args &...args) noexcept {
  if (logger *instance = default_logger(); instance != nullptr) {
    instance->info(fmt, args...);
  }
}
 
template <typename... Args> inline void warn(microfmt::string_view fmt, const Args &...args) noexcept {
  if (logger *instance = default_logger(); instance != nullptr) {
    instance->warn(fmt, args...);
  }
}
 
template <typename StrProvider, typename... Args>
inline void warn(compile_string_holder<StrProvider> fmt, const Args &...args) noexcept {
  if (logger *instance = default_logger(); instance != nullptr) {
    instance->warn(fmt, args...);
  }
}
 
template <typename... Args> inline void error(microfmt::string_view fmt, const Args &...args) noexcept {
  if (logger *instance = default_logger(); instance != nullptr) {
    instance->error(fmt, args...);
  }
}
 
template <typename StrProvider, typename... Args>
inline void error(compile_string_holder<StrProvider> fmt, const Args &...args) noexcept {
  if (logger *instance = default_logger(); instance != nullptr) {
    instance->error(fmt, args...);
  }
}
 
template <typename... Args> inline void critical(microfmt::string_view fmt, const Args &...args) noexcept {
  if (logger *instance = default_logger(); instance != nullptr) {
    instance->critical(fmt, args...);
  }
}
 
template <typename StrProvider, typename... Args>
inline void critical(compile_string_holder<StrProvider> fmt, const Args &...args) noexcept {
  if (logger *instance = default_logger(); instance != nullptr) {
    instance->critical(fmt, args...);
  }
}
 
} // namespace microfmt::log
RELOCO_END_UNSAFE_CODE