Archivist.hpp

Go to the documentation of this file.

#pragma once
 
#include "JournalEntry.hpp"
 
#include <format>
 
namespace MayaFlux::Journal {
 
template <typename... Args>
inline std::string format_runtime(std::string_view fmt_str, Args&&... args)
{
    return std::vformat(fmt_str, std::make_format_args(args...));
}
 
class Sink;
 
/**
 * @class Archivist
 * @brief Singleton class responsible for managing log entries.
 *
 * The Archivist class provides methods to log messages with various severity levels,
 * components, and contexts. It supports both standard and real-time logging.
 */
class MAYAFLUX_API Archivist {
 
public:
    /**
     * @brief Get the singleton instance of the Archivist.
     * @return Reference to the Archivist instance.
     */
    static Archivist& instance();
 
    /**
     * @brief Shutdown the logging system.
     * This should be called once at the end of the application.
     */
    static void shutdown();
 
    /**
     * @brief Log a message with the specified severity, component, and context.
     *
     * This method captures the source location automatically.
     *
     * @param severity The severity level of the log message.
     * @param component The component generating the log message.
     * @param context The execution context of the log message.
     * @param message The log message content.
     * @param location The source location (file, line, function) of the log call.
     */
    void scribe(Severity severity, Component component, Context context,
        std::string_view message,
        std::source_location location = std::source_location::current());
 
    /**
     * @brief Log a message from a real-time context with the specified severity, component, and context.
     * This method is optimized for real-time contexts and captures the source location automatically.
     * @param severity The severity level of the log message.
     * @param component The component generating the log message.
     * @param context The execution context of the log message.
     * @param message The log message content.
     * @param location The source location (file, line, function) of the log call.
     */
    void scribe_rt(Severity severity, Component component, Context context,
        std::string_view message,
        std::source_location location = std::source_location::current());
 
    /**
     * @brief Log a simple message without source location information.
     * This method is intended for use in contexts where source location is not available or needed.
     * It is not effected by severity filters, so use sparingly.
     *
     * @param component The component generating the log message.
     * @param context The execution context of the log message.
     * @param message The log message content.
     */
    void scribe_simple(Component component, Context context,
        std::string_view message);
 
    /**
     * @brief Add a log sink for output
     * @param sink Unique pointer to a LogSink implementation
     */
    void add_sink(std::unique_ptr<Sink> sink);
 
    /**
     * @brief Remove all sinks
     */
    void clear_sinks();
 
    /**
     * @brief Synchronously drain all pending ring buffer entries to sinks.
     *
     * Blocks until the ring buffer is empty. Called automatically by error(),
     * error_rethrow(), and fatal() before propagating. Available for any
     * non-RT caller that needs a guaranteed visibility point.
     */
    void flush();
 
    /**
     * @brief Set the minimum severity level for logging.
     * Messages with a severity lower than this level will be ignored.
     * @param min_sev The minimum severity level to log.
     */
    void set_min_severity(Severity min_sev);
 
    /**
     * @brief Enable or disable logging for a specific component.
     * @param comp The component to enable or disable.
     * @param enabled True to enable logging for the component, false to disable.
     */
    void set_component_filter(Component comp, bool enabled);
 
    /**
     * @brief Restrict logging to these components; an empty list includes all.
     * Disabled component filters still apply.
     */
    void set_component_includes(const std::vector<Component>& components);
 
    /**
     * @brief Enable or disable logging for a specific context.
     * @param ctx The context to enable or disable.
     * @param enabled True to enable logging for the context, false to disable.
     */
    void set_context_filter(Context ctx, bool enabled);
 
    /**
     * @brief Restrict logging to these contexts; an empty list includes all.
     * Disabled context filters still apply.
     */
    void set_context_includes(const std::vector<Context>& contexts);
 
    Archivist(const Archivist&) = delete;
    Archivist& operator=(const Archivist&) = delete;
    Archivist(Archivist&&) = delete;
    Archivist& operator=(Archivist&&) = delete;
 
private:
    Archivist();
    ~Archivist();
 
