|
VLink
2.3.0
A high-performance communication middleware
|
Global singleton logger with four formatting styles and independently configurable sinks. More...
#include <logger.h>
Classes | |
| struct | NoDetail |
| Sentinel type indicating no detail prefix is attached. More... | |
| struct | WrapperStream |
RAII helper backing SLOG_*; collects tokens and flushes on destruction. More... | |
Public Types | |
| enum | Style : uint8_t { kStreamStyle = 0 , kFormatStyle = 1 , kCStyle = 2 } |
Internal output style tag used by the print_* family. More... | |
| enum | Level : uint8_t { kTrace = 0 , kDebug = 1 , kInfo = 2 , kWarn = 3 , kError = 4 , kFatal = 5 , kOff = 6 } |
| Message severity level. More... | |
| using | Callback = MoveFunction< void(Level, std::string_view)> |
| Signature for custom console / file sink callbacks. More... | |
| using | DetailInfo = std::pair< std::string_view, int > |
| Carries the source file name and line number for the detail prefix. More... | |
Public Member Functions | |
| template<Logger::Level LevelT, typename DetailT , typename... ArgsT> | |
| void | print_stream_style ([[maybe_unused]] DetailT &&detail, [[maybe_unused]] ArgsT &&... args) |
| template<Logger::Level LevelT, typename DetailT , typename... ArgsT> | |
| void | print_format_style ([[maybe_unused]] DetailT &&detail, [[maybe_unused]] format::format_string< ArgsT... > format, [[maybe_unused]] ArgsT &&... args) |
| template<Logger::Level LevelT, typename DetailT , typename FormatT , typename... ArgsT> | |
| void | print_c_style ([[maybe_unused]] DetailT &&detail, [[maybe_unused]] FormatT &&format, [[maybe_unused]] ArgsT &&... args) |
| template<Logger::Level LevelT, typename... ArgsT> | |
| void | print ([[maybe_unused]] ArgsT &&... args) |
Static Public Member Functions | |
| static void | init (const std::string &app_name="", const std::string &log_path="") noexcept |
| Initialises the logger singleton. More... | |
| static Logger & | get () noexcept |
| Returns the global logger instance. More... | |
| static void | flush () noexcept |
| Flushes stdout, stderr and the active built-in file backend or plugin. More... | |
| static void | register_console_handler (Callback &&callback) noexcept |
| Installs a custom console sink callback replacing the built-in console writer. More... | |
| static void | register_file_handler (Callback &&callback) noexcept |
| Installs a custom file sink callback replacing the built-in file writer. More... | |
| static void | set_console_level (Level level) noexcept |
Sets the minimum severity for the console sink; pass kOff to mute it. More... | |
| static void | set_file_level (Level level) noexcept |
Sets the minimum severity for the file sink; pass kOff to mute it. More... | |
| static void | set_console_fmt_enable (bool enable) noexcept |
| Enables or disables the extended prefix on the console sink. More... | |
| static Level | get_console_level () noexcept |
| Returns the current console sink severity threshold. More... | |
| static Level | get_file_level () noexcept |
| Returns the current file sink severity threshold. More... | |
| static bool | get_console_fmt_enable () noexcept |
| Returns whether the extended console prefix is enabled. More... | |
| static void | set_stream_flag (std::ios_base::fmtflags flags) noexcept |
Sets std::ios_base format flags applied to stream-style records. More... | |
| static void | set_stream_precision (int precision) noexcept |
| Sets the floating-point precision for stream-style records. More... | |
| static void | set_stream_width (int width) noexcept |
| Sets the minimum field width for stream-style records. More... | |
| static std::ios_base::fmtflags | get_stream_flag () noexcept |
| Returns the stream format flags currently applied to stream-style records. More... | |
| static int | get_stream_precision () noexcept |
| Returns the floating-point precision used for stream-style records. More... | |
| static int | get_stream_width () noexcept |
| Returns the field width used for stream-style records. More... | |
| static void | enable_backtrace (size_t size) noexcept |
Enables a file-backend ring buffer of the most recent size eligible records. More... | |
| static void | disable_backtrace () noexcept |
| Disables backtrace capture and discards the ring buffer. More... | |
| static void | dump_backtrace () noexcept |
| Dumps a snapshot to the built-in file backend and configured console sink. More... | |
| static bool | is_busy () noexcept |
| Reports whether the logger backend is being initialised. More... | |
| static bool | is_writable (Level level) noexcept |
Reports whether a record at level would currently be emitted. More... | |
| static bool | try_acquire_periodic_log (Level level, int64_t interval_ms, std::atomic< uint64_t > &last_log_time_ns) noexcept |
| Attempts to acquire the current period for one limited log call site. More... | |
| static constexpr std::string_view | extract_filename (std::string_view path) noexcept |
| Strips a path down to its final filename component at compile time. More... | |
| template<Level LevelT, typename DetailT , typename... ArgsT> | |
| static void | print_stream_style (DetailT &&detail, ArgsT &&... args) |
Stream-style entry point (used by VLOG_* / print). More... | |
| template<Level LevelT, typename DetailT , typename... ArgsT> | |
| static void | print_format_style (DetailT &&detail, format::format_string< ArgsT... > format, ArgsT &&... args) |
Placeholder-style entry point (used by MLOG_*). More... | |
| template<Logger::Level LevelT, typename DetailT , typename FormatT , typename... ArgsT> | |
| static void | print_c_style (DetailT &&detail, FormatT &&format, ArgsT &&... args) |
printf-style entry point (used by CLOG_*). More... | |
| template<Level LevelT, typename... ArgsT> | |
| static void | print (ArgsT &&... args) |
| Convenience stream-style entry point without source location. More... | |
Static Public Attributes | |
| static constexpr uint8_t | kMinimumLevel = kTrace |
| Compile-time minimum severity level; messages below this are stripped. More... | |
| static constexpr uint8_t | kDetailLevel = kWarn |
Severity threshold at and above which {file:line} is prepended to messages. More... | |
| static constexpr int | kLocalBufferSize = 4096 |
| Size of each C-style format buffer in bytes. More... | |
Friends | |
| template<Logger::Level LevelT> | |
| struct | WrapperStream |
Global singleton logger with four formatting styles and independently configurable sinks.
Configure exactly once via Logger::init before the first get or logging call. Calls after singleton construction do not rebuild the active backend and must not be used for reconfiguration. Console and file output are independently enabled by their level thresholds; an empty log_path selects the configured or temporary default directory. Logging entry points are macros that wrap the public print_* templates and forward a compile-time Level so the bodies disappear when the level is below kMinimumLevel.
| using vlink::Logger::Callback = MoveFunction<void(Level, std::string_view)> |
Signature for custom console / file sink callbacks.
Invoked synchronously from the logging thread, or the backend worker during backtrace replay. The view is valid only for the call. Handlers must support concurrent invocation. A handler may replace or unregister itself; such a registration takes effect once that handler returns, while registrations from other threads wait for handlers in progress and release the previous handler afterwards. Exceptions are reported to standard error and do not escape the logging boundary. Nested ordinary logging on the same thread is suppressed before arguments are evaluated; Fatal still throws.
| using vlink::Logger::DetailInfo = std::pair<std::string_view, int> |
Carries the source file name and line number for the detail prefix.
Built automatically by VLINK_LOG_GET_DETAIL when the message level reaches kDetailLevel.
| enum vlink::Logger::Level : uint8_t |
Message severity level.
Lower numerical values are less severe. kOff is a sentinel that disables a sink.
| Enumerator | |
|---|---|
| kTrace | Verbose tracing. |
| kDebug | Developer diagnostics. |
| kInfo | Normal operational message. |
| kWarn | Recoverable but unusual condition. |
| kError | Recoverable error. |
| kFatal | Unrecoverable; throws |
| kOff | Disable sink. |
| enum vlink::Logger::Style : uint8_t |
Internal output style tag used by the print_* family.
Callers normally interact with styles via macros; the enum is exposed for completeness.
| Enumerator | |
|---|---|
| kStreamStyle | Stream composition via |
| kFormatStyle | Brace placeholders via |
| kCStyle | printf-style formatting via |
|
staticnoexcept |
Disables backtrace capture and discards the ring buffer.
|
staticnoexcept |
Dumps a snapshot to the built-in file backend and configured console sink.
Console replay obeys its current threshold and handler, including Off. Retained records remain available for console replay after a permanent file error.
|
staticnoexcept |
Enables a file-backend ring buffer of the most recent size eligible records.
Console output keeps its threshold and handler. The file backend keeps every record in the ring and additionally writes Warn or higher immediately. Calling again resets the ring to the supplied capacity.
| size | Capacity of the backtrace ring buffer. |
|
inlinestaticconstexprnoexcept |
Strips a path down to its final filename component at compile time.
Details.
| path | Source path, typically FILE. |
|
staticnoexcept |
Flushes stdout, stderr and the active built-in file backend or plugin.
Useful before abnormal termination. Invoked automatically before a kFatal message throws. Custom handlers manage their own buffering and flushing.
|
staticnoexcept |
Returns the global logger instance.
|
staticnoexcept |
Returns whether the extended console prefix is enabled.
true when timestamp, thread ID and severity fields are prepended.
|
staticnoexcept |
Returns the current console sink severity threshold.
|
staticnoexcept |
Returns the current file sink severity threshold.
|
staticnoexcept |
Returns the stream format flags currently applied to stream-style records.
|
staticnoexcept |
Returns the floating-point precision used for stream-style records.
|
staticnoexcept |
Returns the field width used for stream-style records.
|
staticnoexcept |
Initialises the logger singleton.
Must be invoked before get or any logging macro. Only values supplied before the file channel is initialised configure the backend; later calls do not rebuild active sinks. File output is controlled by the file level. An empty log_path selects VLINK_LOG_DIR or a temporary default directory followed by app_name; VLINK_LOG_PID_ENABLE=1 appends the PID so concurrent instances of one application never share a rotating file set. An explicit directory must be owned by one live process.
| app_name | Application name embedded in log output. Default: empty (detect automatically). |
| log_path | Base directory for generated log files when app_name is non-empty. Default: empty (select automatically). |
|
staticnoexcept |
Reports whether the logger backend is being initialised.
true while backend initialisation is in progress.
|
staticnoexcept |
Reports whether a record at level would currently be emitted.
Ordinary logging macros already use this gate before evaluating their arguments. Call it directly only to guard preparation performed outside a macro call.
| level | Severity level under test. |
true when the logger is active and the level passes a sink threshold, or when level is kFatal.
|
inline |
|
static |
Convenience stream-style entry point without source location.
| LevelT | Compile-time severity. |
| ArgsT | Stream argument types. |
| args | Values to stream. |
|
inline |
|
static |
printf-style entry point (used by CLOG_*).
| LevelT | Compile-time severity. |
| DetailT | Either DetailInfo or NoDetail. |
| FormatT | Format string type, typically const char*. |
| ArgsT | printf argument types. |
| detail | Source location info or NoDetail{}. |
| format | printf-style format string. |
| args | printf arguments. |
|
inline |
|
static |
|
inline |
|
static |
Stream-style entry point (used by VLOG_* / print).
Returns immediately when should_log<LevelT>() is false. Otherwise streams args into a thread-local FastStream and hands the resulting view to the sinks.
| LevelT | Compile-time severity. |
| DetailT | Either DetailInfo or NoDetail. |
| ArgsT | Stream argument types. |
| detail | Source location info or NoDetail{}. |
| args | Values to stream. |
|
staticnoexcept |
Installs a custom console sink callback replacing the built-in console writer.
| callback | Handler called with (level, message_view) for each record. |
|
staticnoexcept |
Installs a custom file sink callback replacing the built-in file writer.
| callback | Handler called with (level, message_view) for each record. |
|
staticnoexcept |
Enables or disables the extended prefix on the console sink.
The extended prefix contains the timestamp, thread ID and severity. ANSI level colours are independent of this setting.
| enable | true to prepend the extended fields, false to omit them. |
|
staticnoexcept |
Sets the minimum severity for the console sink; pass kOff to mute it.
| level | Minimum output level. |
|
staticnoexcept |
Sets the minimum severity for the file sink; pass kOff to mute it.
| level | Minimum output level. |
|
staticnoexcept |
Sets std::ios_base format flags applied to stream-style records.
| flags | Stream format flags. |
|
staticnoexcept |
Sets the floating-point precision for stream-style records.
| precision | Precision passed to std::setprecision. |
|
staticnoexcept |
Sets the minimum field width for stream-style records.
| width | Field width passed to std::setw. |
|
staticnoexcept |
Attempts to acquire the current period for one limited log call site.
| level | Severity from kTrace through kError; other values are rejected. |
| interval_ms | Minimum interval in milliseconds; non-positive values disable limiting. |
| last_log_time_ns | Per-call-site monotonic timestamp, initially 0. |
true when the level is writable and the current period is acquired.
|
friend |
|
staticconstexpr |
Severity threshold at and above which {file:line} is prepended to messages.
Override by defining VLINK_LOG_DETAIL_LEVEL before including this header. Defaults to kWarn.
|
staticconstexpr |
Size of each C-style format buffer in bytes.
Messages longer than kLocalBufferSize - 1 characters are silently truncated.
|
staticconstexpr |
Compile-time minimum severity level; messages below this are stripped.
Override by defining VLINK_LOG_LEVEL before including this header. Defaults to kTrace so every level is emitted by default.