VLink  2.3.0
A high-performance communication middleware
vlink::Logger类 参考final

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

#include <logger.h>

vlink::Logger 的协作图:

类

struct  NoDetail
 Sentinel type indicating no detail prefix is attached. 更多...
 
struct  WrapperStream
 RAII helper backing SLOG_*; collects tokens and flushes on destruction. 更多...
 

Public 类型

enum  Style : uint8_t { kStreamStyle = 0 , kFormatStyle = 1 , kCStyle = 2 }
 Internal output style tag used by the print_* family. 更多...
 
enum  Level : uint8_t {
  kTrace = 0 , kDebug = 1 , kInfo = 2 , kWarn = 3 ,
  kError = 4 , kFatal = 5 , kOff = 6
}
 Message severity level. 更多...
 
using Callback = MoveFunction< void(Level, std::string_view)>
 Signature for custom console / file sink callbacks. 更多...
 
using DetailInfo = std::pair< std::string_view, int >
 Carries the source file name and line number for the detail prefix. 更多...
 

Public 成员函数

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)
 

静态 Public 成员函数

static void init (const std::string &app_name="", const std::string &log_path="") noexcept
 Initialises the logger singleton. 更多...
 
static Logger & get () noexcept
 Returns the global logger instance. 更多...
 
static void flush () noexcept
 Flushes stdout, stderr and the active built-in file backend or plugin. 更多...
 
static void register_console_handler (Callback &&callback) noexcept
 Installs a custom console sink callback replacing the built-in console writer. 更多...
 
static void register_file_handler (Callback &&callback) noexcept
 Installs a custom file sink callback replacing the built-in file writer. 更多...
 
static void set_console_level (Level level) noexcept
 Sets the minimum severity for the console sink; pass kOff to mute it. 更多...
 
static void set_file_level (Level level) noexcept
 Sets the minimum severity for the file sink; pass kOff to mute it. 更多...
 
static void set_console_fmt_enable (bool enable) noexcept
 Enables or disables the extended prefix on the console sink. 更多...
 
static Level get_console_level () noexcept
 Returns the current console sink severity threshold. 更多...
 
static Level get_file_level () noexcept
 Returns the current file sink severity threshold. 更多...
 
static bool get_console_fmt_enable () noexcept
 Returns whether the extended console prefix is enabled. 更多...
 
static void set_stream_flag (std::ios_base::fmtflags flags) noexcept
 Sets std::ios_base format flags applied to stream-style records. 更多...
 
static void set_stream_precision (int precision) noexcept
 Sets the floating-point precision for stream-style records. 更多...
 
static void set_stream_width (int width) noexcept
 Sets the minimum field width for stream-style records. 更多...
 
static std::ios_base::fmtflags get_stream_flag () noexcept
 Returns the stream format flags currently applied to stream-style records. 更多...
 
static int get_stream_precision () noexcept
 Returns the floating-point precision used for stream-style records. 更多...
 
static int get_stream_width () noexcept
 Returns the field width used for stream-style records. 更多...
 
static void enable_backtrace (size_t size) noexcept
 Enables a file-backend ring buffer of the most recent size eligible records. 更多...
 
static void disable_backtrace () noexcept
 Disables backtrace capture and discards the ring buffer. 更多...
 
static void dump_backtrace () noexcept
 Dumps a snapshot to the built-in file backend and configured console sink. 更多...
 
static bool is_busy () noexcept
 Reports whether the logger backend is being initialised. 更多...
 
static bool is_writable (Level level) noexcept
 Reports whether a record at level would currently be emitted. 更多...
 
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. 更多...
 
static constexpr std::string_view extract_filename (std::string_view path) noexcept
 Strips a path down to its final filename component at compile time. 更多...
 
template<Level LevelT, typename DetailT , typename... ArgsT>
static void print_stream_style (DetailT &&detail, ArgsT &&... args)
 Stream-style entry point (used by VLOG_* / print). 更多...
 
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_*). 更多...
 
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_*). 更多...
 
template<Level LevelT, typename... ArgsT>
static void print (ArgsT &&... args)
 Convenience stream-style entry point without source location. 更多...
 

静态 Public 属性

static constexpr uint8_t kMinimumLevel = kTrace
 Compile-time minimum severity level; messages below this are stripped. 更多...
 
static constexpr uint8_t kDetailLevel = kWarn
 Severity threshold at and above which {file:line} is prepended to messages. 更多...
 
static constexpr int kLocalBufferSize = 4096
 Size of each C-style format buffer in bytes. 更多...
 

友元

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.

成员类型定义说明

◆ 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.

成员枚举类型说明

◆ Level

enum vlink::Logger::Level : uint8_t

Message severity level.

Lower numerical values are less severe. kOff is a sentinel that disables a sink.

枚举值
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.

枚举值
kStreamStyle 

Stream composition via FastStream operator<<.

kFormatStyle 

Brace placeholders via vlink::format.

kCStyle 

printf-style formatting via std::snprintf.

成员函数说明

◆ disable_backtrace()

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

Disables backtrace capture and discards the ring buffer.

警告
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.

警告
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.

参数
sizeCapacity of the backtrace ring buffer.
警告
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

参数
pathSource path, typically FILE.
返回
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.

警告
Call during application runtime, before static object destruction begins.

◆ get()

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

Returns the global logger instance.

返回
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.

返回
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.

返回
Current level.

◆ get_file_level()

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

Returns the current file sink severity threshold.

返回
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.

返回
Format flags.

◆ get_stream_precision()

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

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

返回
Precision value.

◆ get_stream_width()

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

Returns the field width used for stream-style records.

返回
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.

参数
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.

返回
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.

参数
levelSeverity level under test.
返回
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.

模板参数
LevelTCompile-time severity.
ArgsTStream argument types.
参数
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
函数调用图:

◆ 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_*).

模板参数
LevelTCompile-time severity.
DetailTEither DetailInfo or NoDetail.
FormatTFormat string type, typically const char*.
ArgsTprintf argument types.
参数
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
函数调用图:

◆ 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_*).

模板参数
LevelTCompile-time severity.
DetailTEither DetailInfo or NoDetail.
ArgsTFormat argument types.
参数
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.

模板参数
LevelTCompile-time severity.
DetailTEither DetailInfo or NoDetail.
ArgsTStream argument types.
参数
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.

参数
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.

参数
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.

参数
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.

参数
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.

参数
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.

参数
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.

参数
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.

参数
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.

参数
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.
返回
true when the level is writable and the current period is acquired.

友元及相关函数文档

◆ WrapperStream

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

类成员变量说明

◆ 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.


该类的文档由以下文件生成: