VLink  2.3.0
A high-performance communication middleware
vlink::Logger Class Referencefinal

Global singleton logger with four formatting styles and independently configurable sinks. More...

#include <logger.h>

Collaboration diagram for vlink::Logger:

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
 

Detailed Description

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.

Member Typedef Documentation

◆ Callback

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.

◆ DetailInfo

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.

Member Enumeration Documentation

◆ Level

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 Exception::RuntimeError.

kOff 

Disable sink.

◆ Style

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 FastStream operator<<.

kFormatStyle 

Brace placeholders via vlink::format.

kCStyle 

printf-style formatting via std::snprintf.

Member Function Documentation

◆ disable_backtrace()

static void vlink::Logger::disable_backtrace ( )
staticnoexcept

Disables backtrace capture and discards the ring buffer.

Warning
Call during application runtime, before static object destruction begins.

◆ dump_backtrace()

static void vlink::Logger::dump_backtrace ( )
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.

Warning
Call during application runtime, before static object destruction begins.

◆ enable_backtrace()

static void vlink::Logger::enable_backtrace ( size_t  size)
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.

Parameters
sizeCapacity of the backtrace ring buffer.
Warning
Call during application runtime, before static object destruction begins.

◆ extract_filename()

constexpr std::string_view vlink::Logger::extract_filename ( std::string_view  path)
inlinestaticconstexprnoexcept

Strips a path down to its final filename component at compile time.

Details.

Parameters
pathSource path, typically FILE.
Returns
View covering the filename portion.

◆ flush()

static void vlink::Logger::flush ( )
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.

Warning
Call during application runtime, before static object destruction begins.

◆ get()

static Logger& vlink::Logger::get ( )
staticnoexcept

Returns the global logger instance.

Returns
Reference to the singleton.

◆ get_console_fmt_enable()

static bool vlink::Logger::get_console_fmt_enable ( )
staticnoexcept

Returns whether the extended console prefix is enabled.

Returns
true when timestamp, thread ID and severity fields are prepended.

◆ get_console_level()

static Level vlink::Logger::get_console_level ( )
staticnoexcept

Returns the current console sink severity threshold.

Returns
Current level.

◆ get_file_level()

static Level vlink::Logger::get_file_level ( )
staticnoexcept

Returns the current file sink severity threshold.

Returns
Current level.

◆ get_stream_flag()

static std::ios_base::fmtflags vlink::Logger::get_stream_flag ( )
staticnoexcept

Returns the stream format flags currently applied to stream-style records.

Returns
Format flags.

◆ get_stream_precision()

static int vlink::Logger::get_stream_precision ( )
staticnoexcept

Returns the floating-point precision used for stream-style records.

Returns
Precision value.

◆ get_stream_width()

static int vlink::Logger::get_stream_width ( )
staticnoexcept

Returns the field width used for stream-style records.

Returns
Width value.

◆ init()

static void vlink::Logger::init ( const std::string &  app_name = "",
const std::string &  log_path = "" 
)
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.

Parameters
app_nameApplication name embedded in log output. Default: empty (detect automatically).
log_pathBase directory for generated log files when app_name is non-empty. Default: empty (select automatically).

◆ is_busy()

static bool vlink::Logger::is_busy ( )
staticnoexcept

Reports whether the logger backend is being initialised.

Returns
true while backend initialisation is in progress.

◆ is_writable()

static bool vlink::Logger::is_writable ( Level  level)
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.

Parameters
levelSeverity level under test.
Returns
true when the logger is active and the level passes a sink threshold, or when level is kFatal.

◆ print() [1/2]

template<Logger::Level LevelT, typename... ArgsT>
void vlink::Logger::print ( [[maybe_unused] ] ArgsT &&...  args)
inline

◆ print() [2/2]

template<Level LevelT, typename... ArgsT>
static void vlink::Logger::print ( ArgsT &&...  args)
static

Convenience stream-style entry point without source location.

Template Parameters
LevelTCompile-time severity.
ArgsTStream argument types.
Parameters
argsValues to stream.

◆ print_c_style() [1/2]

template<Logger::Level LevelT, typename DetailT , typename FormatT , typename... ArgsT>
void vlink::Logger::print_c_style ( [[maybe_unused] ] DetailT &&  detail,
[[maybe_unused] ] FormatT &&  format,
[[maybe_unused] ] ArgsT &&...  args 
)
inline
Here is the call graph for this function:

◆ print_c_style() [2/2]

template<Logger::Level LevelT, typename DetailT , typename FormatT , typename... ArgsT>
static void vlink::Logger::print_c_style ( DetailT &&  detail,
FormatT &&  format,
ArgsT &&...  args 
)
static

printf-style entry point (used by CLOG_*).