    class Impl;
    std::unique_ptr<Impl> m_impl;
};
 
/**
 * @brief Log a message with the specified severity, component, and context.
 *
 * Captures the source location automatically.
 *
 * @param severity   The severity level of the log message.
 * @param component  The component generating the log message.
 * @param context    The execution context of the log message.
 * @param location   Source location (file, line, function) of the log call.
 * @param message    The log message content.
 */
inline void scribe(Severity severity, Component component, Context context,
    std::source_location location, std::string_view message)
{
    Archivist::instance().scribe(severity, component, context, message, location);
}
 
/**
 * @brief printf-style overload of scribe().
 *
 * @copydoc scribe(Severity,Component,Context,std::string_view,std::source_location)
 *
 * @param msg_or_fmt  The format string.
 * @param args        The format arguments.
 */
template <typename... Args>
void scribe(Severity severity, Component component, Context context,
    std::source_location location, const char* msg_or_fmt, Args&&... args)
{
    if constexpr (sizeof...(Args) == 0) {
        Archivist::instance().scribe(severity, component, context,
            std::string_view(msg_or_fmt), location);
    } else {
        auto msg = format_runtime(msg_or_fmt, std::forward<Args>(args)...);
        Archivist::instance().scribe(severity, component, context, msg, location);
    }
}
 
/**
 * @brief Log a message in a real-time context with automatic source location.
 *
 * Optimized for real-time usage and captures the source location automatically.
 *
 * @param severity   The severity level of the log message.
 * @param component  The component generating the log message.
 * @param context    The execution context of the log message.
 * @param location   Source location (file, line, function) of the log call.
 * @param message    The log message content.
 */
inline void scribe_rt(Severity severity, Component component, Context context,
    std::source_location location, std::string_view message)
{
    Archivist::instance().scribe_rt(severity, component, context, message, location);
}
 
/**
 * @brief printf-style overload of scribe_rt().
 *
 * @copydoc scribe_rt(Severity,Component,Context,std::string_view,std::source_location)
 *
 * @param msg_or_fmt  The format string.
 * @param args        The format arguments.
 */
template <typename... Args>
void scribe_rt(Severity severity, Component component, Context context,
    std::source_location location,
    const char* msg_or_fmt, Args&&... args)
{
    if constexpr (sizeof...(Args) == 0) {
        Archivist::instance().scribe_rt(severity, component, context,
            std::string_view(msg_or_fmt), location);
    } else {
        auto msg = format_runtime(msg_or_fmt, std::forward<Args>(args)...);
        Archivist::instance().scribe_rt(severity, component, context, msg, location);
    }
}
 
/**
 * @brief Log a simple message without source-location.
 *
 * Intended for contexts where source location is unavailable or unnecessary.
 * It is not effected by severity filters, so use sparingly.
 *
 * @param component  The component generating the log message.
 * @param context    The execution context of the log message.
 * @param message    The log message content.
 */
inline void log(Component component, Context context,
    std::string_view message)
{
    Archivist::instance().scribe_simple(component, context, message);
}
 
/**
 * @brief printf-style overload of log().
 *
 * @copydoc log(Component,Context,std::string_view)
 *
 * @param msg_or_fmt  The format string.
 * @param args        The format arguments.
 */
template <typename... Args>
void log(Component component, Context context,
    const char* msg_or_fmt, Args&&... args)
{
    if constexpr (sizeof...(Args) == 0) {
        Archivist::instance().scribe_simple(component, context,
            std::string_view(msg_or_fmt));
    } else {
        auto msg = format_runtime(msg_or_fmt, std::forward<Args>(args)...);
        Archivist::instance().scribe_simple(component, context, msg);
    }
}
 
/**
 * @brief Print formatted output directly to stdout with MayaFlux prefix.
 *
 * Intended for immediate, unfiltered output without journal infrastructure.
 * No component/context tagging, no severity filtering, no source location.
 * Output includes [MayaFlux] prefix to identify framework origin.
 *
 * @param message The message or format string.
 */
inline void format_print(std::string_view message)
{
    std::cout << "[MayaFlux] " << message << '\n';
}
 
/**
 * @brief Printf-style overload of format_print().
 *
 * @copydoc format_print(std::string_view)
 *
 * @param msg_or_fmt  The format string.
 * @param args        The format arguments.
 */
template <typename... Args>
inline void format_print(std::format_string<std::remove_cvref_t<Args>...> fmt_str, Args&&... args)
{
    std::cout << "[MayaFlux] " << format(fmt_str, std::forward<Args>(args)...) << '\n';
}
 
/**
 * @brief Printf-style overload for runtime format strings.
 *
 * @copydoc format_print(std::string_view)
 *
 * @param fmt_str  The runtime format string.
 * @param args     The format arguments.
 */
template <typename... Args>
inline void format_print(const char* fmt_str, Args&&... args)
{
    std::cout << "[MayaFlux] " << format_runtime(fmt_str, std::forward<Args>(args)...) << '\n';
}
 
/**
 * @brief Log a fatal message and abort the program.
 *
 * @param component  The component generating the log message.
 * @param context    The execution context of the log message.
 * @param location   Source location (file, line, function) of the log call.
 * @param message    The fatal message content.
 */
[[noreturn]] inline void fatal(Component component, Context context,
    std::source_location location, std::string_view message)
{
    Archivist::instance().scribe(Severity::FATAL, component, context, message, location);
    Archivist::instance().flush();
    std::abort();
}
 
/**
 * @brief fmt-style overload of fatal().
 *
 * @copydoc fatal(Component,Context,std::string_view,std::source_location)
 *
 * @tparam Args      Types of the format arguments.
 * @param fmt_str    The format string.
 * @param args       The format arguments.
 */
template <typename... Args>
[[noreturn]] void fatal(Component component, Context context,
    std::source_location location, std::format_string<Args...> fmt_str, Args&&... args)
{
    auto msg = format(fmt_str, std::forward<Args>(args)...);
    Archivist::instance().scribe(Severity::FATAL, component, context, msg, location);
    Archivist::instance().flush();
    std::abort();
}
 
/**
 * @brief Log an error message and optionally throw an exception.
 *
 * @tparam ExceptionType  The exception type to throw when behavior == LogAndThrow.
 * @param context    The execution context of the log message.
 * @param location   Source location (file, line, function) of the log call.
 * @param message    The error message content.
 */
template <typename ExceptionType = std::runtime_error>
[[noreturn]] void error(Component component, Context context,
    std::source_location location,
    std::string_view message)
{
    Archivist::instance().scribe(Severity::ERROR, component, context, message, location);
    Archivist::instance().flush();
    throw ExceptionType(std::string(message));
}
 
/**
 * @brief fmt-style overload of error().
 *
 * @copydoc error(Component,Context,ExceptionBehavior,std::string_view,std::source_location)
 *
 * @tparam ExceptionType  The exception type to throw when behavior == LogAndThrow.
 * @tparam Args           Types of the format arguments.
 * @param fmt_str         The format string.
 * @param args            The format arguments.
 */
template <typename ExceptionType = std::runtime_error, typename... Args>
[[noreturn]] void error(Component component, Context context,
    std::source_location location, const char* fmt_str, Args&&... args)
{
    if constexpr (sizeof...(Args) == 0) {
        Archivist::instance().scribe(Severity::ERROR, component, context,
            std::string_view(fmt_str), location);
        Archivist::instance().flush();
        throw ExceptionType(std::string(fmt_str));
    } else {
        auto msg = format_runtime(fmt_str, std::forward<Args>(args)...);
        Archivist::instance().scribe(Severity::ERROR, component, context, msg, location);
        Archivist::instance().flush();
        throw ExceptionType(msg);
    }
}
 
/**
 * @brief Catch and log an exception, then rethrow it.
 * This function is intended to be called within a catch block.
 * @param Component The component generating the log message.
 * @param Context The execution context of the log message.
 * @param location The source location (file, line, function) of the log call.
 * @param additional_context Optional additional context to prepend to the exception message.
 */
[[noreturn]] inline void error_rethrow(Component component, Context context,
    std::source_location location = std::source_location::current(),
    std::string_view additional_context = "")
{
    auto ep = std::current_exception();
    if (!ep) {
        Archivist::instance().scribe(Severity::ERROR, component, context,
            "error_rethrow called outside of a catch", location);
        Archivist::instance().flush();
        std::terminate();
    }
 
    try {
        std::rethrow_exception(ep);
    } catch (const std::exception& e) {
        std::string msg = std::string(e.what());
        if (!additional_context.empty()) {
            msg = std::string(additional_context) + ": " + msg;
        }
        Archivist::instance().scribe(Severity::ERROR, component, context, msg, location);
        Archivist::instance().flush();
        std::rethrow_exception(ep);
    } catch (...) {
        std::string msg = "Unknown exception";
        if (!additional_context.empty()) {
            msg = std::string(additional_context) + ": " + msg;
        }
        Archivist::instance().scribe(Severity::ERROR, component, context, msg, location);
        Archivist::instance().flush();
        std::rethrow_exception(ep);
    }
}
 
/**
 * @brief fmt-style overload of error_rethrow().
 *
 * @copydoc error_rethrow(Component,Context,std::source_location,std::string_view)
 *
 * @tparam Args      Types of the format arguments.
 * @param fmt_str    The format string.
 * @param args       The format arguments.
 */
template <typename... Args>
[[noreturn]] inline void error_rethrow(Component component, Context context,
    std::source_location location, const char* fmt_str, Args&&... args)
{
    auto msg = format_runtime(fmt_str, std::forward<Args>(args)...);
    error_rethrow(component, context, location, std::string_view(msg));
}
 
} // namespace MayaFlux::Journal
 
