Add cross-DSO logger instance sharing and flush functionality; bump version to v1.0.8

Author: kzhdev

CHANGELOG

@@ -1,3 +1,11 @@
+# v1.0.8 - 04-02-2026
+- Add cross-DSO logger instance sharing via `Logger::set_instance()` and `Logger::clear_instance_override()`
+  - Enables plugin/shared-library architectures where dynamically-loaded modules should route `LOG_*` calls to the host application's logger
+  - `instance()` now uses an `std::atomic<Logger*>` initialized to the library-local singleton, swappable at runtime
+  - Thread-safe: atomic acquire-release ordering ensures full visibility of the target logger's initialization
+- Add `Logger::flush()`: blocks until all queued log entries are written, then returns with the logger still running
+  - Use before `FreeLibrary`/`dlclose` to drain entries whose format-string pointers live in the plugin's code segment
+
 # v1.0.7 - 03-30-2026
 - Add to_log_level function
 

CMakeLists.txt

@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.20)
 
 project(slick-logger
-    VERSION 1.0.7
+    VERSION 1.0.8
     LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 20)

README.md

@@ -365,6 +365,56 @@ int main() {
 }
 ```
 
+### Sharing the Logger Across Shared Libraries (Plugin / Strategy Pattern)
+
+Because slick-logger is header-only, each binary (EXE or `.dll`/`.so`) that includes `logger.hpp` gets its own `Logger` instance. This means `LOG_*` calls inside a dynamically-loaded plugin will not appear in the host application's log file by default.
+
+Use `Logger::set_instance()` to redirect a plugin's `LOG_*` calls to the host's logger:
+
+**Host application** — pass its logger to the plugin after loading:
+
+```cpp
+// host/main.cpp
+#include <slick/logger.hpp>
+
+// Platform-specific shared library loading omitted for brevity (LoadLibrary on Windows, dlopen on Linux)
+using StrategyInitFn = void(*)(slick::logger::Logger&);
+
+void load_strategy(void* handle) {
+    auto* init_fn = reinterpret_cast<StrategyInitFn>(get_symbol(handle, "strategy_init"));
+    if (init_fn) {
+        // Redirect the plugin's LOG_* macros to this process's logger
+        init_fn(slick::logger::Logger::instance());
+    }
+}
+```
+
+**Plugin / strategy shared library** — expose a C-linkage init function:
+
+```cpp
+// strategy/strategy.cpp
+#include <slick/logger.hpp>
+
+extern "C" void strategy_init(slick::logger::Logger& framework_logger) {
+    // All LOG_* calls in this shared library now route to the host's logger
+    slick::logger::Logger::set_instance(&framework_logger);
+    LOG_INFO("Strategy loaded — logger connected to framework");
+}
+
+extern "C" void strategy_shutdown() {
+    // Optional: restore this library's own local logger on unload
+    slick::logger::Logger::clear_instance_override();
+}
+```
+
+> **Why `extern "C"`?** C linkage prevents name-mangling differences between compilers, ensuring `get_symbol`/`GetProcAddress`/`dlsym` can reliably locate the function.
+
+> **Thread-safety:** `set_instance()` uses `std::atomic` with acquire-release ordering. Call it once during plugin initialization, before any logging threads in the plugin start.
+
+> **Unload ordering — important:** `LOG_*` with string literals stores a raw pointer to the format string, which lives in the plugin's code segment. The host must call `Logger::instance().flush()` **before** calling `FreeLibrary`/`dlclose`. `flush()` blocks until the writer thread has consumed all queued entries, then returns with the logger still running so host logging can continue normally. Using `shutdown()` instead would stop the logger entirely.
+
+> **Multiple plugins:** Each shared library (`.dll`/`.so`) holds its own copy of `override_instance_`. All plugins can independently call `set_instance()` with the same host logger — the host logger's lock-free queue is designed for concurrent producers.
+
 ## Sink Types
 
 ### ConsoleSink

include/slick/logger.hpp

@@ -55,8 +55,8 @@
 
 #define SLICK_LOGGER_VERSION_MAJOR 1
 #define SLICK_LOGGER_VERSION_MINOR 0
-#define SLICK_LOGGER_VERSION_PATCH 7
-#define SLICK_LOGGER_VERSION "1.0.7"
+#define SLICK_LOGGER_VERSION_PATCH 8
+#define SLICK_LOGGER_VERSION "1.0.8"
 
 #ifndef SLICK_LOGGER_MAX_ARGS
 #define SLICK_LOGGER_MAX_ARGS 20
@@ -620,12 +620,43 @@ class Logger {
      */
     void shutdown(bool clear_sinks = true);
 
+    /**
+     * @brief Block until all log entries queued before this call have been
+     * written to all sinks. The logger keeps running — unlike shutdown(),
+     * logging can continue normally after flush() returns.
+     *
+     * Primary use case: call flush() before unloading a shared library whose
+     * string literals are referenced by queued log entries. Because LOG_* with
+     * string literals stores a raw pointer into the caller's code segment,
+     * unloading the library while entries are still queued would leave dangling
+     * pointers that the writer thread would later dereference.
+     *
+     * Does nothing if the logger has not been initialized.
+     */
+    void flush();
+
     /**
      * @brief Reset the logger to uninitialized state
      * Note: This is primarily for testing purposes. Use with caution.
      */
     void reset();
 
+    /**
+     * @brief Redirect Logger::instance() to an external Logger.
+     *
+     * Because slick-logger is header-only, every shared library (.dll/.so) and
+     * the host executable each compile in their own copy of Logger::instance().
+     * Call this from a shared library's init function to make all LOG_* macros
+     * in that library route to the host's logger instead of the library-local one.
+     * Pass nullptr to restore the library-local singleton.
+     *
+     * Thread-safety: uses atomic store/load with acquire-release ordering, so
+     * all initialization of the target logger is visible before any LOG_* call
+     * after set_instance() returns.
+     */
+    static void set_instance(Logger* logger) noexcept;
+    static void clear_instance_override() noexcept;
+
 private:
     Logger() = default;
     ~Logger();
@@ -658,6 +689,14 @@ class Logger {
     uint64_t read_index_{0};
     std::atomic<LogLevel> log_level_{LogLevel::L_TRACE};
     std::unordered_map<std::string_view, int> sinkname_index_map_;
+
+    // The logger instance local to this shared library / executable.
+    // override_instance_ points here by default.
+    static Logger instance_;
+    // Points to the active Logger for this shared library / executable.
+    // Defaults to &instance_. Call set_instance() to redirect to an external
+    // logger (e.g. the host application's logger when loaded as a plugin).
+    static std::atomic<Logger*> override_instance_;
 };
 
 
@@ -1253,8 +1292,18 @@ inline std::string DailyFileSink::get_date_string() const {
 }
 
 inline Logger& Logger::instance() {
-    static Logger instance;
-    return instance;
+    return *override_instance_.load(std::memory_order_acquire);
+}
+
+inline Logger Logger::instance_;
+inline std::atomic<Logger*> Logger::override_instance_{&Logger::instance_};
+
+inline void Logger::set_instance(Logger* logger) noexcept {
+    override_instance_.store(logger, std::memory_order_release);
+}
+
+inline void Logger::clear_instance_override() noexcept {
+    override_instance_.store(&instance_, std::memory_order_release);
 }
 
 inline void Logger::init(const std::filesystem::path& log_file, size_t log_queue_size, size_t string_buffer_size) {
@@ -1680,6 +1729,19 @@ inline Logger::~Logger() {
     shutdown();
 }
 
+inline void Logger::flush() {
+    if (!running_.load(std::memory_order_relaxed) || !log_queue_) {
+        return;
+    }
+    // Snapshot the write cursor: any entry reserved before this point has
+    // already been assigned an index below drain_target.
+    const uint64_t drain_target = log_queue_->initial_reading_index();
+    // Wait until the writer thread's read cursor reaches drain_target.
+    while (running_.load(std::memory_order_relaxed) && read_index_ < drain_target) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+}
+
 inline void Logger::reset() {
     shutdown();
     // Reset all state for fresh initialization

src/logger.hpp

@@ -618,12 +618,43 @@ class Logger {
      */
     void shutdown(bool clear_sinks = true);
 
+    /**
+     * @brief Block until all log entries queued before this call have been
+     * written to all sinks. The logger keeps running — unlike shutdown(),
+     * logging can continue normally after flush() returns.
+     *
+     * Primary use case: call flush() before unloading a shared library whose
+     * string literals are referenced by queued log entries. Because LOG_* with
+     * string literals stores a raw pointer into the caller's code segment,
+     * unloading the library while entries are still queued would leave dangling
+     * pointers that the writer thread would later dereference.
+     *
+     * Does nothing if the logger has not been initialized.
+     */
+    void flush();
+
     /**
      * @brief Reset the logger to uninitialized state
      * Note: This is primarily for testing purposes. Use with caution.
      */
     void reset();
 
+    /**
+     * @brief Redirect Logger::instance() to an external Logger.
+     *
+     * Because slick-logger is header-only, every shared library (.dll/.so) and
+     * the host executable each compile in their own copy of Logger::instance().
+     * Call this from a shared library's init function to make all LOG_* macros
+     * in that library route to the host's logger instead of the library-local one.
+     * Pass nullptr to restore the library-local singleton.
+     *
+     * Thread-safety: uses atomic store/load with acquire-release ordering, so
+     * all initialization of the target logger is visible before any LOG_* call
+     * after set_instance() returns.
+     */
+    static void set_instance(Logger* logger) noexcept;
+    static void clear_instance_override() noexcept;
+
 private:
     Logger() = default;
     ~Logger();
@@ -656,6 +687,14 @@ class Logger {
     uint64_t read_index_{0};
     std::atomic<LogLevel> log_level_{LogLevel::L_TRACE};
     std::unordered_map<std::string_view, int> sinkname_index_map_;
+
+    // The logger instance local to this shared library / executable.
+    // override_instance_ points here by default.
+    static Logger instance_;
+    // Points to the active Logger for this shared library / executable.
+    // Defaults to &instance_. Call set_instance() to redirect to an external
+    // logger (e.g. the host application's logger when loaded as a plugin).
+    static std::atomic<Logger*> override_instance_;
 };
 
 
@@ -1251,8 +1290,18 @@ inline std::string DailyFileSink::get_date_string() const {
 }
 
 inline Logger& Logger::instance() {
-    static Logger instance;
-    return instance;
+    return *override_instance_.load(std::memory_order_acquire);
+}
+
+inline Logger Logger::instance_;
+inline std::atomic<Logger*> Logger::override_instance_{&Logger::instance_};
+
+inline void Logger::set_instance(Logger* logger) noexcept {
+    override_instance_.store(logger, std::memory_order_release);
+}
+
+inline void Logger::clear_instance_override() noexcept {
+    override_instance_.store(&instance_, std::memory_order_release);
 }
 
 inline void Logger::init(const std::filesystem::path& log_file, size_t log_queue_size, size_t string_buffer_size) {
@@ -1678,6 +1727,19 @@ inline Logger::~Logger() {
     shutdown();
 }
 
+inline void Logger::flush() {
+    if (!running_.load(std::memory_order_relaxed) || !log_queue_) {
+        return;
+    }
+    // Snapshot the write cursor: any entry reserved before this point has
+    // already been assigned an index below drain_target.
+    const uint64_t drain_target = log_queue_->initial_reading_index();
+    // Wait until the writer thread's read cursor reaches drain_target.
+    while (running_.load(std::memory_order_relaxed) && read_index_ < drain_target) {
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
+}
+
 inline void Logger::reset() {
     shutdown();
     // Reset all state for fresh initialization

tests/CMakeLists.txt

@@ -30,7 +30,28 @@ if(BUILD_SLICK_LOGGER_TESTING)
     target_include_directories(slick_logger_timestamp_tests PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)
     target_link_libraries(slick_logger_timestamp_tests slick::logger GTest::gtest_main)
     add_test(NAME slick_logger_timestamp_tests COMMAND slick_logger_timestamp_tests)
-    
+
+    # --- Shared-library integration test ---
+    # Build a minimal plugin as a real shared library (.dll/.so), then load it
+    # at runtime to verify LOG_* calls inside the plugin are routed to the host
+    # logger via Logger::set_instance().
+    add_library(slick_logger_test_plugin SHARED plugin/plugin.cpp)
+    target_link_libraries(slick_logger_test_plugin PRIVATE slick::logger)
+    # Hide all symbols by default on non-Windows so only PLUGIN_EXPORT ones are visible.
+    set_target_properties(slick_logger_test_plugin PROPERTIES
+        CXX_VISIBILITY_PRESET hidden
+        VISIBILITY_INLINES_HIDDEN ON
+    )
+
+    # Resolve the plugin path at configure time so the test executable knows
+    # where to find the .dll/.so without relying on PATH/LD_LIBRARY_PATH.
+    add_executable(slick_logger_shared_lib_tests test_shared_library.cpp)
+    target_link_libraries(slick_logger_shared_lib_tests PRIVATE slick::logger GTest::gtest_main)
+    target_compile_definitions(slick_logger_shared_lib_tests PRIVATE
+        PLUGIN_LIB_PATH="$<TARGET_FILE:slick_logger_test_plugin>"
+    )
+    add_test(NAME slick_logger_shared_lib_tests COMMAND slick_logger_shared_lib_tests)
+
 else()
     message(STATUS "Testing disabled - skipping slick-logger tests")
 endif()

tests/plugin/plugin.cpp

@@ -0,0 +1,51 @@
+#include <slick/logger.hpp>
+
+// Exported symbols use C linkage to avoid name-mangling differences across
+// compilers and platforms (required for GetProcAddress / dlsym to work).
+
+extern "C" {
+
+#if defined(_WIN32)
+#  define PLUGIN_EXPORT __declspec(dllexport)
+#else
+#  define PLUGIN_EXPORT __attribute__((visibility("default")))
+#endif
+
+/**
+ * Called by the host after loading this shared library.
+ * Redirects this library's Logger::instance() to the host's logger so that
+ * all LOG_* calls from this library appear in the host's log file.
+ *
+ * IMPORTANT — unload ordering:
+ * LOG_* with string literals stores a raw pointer to the format string, which
+ * lives in this library's code segment. The host must call
+ * Logger::instance().flush() BEFORE calling FreeLibrary/dlclose to ensure the
+ * writer thread has consumed all queued entries. Unlike shutdown(), flush()
+ * leaves the logger running so the host can continue logging after the call.
+ */
+PLUGIN_EXPORT void plugin_init(slick::logger::Logger* host_logger) {
+    slick::logger::Logger::set_instance(host_logger);
+    LOG_INFO("plugin_init: logger connected to host");
+}
+
+/**
+ * Exercise several log levels so the test can verify each one is routed
+ * to the host logger.
+ */
+PLUGIN_EXPORT void plugin_log_messages() {
+    LOG_DEBUG("plugin debug message");
+    LOG_INFO("plugin info message");
+    LOG_WARN("plugin warn message");
+    LOG_ERROR("plugin error message");
+}
+
+/**
+ * Called by the host before unloading this shared library.
+ * Restores this library's own local logger so that any logging after
+ * unload does not dereference the (potentially destroyed) host logger.
+ */
+PLUGIN_EXPORT void plugin_shutdown() {
+    slick::logger::Logger::clear_instance_override();
+}
+
+} // extern "C"