reckless

When choosing reckless, be aware of its intentional design tradeoffs compared to other logging libraries:

• Dangling Pointers: reckless allows you to pass raw pointers to the background thread. This improves performance because the log string is not prepared at the call site, but it can lead to crashes if the pointer becomes invalid before it is written to disk.
  • Best Practice: Never use raw pointers to dynamically allocated or stack-allocated memory. Pointers to global objects and string literals are generally safe. For dynamically allocated strings, use std::string.
• Floating-Point Precision: reckless may trade some precision in floating-point output for increased performance.
• Latency vs. Throughput: reckless aims for stable, low latency. It uses a configurable buffer (defaulting to 64 KiB) to avoid sudden hangs. If the buffer fills up, the caller may experience latency spikes as the logger performs synchronous writes.
• Crash Safety: reckless is designed to minimize the risk of losing log messages during a crash by flushing whenever possible.

The basic_log class is the foundation for all loggers in reckless. It manages the asynchronous infrastructure, including input/output buffers and the background worker thread. It does not provide public functions for direct logging; instead, it provides a protected write<Formatter>(Args&&... args) method intended to be used by derived classes (like policy_log or severity_log).

Key responsibilities of basic_log include:

• Managing buffer capacities (input_buffer_capacity and output_buffer_capacity).
• Handling error policies for temporary and permanent writer failures.
• Providing mechanisms for panic flushing during crashes.
• Monitoring buffer health via high-watermarks and full-count metrics.

// #include <reckless/basic_log.hpp>

class basic_log {
public:
    basic_log();
    basic_log(writer* pwriter);
    basic_log(writer* pwriter, std::size_t input_buffer_capacity, std::size_t output_buffer_capacity);
    virtual ~basic_log();

    void open(writer* pwriter);
    void open(writer* pwriter, std::size_t input_buffer_capacity, std::size_t output_buffer_capacity);
    virtual void close(std::error_code& ec) noexcept;
    virtual void flush(std::error_code& ec);
    // ... other members

protected:
    template <class Formatter, typename... Args>
    void write(Args&&... args);
};

Reckless is an asynchronous logging library designed for extremely low latency and high throughput.

The Mechanism: When a logging call is made, the library only pushes the arguments onto a shared, lockless queue. The actual string formatting and I/O operations are performed asynchronously by a separate background thread. This design provides several benefits:

• Minimal Call-site Cost: In non-contended cases, the cost is roughly equivalent to a standard function call.
• No Kernel Transitions: By avoiding kernel calls at the call site, it prevents CPU cache pollution and allows non-logging code to run faster.
• Lockless Synchronization: No locks are taken between threads unless the queue fills up.
• Asynchronous Formatting & I/O: Text formatting and I/O wait times are moved off the main execution path.
• Batching: During log bursts, multiple items can be batched into a single I/O operation to improve throughput.

Because formatting and I/O are handled asynchronously in a single background thread, users must be aware of the following:

• Data Lifetime: If you pass arguments by reference or pointer, you must ensure the referenced data remains valid until the log is flushed or closed. For dynamically allocated data, use std::string, std::shared_ptr, or std::unique_ptr to ensure safety.
• Crash Handling: In the event of a crash, log data currently in the queue may be lost. You should use the library's provided convenience functions to aid in flushing data during critical failures.
• Scalability Limits: Since all formatting occurs in a single background thread, extremely high volumes of parallel log entries or very expensive formatting could theoretically become a bottleneck.
• Predictability: Performance measurement may be less predictable as the OS might suspend other threads to allow the logging thread to run.

Because reckless buffers data asynchronously, a crash can result in losing the most recent (and often most important) log entries. To minimize this, use panic_flush in your crash handler.

Option 1: Using the provided convenience helpers Use install_crash_handler to automatically call panic_flush on a list of loggers when a crash occurs.

#include <reckless/crash_handler.hpp>

// In your setup code:
void setup() {
    // This installs a handler that calls panic_flush on g_log
    static scoped_crash_handler handler(&g_log);
}

Option 2: Manual integration If you already have a custom crash handler, simply call log.start_panic_flush() (or panic_flush as described in the basic_log API) within it. This puts the log into a "panic" state that prevents standard cleanup in the destructor to ensure the crash-related data is prioritized.

// #include <reckless/crash_handler.hpp>

void install_crash_handler(std::initializer_list<basic_log*> log);
void uninstall_crash_handler();

class scoped_crash_handler {
public:
    scoped_crash_handler(std::initializer_list<basic_log*> log)
    {
        install_crash_handler(log);
    }
    ~scoped_crash_handler()
    {
        uninstall_crash_handler();
    }
};

To use Reckless, you typically define a logger type using reckless::severity_log with a specific policy, then associate it with a writer (like reckless::file_writer).

reckless::severity_log is a policy-based logger that allows you to configure fields such as indentation, separators, severity markers, and timestamps.

Key Features:

• Type-safe printf-style syntax: Use %p, %s, %d, %f, etc., in a way that is type-safe and extensible.
• Scoped Indentation: Use reckless::scoped_indent to automatically indent all log lines within a specific C++ scope.

#include <reckless/severity_log.hpp>
#include <reckless/file_writer.hpp>

// Define a logger with specific formatting policies
using log_t = reckless::severity_log<
    reckless::indent<4>,       // 4 spaces of indent
    ' ',                       // Field separator
    reckless::severity_field,  // Show severity marker (D/I/W/E) first
    reckless::timestamp_field  // Then timestamp field
    >;

reckless::file_writer writer("log.txt");
log_t g_log(&writer);

int main()
{
    std::string s("Hello World!");

    // Type-safe printf-style logging
    g_log.debug("Pointer: %p", s.c_str());
    g_log.info("Info line: %s", s);

    for(int i=0; i!=4; ++i) {
        reckless::scoped_indent indent;  // Indents lines within this scope
        g_log.warn("Warning: %d", i);
    }

    g_log.error("Error: %f", 3.14);

    return 0;
}