// ============================================================================
// CONVENIENCE MACROS (for regular logging only)
// ============================================================================
 
#define MF_TRACE(comp, ctx, ...)                                             \
    MayaFlux::Journal::scribe(MayaFlux::Journal::Severity::TRACE, comp, ctx, \
        std::source_location::current(), __VA_ARGS__)
 
#define MF_DEBUG(comp, ctx, ...)                                             \
    MayaFlux::Journal::scribe(MayaFlux::Journal::Severity::DEBUG, comp, ctx, \
        std::source_location::current(), __VA_ARGS__)
 
#define MF_INFO(comp, ctx, ...)                                             \
    MayaFlux::Journal::scribe(MayaFlux::Journal::Severity::INFO, comp, ctx, \
        std::source_location::current(), __VA_ARGS__)
 
#define MF_WARN(comp, ctx, ...)                                             \
    MayaFlux::Journal::scribe(MayaFlux::Journal::Severity::WARN, comp, ctx, \
        std::source_location::current(), __VA_ARGS__)
 
#define MF_ERROR(comp, ctx, ...)                                             \
    MayaFlux::Journal::scribe(MayaFlux::Journal::Severity::ERROR, comp, ctx, \
        std::source_location::current(), __VA_ARGS__)
 
#define MF_ASSERT(comp, ctx, condition, ...)                       \
    do {                                                           \
        if (!(condition)) [[unlikely]] {                           \
            MayaFlux::Journal::scribe(                             \
                MayaFlux::Journal::Severity::ERROR, comp, ctx,     \
                std::source_location::current(),                   \
                "Assertion failed: " #condition ". " __VA_ARGS__); \
            MayaFlux::Journal::Archivist::instance().shutdown();   \
            std::abort();                                          \
        }                                                          \
    } while (false)
 
// ============================================================================
// CONVENIENCE MACROS for REAL-TIME LOGGING ONLY
// ============================================================================
 
#define MF_RT_TRACE(comp, ctx, ...)                                             \
    MayaFlux::Journal::scribe_rt(MayaFlux::Journal::Severity::TRACE, comp, ctx, \
        std::source_location::current(), __VA_ARGS__)
 
#define MF_RT_WARN(comp, ctx, ...)                                             \
    MayaFlux::Journal::scribe_rt(MayaFlux::Journal::Severity::WARN, comp, ctx, \
        std::source_location::current(), __VA_ARGS__)
 
#define MF_RT_ERROR(comp, ctx, ...)                                             \
    MayaFlux::Journal::scribe_rt(MayaFlux::Journal::Severity::ERROR, comp, ctx, \
        std::source_location::current(), __VA_ARGS__)
 
#define MF_RT_DEBUG(comp, ctx, ...)                                             \
    MayaFlux::Journal::scribe_rt(MayaFlux::Journal::Severity::DEBUG, comp, ctx, \
        std::source_location::current(), __VA_ARGS__)
 
// ============================================================================
// CONVENIENCE MACROS for SIMPLE LOGGING (no source-location)
// ============================================================================
#define MF_LOG(comp, ctx, ...) MayaFlux::Journal::log(comp, ctx, __VA_ARGS__)
 
// ============================================================================
// CONVENIENCE MACROS for QUICK OUTPUT (no journal system)
// ============================================================================
#define MF_PRINT(...) MayaFlux::Journal::format_print(__VA_ARGS__)