Template Parameters
LevelTCompile-time severity.
DetailTEither DetailInfo or NoDetail.
FormatTFormat string type, typically const char*.
ArgsTprintf argument types.
Parameters
detailSource location info or NoDetail{}.
formatprintf-style format string.
argsprintf arguments.

◆ print_format_style() [1/2]

template<Logger::Level LevelT, typename DetailT , typename... ArgsT>
void vlink::Logger::print_format_style ( [[maybe_unused] ] DetailT &&  detail,
[[maybe_unused] ] format::format_string< ArgsT... >  format,
[[maybe_unused] ] ArgsT &&...  args 
)
inline
Here is the call graph for this function:

◆ print_format_style() [2/2]

template<Level LevelT, typename DetailT , typename... ArgsT>
static void vlink::Logger::print_format_style ( DetailT &&  detail,
format::format_string< ArgsT... >  format,
ArgsT &&...  args 
)
static

Placeholder-style entry point (used by MLOG_*).

Template Parameters
LevelTCompile-time severity.
DetailTEither DetailInfo or NoDetail.
ArgsTFormat argument types.
Parameters
detailSource location info or NoDetail{}.
formatFormat string with {} placeholders.
argsFormat arguments.

◆ print_stream_style() [1/2]

template<Logger::Level LevelT, typename DetailT , typename... ArgsT>
void vlink::Logger::print_stream_style ( [[maybe_unused] ] DetailT &&  detail,
[[maybe_unused] ] ArgsT &&...  args 
)
inline

◆ print_stream_style() [2/2]

template<Level LevelT, typename DetailT , typename... ArgsT>
static void vlink::Logger::print_stream_style ( DetailT &&  detail,
ArgsT &&...  args 
)
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.

Template Parameters
LevelTCompile-time severity.
DetailTEither DetailInfo or NoDetail.
ArgsTStream argument types.
Parameters
detailSource location info or NoDetail{}.
argsValues to stream.

◆ register_console_handler()

static void vlink::Logger::register_console_handler ( Callback &&  callback)
staticnoexcept

Installs a custom console sink callback replacing the built-in console writer.

Parameters
callbackHandler called with (level, message_view) for each record.

◆ register_file_handler()

static void vlink::Logger::register_file_handler ( Callback &&  callback)
staticnoexcept

Installs a custom file sink callback replacing the built-in file writer.

Parameters
callbackHandler called with (level, message_view) for each record.

◆ set_console_fmt_enable()

static void vlink::Logger::set_console_fmt_enable ( bool  enable)
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.

Parameters
enabletrue to prepend the extended fields, false to omit them.

◆ set_console_level()

static void vlink::Logger::set_console_level ( Level  level)
staticnoexcept

Sets the minimum severity for the console sink; pass kOff to mute it.

Parameters
levelMinimum output level.

◆ set_file_level()

static void vlink::Logger::set_file_level ( Level  level)
staticnoexcept

Sets the minimum severity for the file sink; pass kOff to mute it.

Parameters
levelMinimum output level.

◆ set_stream_flag()

static void vlink::Logger::set_stream_flag ( std::ios_base::fmtflags  flags)
staticnoexcept

Sets std::ios_base format flags applied to stream-style records.

Parameters
flagsStream format flags.

◆ set_stream_precision()

static void vlink::Logger::set_stream_precision ( int  precision)
staticnoexcept

Sets the floating-point precision for stream-style records.

Parameters
precisionPrecision passed to std::setprecision.

◆ set_stream_width()

static void vlink::Logger::set_stream_width ( int  width)
staticnoexcept

Sets the minimum field width for stream-style records.

Parameters
widthField width passed to std::setw.

◆ try_acquire_periodic_log()

static bool vlink::Logger::try_acquire_periodic_log ( Level  level,
int64_t  interval_ms,
std::atomic< uint64_t > &  last_log_time_ns 
)
staticnoexcept

Attempts to acquire the current period for one limited log call site.

Parameters
levelSeverity from kTrace through kError; other values are rejected.
interval_msMinimum interval in milliseconds; non-positive values disable limiting.
last_log_time_nsPer-call-site monotonic timestamp, initially 0.
Returns
true when the level is writable and the current period is acquired.

Friends And Related Function Documentation

◆ WrapperStream

template<Logger::Level LevelT>
friend struct WrapperStream
friend

Member Data Documentation

◆ kDetailLevel

constexpr uint8_t vlink::Logger::kDetailLevel = kWarn
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.

◆ kLocalBufferSize

constexpr int vlink::Logger::kLocalBufferSize = 4096
staticconstexpr

Size of each C-style format buffer in bytes.

Messages longer than kLocalBufferSize - 1 characters are silently truncated.

◆ kMinimumLevel

constexpr uint8_t vlink::Logger::kMinimumLevel = kTrace
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.


The documentation for this class was generated from the following file: