spdlog日志库源码：registry类
registry类意义
已经有了用于接收前端用户log消息的类logger，代表log消息的类是log_msg，后端写log消息到目标文件的类sink，格式化log消息为最终字符串的类formatter，解析pattern flag的类pattern_formatter等等。但似乎还存在一个问题：库的使用者，如何使用它们？
每次使用时，可能需要先创建logger对象，然后通过logger对象来接收用户log消息。然而，当用户希望创建多个logger对象时，谁来组织logger对象？谁来辨识logger name对应logger对象是否已经创建？如何通过logger name获取对应logger对象？能否有一个全局的默认logger，用户不需要做复杂设置？
这就可以用registry类，维护：
1）一个默认的全局logger对象；
2）一个logger对象的全局注册表，logger name就是其唯一标识；
3）一个线程池，用于异步写log；
4）一个周期工作线程，用于执行定时任务；
registry类实现
registry数据成员
registry是一个综合性的类，包含多种功能。其核心功能是提供全局logger对象注册表，主要数据成员，分为这几部分：
1）logger对象注册表loggers_，map存放；
2）缺省的logger对象default_logger_，便捷接口；
3）缺省的formatter格式器formatter_，通常为pattern_formatter，方便编译pattern字符串；
4）一个线程池tp_，用于异步写log；
5）线程安全，3个不同的锁用于保护数据；
6）异常处理，缺省的全局配置，以及错误回调；
7）杂项；
具体来说：
class SPDLOG_API registry
{
private:
// logger_map_mutex_是loggers_的互斥锁, flusher_mutex_是periodic_flusher_的互斥锁
std::mutex logger_map_mutex_, flusher_mutex_;
std::recursive_mutex tp_mutex_; // 线程池tp_的递归锁
std::unordered_map<std::string, std::shared_ptr<logger>> loggers_; // logger对象注册表, 存放(logger name, logger对象共享指针)
log_levels log_levels_; // 用户事先指定的log等级, map存放(logger name, log level)
std::unique_ptr<formatter> formatter_; // pattern 格式器, 默认为pattern_formatter实例
spdlog::level::level_enum global_log_level_ = level::info; // 全局log等级值, 新logger对象缺省log等级
level::level_enum flush_level_ = level::off; // flush等级值, 新logger对象缺省flush等级
err_handler err_handler_; // 错误处理, 发生错误时回调
std::shared_ptr<thread_pool> tp_; // 线程池, 用于异步写log, 但registry并不是线程池创建者
std::unique_ptr<periodic_worker> periodic_flusher_; // 定时flush
std::shared_ptr<logger> default_logger_; // 默认的logger对象
bool automatic_registration_ = true; // 自动注册logger对象选项
size_t backtrace_n_messages_ = 0; // 回溯消息个数, 每个logger对象都可以设置一个环形缓冲区
};
registry函数成员
构造与析构
构造函数创建一个默认的logger对象，将stdout作为输出目标。formatter_也是用默认的pattern_formatter类构造，用于所有注册的logger对象作为编译pattern字符串的对象。
// 构造函数
SPDLOG_INLINE registry::registry()
: formatter_(new pattern_formatter())
{
#ifndef SPDLOG_DISABLE_DEFAULT_LOGGER // 控制是否关闭default logger对象
// 针对不同的平台, 创建不同的sink, 作为logger输出目标
// create default logger (ansicolor_stdout_sink_mt or wincolor_stdout_sink_mt in windows).
# ifdef _WIN32 // Windows平台
auto color_sink = std::make_shared<sinks::wincolor_stdout_sink_mt>();
# else // non-Windows平台
auto color_sink = std::make_shared<sinks::ansicolor_stdout_sink_mt>();
# endif
const char *default_logger_name = ""; // default logger名称
default_logger_ = std::make_shared<spdlog::logger>(default_logger_name, std::move(color_sink));
loggers_[default_logger_name] = default_logger_; // 加入注册表
#endif // SPDLOG_DISABLE_DEFAULT_LOGGER
}
// 默认合成的析构函数
SPDLOG_INLINE registry::~registry() = default;
单例模式
registry为何要实现为单例？
因为registry提供全局唯一的注册表、默认的logger对象、缺省全局配置、后端线程池等唯一性资源，需要确保registry对象的唯一性。
registry类实现单例模式，是采用典型的惯用实现方法。我之前在这篇文章C++ 单例模式浅析中分析过，这种方式创建的单例模式并不是线程安全的。
// 单例模式惯用法实现registry
class SPDLOG_API registry
{
public:
registry(const registry &) = delete;
registry &operator=(const registry &) = delete;
...
static registry &instance();
private:
registry();
~registry();
...
SPDLOG_INLINE registry ®istry::instance()
{
static registry s_instance;
return s_instance;
}
全局注册表
作为一个单例模式，registry确保了自身全局唯一实例。而registry通过维护一个map结构的注册表loggers_，存放logger对象，索引key是logger name。当用户新建了一个logger对象，想要在注册表中搜到，先要通过register_logger将其加入注册表；如果后面想要获取，可以通过get接口得到。
public:
// 注册一个logger对象到注册表
void register_logger(std::shared_ptr<logger> new_logger);
std::shared_ptr<logger> get(const std::string &logger_name);
...
private:
std::unordered_map<std::string, std::shared_ptr<logger>> loggers_; // logger对象注册表, 存放(logger name, logger对象)
- 注册logger对象
注册logger对象的实现register_logger很简单，就是先检测注册表中是否存在对应名称的logger对象，如果存在，就抛出异常；如果不存在，就加入。因此，需要十分注意：不能重复注册同一个logger名称的logger对象。
// 注册logger对象
SPDLOG_INLINE void registry::register_logger(std::shared_ptr<logger> new_logger)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_); // 由于是public接口，先获得锁，再对loggers_进行操作
register_logger_(std::move(new_logger));
}
// private实现
SPDLOG_INLINE void registry::register_logger_(std::shared_ptr<logger> new_logger)
{
auto logger_name = new_logger->name();
throw_if_exists_(logger_name); // 确保logger name唯一
loggers_[logger_name] = std::move(new_logger);
}
// 如果logger_name对应项存在, 就抛出异常
SPDLOG_INLINE void registry::throw_if_exists_(const std::string &logger_name)
{
if (loggers_.find(logger_name) != loggers_.end())
{
throw_spdlog_ex("logger with name '" + logger_name + "' already exists");
}
}
- 查找logger对象
get实现查找logger对象更简单，直接对map的结构loggers_根据key（logger name）进行查找。
// 根据logger_name查找logger对象
SPDLOG_INLINE std::shared_ptr<logger> registry::get(const std::string &logger_name)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_); // 由于是public接口，先获得锁，再对loggers_进行操作
auto found = loggers_.find(logger_name);
return found == loggers_.end() ? nullptr : found->second;
}
initialize_logger初始化logger对象
当用户新建一个logger对象后，该如何设置其属性成员呢？
registry通过initialize_logger接口，为其提供默认初始化方式，无需为每个属性再单独设置。使用initialize_logger初始化的logger对象，会自动添加进全局注册表；如果是手动初始化的logger对象，则需要手动添加进全局注册表。
// 初始化一个logger对象new_logger
SPDLOG_INLINE void registry::initialize_logger(std::shared_ptr<logger> new_logger)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
new_logger->set_formatter(formatter_->clone());
if (err_handler_) // 注意：err_handler_受互斥锁logger_map_mutex_保护
{
new_logger->set_error_handler(err_handler_);
}
// 判断用户是否有事先指定new_logger的log level, 如果有就按事先指定的设置; 如果没有, 就用默认的
// set new level according to previously configured level or default level
auto it = log_levels_.find(new_logger->name());
auto new_level = it != log_levels_.end() ? it->second : global_log_level_;
new_logger->set_level(new_level);
// 设置flush level
new_logger->flush_on(flush_level_);
// 设置环形缓冲区, 用于回溯最近的log消息
if (backtrace_n_messages_ > 0)
{
new_logger->enable_backtrace(backtrace_n_messages_);
}
// 自动注册进全局注册表
if (automatic_registration_)
{
register_logger_(std::move(new_logger));
}
}
全局格式器
每个logger对象都拥有自己的格式器（formatter）成员，也就是说，能指定各自的pattern，从而决定输出的log消息格式。但如果想通过一个接口，为所有logger设置格式器，该怎么办？
此时，可以用到registry的全局格式器，接口set_formatter能为所有已注册的logger对象更新格式器。
// 为所有已注册的logger对象设置格式器
// Set global formatter. Each sink in each logger will get a clone of this object
SPDLOG_INLINE void registry::set_formatter(std::unique_ptr<formatter> formatter)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
formatter_ = std::move(formatter);
// 为所有注册表loggers_中的logger对象更新formatter
for (auto &l : loggers_)
{
l.second->set_formatter(formatter_->clone()); // 注意这类调用了formatter::clone深度克隆对象
}
}
预置日志等级
- 预置日志等级
spdlog支持事先为logger对象预置日志等级，待到新建的logger对象用initialize_logger()初始化时，为其指定log level。也就是说，此时尚未创建logger对象。
预置的日志等级log_levels_是log_levels类型，本质上一个unordered_map，key是logger name， value是log level枚举值。也就是说，spdlog只支持内置的日志等级（已经定义的那几个）。
using log_levels = std::unordered_map<std::string, level::level_enum>;
预置日志等级工作原理：通过环境变量或main启动参数，为logger对象指定log level，通过registry::set_level将其存放进map log_levels_中。当调用initialize_logger对logger对象进行初始化时，会从log_levels_中查找是否已经预置log level，如果已经预置，就直接用预置的日志等级初始化当前新建的logger对象；如果没有预置，就用缺省的global_log_level_来设置。
SPDLOG_INLINE void registry::initialize_logger(std::shared_ptr<logger> new_logger)
{
...
// 根据预置的log level或缺省的level, 来设置新logger对象的level
// set new level according to previously configured level or default level
auto it = log_levels_.find(new_logger->name());
auto new_level = it != log_levels_.end() ? it->second : global_log_level_;
new_logger->set_level(new_level);
...
}
- 更新日志等级
程序启动后，或者logger对象加入注册表后，有没有办法根据修改的预置日志等级更新？
答案是有的，可以通过registry::set_levels为所有已注册logger对象更新预置日志等级。
initialize_logger中设置预置日志等级，只会更新单个logger对象的日志等级，而set_levels中设置，则会更新所有已注册logger对象的日志等级。
// 更新日志等级
// 当想为已注册logger对象更新时，指定levels即可；当想更新全局日志等级时，需要指定global_level
SPDLOG_INLINE void registry::set_levels(log_levels levels, level::level_enum *global_level)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
log_levels_ = std::move(levels);
auto global_level_requested = global_level != nullptr;
global_log_level_ = global_level_requested ? *global_level : global_log_level_;
// 为所有已注册logger对象更新日志等级, 优先用预置的, 没有找到预置时, 再用全局的
for (auto &logger : loggers_)
{
auto logger_entry = log_levels_.find(logger.first);
if (logger_entry != log_levels_.end())
{
logger.second->set_level(logger_entry->second);
}
else if (global_level_requested)
{
logger.second->set_level(*global_level);
}
}
}
flush日志等级
spdlog支持单独flush（冲刷）指定level的日志消息（与记录日志的level分开）到目标文件，registry提供flush_on接口，设置（注册的）logger对象全局的flush_level_。
// 为每个已注册logger对象设置flush等级
// 当各个logger对象调用自身flush函数时, 会根据该flush等级与log消息的等级判断是否应该将文件立即冲刷到目标文件
SPDLOG_INLINE void registry::flush_on(level::level_enum log_level)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
for (auto &l : loggers_)
{
l.second->flush_on(log_level);
}
flush_level_ = log_level;
}
flush_level_并不是单独工作，而是搭配定时器periodic_flusher_，定时调用flush_every，从而实现定时冲刷指定level的log消息。
// 指定一个周期性工作的线程, 定时flush所有logger
template<typename Rep, typename Period>
void flush_every(std::chrono::duration<Rep, Period> interval)
{
std::lock_guard<std::mutex> lock(flusher_mutex_);
auto clbk = [this]() { this->flush_all(); };
periodic_flusher_ = details::make_unique<periodic_worker>(clbk, interval);
}
// flush所有已注册logger对象的log消息到目标文件
// 要求logger对象必须是线程安全的
SPDLOG_INLINE void registry::flush_all()
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
for (auto &l : loggers_)
{
l.second->flush();
}
}
默认logger
为了方便用户spdlog，registry提供了默认logger对象default_logger_，无需用户再手动创建、设置。default_logger_的默认目标（sink）是控制台（stdout），可以很方便用户调试。
- 获取默认的logger
获取默认的logger对象，有两种方式：
1）default_logger()获取共享指针管理的logger对象，线程安全；
2）通过shared_ptr<>::get()获取raw pointer，速度default_logger()比更快，但无法与set_default_logger()并发调用。
// 获取shared_ptr管理的默认logger, 线程安全
SPDLOG_INLINE std::shared_ptr<logger> registry::default_logger()
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
return default_logger_;
}
// 获取指向默认logger的raw pointer, 非线程安全, 但速度更快
// Return raw ptr to the default logger.
// To be used directly by the spdlog default api (e.g. spdlog::info)
// This make the default API faster, but cannot be used concurrently with set_default_logger().
// e.g do not call set_default_logger() from one thread while calling spdlog::info() from another.
SPDLOG_INLINE logger *registry::get_default_raw()
{
return default_logger_.get();
}
- 更新默认的logger
如果用户不想使用默认的logger对象，或者说，在不改变接口情况下，想将其替换成用户自定logger对象，那么可以调用registry::set_default_logger。
set_default_logger的实现很简单，思路是：先从全局注册表loggers_移除现有的默认logger对象，然后将新对象new_default_logger添加进注册表，最后将default_logger_指向新对象new_default_logger。
// set default logger.
// default logger is stored in default_logger_ (for faster retrieval) and in the loggers_ map.
SPDLOG_INLINE void registry::set_default_logger(std::shared_ptr<logger> new_default_logger)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
// 先从注册表删除
// remove previous default logger from the map
if (default_logger_ != nullptr)
{
loggers_.erase(default_logger_->name());
}
// 再将新的new_default_logger加入注册表
if (new_default_logger != nullptr)
{
loggers_[new_default_logger->name()] = new_default_logger;
}
// 更新默认的logger
default_logger_ = std::move(new_default_logger);
}
在已注册logger上应用函数
有时，用户希望将已注册的logger对象作为参数，调用一个自定义函数。此时，可以用到apply_all接口。
实现思路是：将自定义函数作为函数参数，传入apply_all，对每个已注册的logger对象都调用fun()。
// 将已注册logger作为参数, 应用到函数fun
SPDLOG_INLINE void registry::apply_all(const std::function<void(const std::shared_ptr<logger>)> &fun)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
for (auto &l : loggers_)
{
fun(l.second);
}
}
回溯最近的log消息
logger对象包含backtracer（环形队列）成员用于回溯最近的log消息，registry提供enable_backtrace接口，方便用户设置、开启该功能。
- 开启回溯功能
开启回溯功能，实际上是将用户指定的消息条数转发给已注册logger，以开启并设置队列大小。
// 开启回溯功能
// 指定logger对象的环形缓冲区大小，设置了大小才能回溯最近的log消息
SPDLOG_INLINE void registry::enable_backtrace(size_t n_messages)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_); // 加锁确保线程安全
backtrace_n_messages_ = n_messages;
for (auto &l : loggers_)
{
l.second->enable_backtrace(n_messages);
}
}
- 关闭回溯功能
关闭回溯功能，类似于开启，都是转发给已注册的logger，进行相应的设置。
// 关闭回溯功能
SPDLOG_INLINE void registry::disable_backtrace()
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
backtrace_n_messages_ = 0;
for (auto &l : loggers_)
{
l.second->disable_backtrace();
}
}
线程安全
registry用了2把互斥锁（std::mutex） + 1把递归锁（std::recursive_mutex）。总原则: logger_map_mutex_保护几乎所有数据成员，flusher_mutex_和tp_mutex_分别只保护periodic_flusher_、tp_。
tp_mutex_为何用递归锁，而不用普通互斥锁？
因为tp_mutex_保护的是线程池tp_，registry为其提供了public接口tp_mutex()导致该锁可能会被多个线程访问，get_tp()接口导致可能多次加锁。由于线程池对象tp_创建后不再修改（除了释放），因此多线程环境下并发访问通常也是安全的，因此使用递归锁没有问题。
错误处理
logger对象本身包含错误回调err_handler_，registry的err_handler_存在意义就是为logger的错误回调提供缓存及用户接口。
- 设置错误回调
可通过registry的set_error_handler接口，为每个logger对象更新错误回调。
SPDLOG_INLINE void registry::set_error_handler(err_handler handler)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
for (auto &l : loggers_)
{
l.second->set_error_handler(handler);
}
err_handler_ = std::move(handler);
}
- 什么时候调用错误回调？
对logger的错误回调，实际上包装到了用于异常处理的宏SPDLOG_LOGGER_CATCH中，当catch到异常时，就会回调err_handler_。如果用户通过registry::set_error_handler提供了自定义错误处理函数，那么就调用用户的；如果没有提供，就调用默认的logger::err_handler_，在控制台打印错误信息。
#ifndef SPDLOG_NO_EXCEPTIONS
# define SPDLOG_LOGGER_CATCH(location) \
catch (const std::exception &ex) \
{ \
if (location.filename) \
{ \
err_handler_(fmt_lib::format(SPDLOG_FMT_STRING("{} [{}({})]"), ex.what(), location.filename, location.line)); \
} \
else \
{ \
err_handler_(ex.what()); \
} \
} \
catch (...) \
{ \
err_handler_("Rethrowing unknown exception in logger"); \
throw; \
}
#else
# define SPDLOG_LOGGER_CATCH(location)
#endif
例如，loger在将log消息转交给sink，将内容写到文件的时候，可能发生写失败的错误，抛出异常；在registry查找指定logger name不存在的时候，抛出异常。
// 在注册表查找logger name
SPDLOG_INLINE void registry::throw_if_exists_(const std::string &logger_name)
{
if (loggers_.find(logger_name) != loggers_.end())
{ // 不存在则抛出异常
throw_spdlog_ex("logger with name '" + logger_name + "' already exists");
}
}
common模块为抛出异常提供便捷接口，有2个重载版本，分别针对系统调用错误、非系统调用错误。
# define SPDLOG_TRY try
# define SPDLOG_THROW(ex) throw(ex)
# define SPDLOG_CATCH_STD catch (const std::exception &) {}
[[noreturn]] SPDLOG_API void throw_spdlog_ex(const std::string &msg, int last_errno);
[[noreturn]] SPDLOG_API void throw_spdlog_ex(std::string msg);
// 系统调用错误 抛出异常
SPDLOG_INLINE void throw_spdlog_ex(const std::string &msg, int last_errno)
{
SPDLOG_THROW(spdlog_ex(msg, last_errno));
}
// 非系统调用错误 抛出异常
SPDLOG_INLINE void throw_spdlog_ex(std::string msg)
{
SPDLOG_THROW(spdlog_ex(std::move(msg)));
}
定时工作类periodic_worker
registry::flush_every中，创建了一个定时工作类periodic_worker对象。该类构造时，会启动一个线程，在其中利用锁+条件变量定时执行用户回调，从而实现用户自定义任务的定时执行。
// 定时工作者类periodic_worker, 为用户自定义任务fun提供定时回调功能
class SPDLOG_API periodic_worker
{
public:
// 构造函数
template<typename Rep, typename Period>
periodic_worker(const std::function<void()> &callback_fun, std::chrono::duration<Rep, Period> interval);
// 禁用copy操作
periodic_worker(const periodic_worker &) = delete;
periodic_worker &operator=(const periodic_worker &) = delete;
// stop the worker thread and join it
~periodic_worker();
private:
bool active_;
std::thread worker_thread_;
std::mutex mutex_;
std::condition_variable cv_;
};
- 构造函数
注意到periodic_worker构造函数是一个函数模板，这是为什么？
因为用户传入的时间间隔参数（interval）的类型并不确定，可能是秒（chrono::seconds），也可能是毫秒（chrono::milliseconds），或者分钟（chrono::minutes）等等，为了兼容这些类型，因而使用模板来支持。
template<typename Rep, typename Period>
periodic_worker(const std::function<void()> &callback_fun, std::chrono::duration<Rep, Period> interval)
{
active_ = (interval > std::chrono::duration<Rep, Period>::zero());
if (!active_)
{
return;
}
// for循环+互斥锁+条件变量 实现子线程主循环, 以定时执行callback_fun
worker_thread_ = std::thread([this, callback_fun, interval]() {
for (;;)
{
std::unique_lock<std::mutex> lock(this->mutex_);
// wait_for等到超时, 返回cv_status::timeout(true)
// 如果wait_for第三个参数如果返回true, 则不再等待; 如果返回false, 则继续等待
// active_ 控制线程(循环)是否退出
if (this->cv_.wait_for(lock, interval, [this] { return !this->active_; }))
{
return; // active_ == false, so exit this thread
}
callback_fun();
}
});
}
- 析构函数
析构函数就是让子线程退出死循环，结束线程运行；母线程连接子线程以回收资源。
// stop the worker thread and join it
SPDLOG_INLINE periodic_worker::~periodic_worker()
{
if (worker_thread_.joinable()) // 只有线程可连接情况下, 连接线程才有意义
{
{
std::lock_guard<std::mutex> lock(mutex_);
// 为什么active_使用bool类型, 而不用atomic<bool>类型？
// 因为进入子线程后, 只有periodic_worker对象析构时才会写active, 其他情况只读, 不会造成线程安全问题
active_ = false;
}
cv_.notify_one();
worker_thread_.join();
}
}
registry类应用
虽然registry是单例模式，但spdlog并没有打算让用户直接像下面这种方式，调用registry对库进行，而是提供了便捷的全局接口。实现方式，是在registry对应接口基础上，进行了包装，简化了调用。
initialize_logger初始化logger对象
比如，初始化一个logger对象，如果直接使用registry，就得这样：
details::registry::instance().initialize_logger(std::move(logger));
spdlog提供了便捷接口：
// 初始化、注册一个logger对象
// Example:
// auto mylogger = std::make_shared<spdlog::logger>("mylogger", ...);
// spdlog::initialize_logger(mylogger);
SPDLOG_INLINE void initialize_logger(std::shared_ptr<logger> logger)
{
details::registry::instance().initialize_logger(std::move(logger));
}
get查找logger对象
// 根据logger name查找已注册logger对象
SPDLOG_INLINE std::shared_ptr<logger> get(const std::string &name)
{
return details::registry::instance().get(name);
}
set_formatter设置格式器
由于logger对象构建时，就必须有格式器，因此set_formatter只是更新其格式器。
// 为所有已注册logger对象设置新的格式器formatter
SPDLOG_INLINE void set_formatter(std::unique_ptr<spdlog::formatter> formatter)
{
details::registry::instance().set_formatter(std::move(formatter));
}
set_pattern设置格式串
logger对象需要pattern，利用formatter根据pattern将log消息转换最终期望的log消息格式。便捷全局接口set_pattern，实际上利用set_formatter向logger传递一个pattern_formatter对象。其原理类似于logger::set_pattern实现。不同点在于：logger::set_pattern是针对单个logger对象，而set_pattern是针对所有已注册logger对象。
// 设置全局格式串
SPDLOG_INLINE void set_pattern(std::string pattern, pattern_time_type time_type)
{
set_formatter(std::unique_ptr<spdlog::formatter>(new pattern_formatter(std::move(pattern), time_type)));
}
全局backtrace操作
我们知道registry提供了开启、关闭backtrace（回溯）log消息功能。全局backtrace接口，也只是利用registry单例进行转发。还有一个比较特殊的，那就是如何将回溯栈的log消息转档（dump）？
SPDLOG_INLINE void enable_backtrace(size_t n_messages)
{
details::registry::instance().enable_backtrace(n_messages);
}
SPDLOG_INLINE void disable_backtrace()
{
details::registry::instance().disable_backtrace();
}
转档回溯栈，实际上是通过logger::dump_backtrace对环形队列的每个元素（log消息），调用自定义函数，将其写到指定目标。
// 转档回溯栈
// default_logger_raw()实际上是registry::default_logger_所指logger对象, 全局唯一
SPDLOG_INLINE void dump_backtrace()
{
default_logger_raw()->dump_backtrace();
}
// 转发给私有实现
SPDLOG_INLINE void logger::dump_backtrace()
{
dump_backtrace_();
}
// 转档回溯栈tracer_中的log消息
SPDLOG_INLINE void logger::dump_backtrace_()
{
using details::log_msg;
if (tracer_.enabled())
{
sink_it_(log_msg{name(), level::info, "****************** Backtrace Start ******************"});
// 弹出回溯栈所有元素并回调lambda, 将log消息写入每个sink对应的目标文件
tracer_.foreach_pop([this](const log_msg &msg) { this->sink_it_(msg); });
sink_it_(log_msg{name(), level::info, "****************** Backtrace End ********************"});
}
}
可以看到dump_backtrace_中的关键，是logger::sink_it_以及details::backtracer::foreach_pop。
sink_it_是logger一个私有virtual函数，logger提供了公共实现，将log消息写到所有sink目标上，属于同步操作；子类可以继承，也可以重写，例如子类async_logger也实现了一个版本，不过是将log消息添加到环形队列，然后交给线程池处理。
// logger类对sink_it_的实现, 提供公共实现方式
SPDLOG_INLINE void logger::sink_it_(const details::log_msg &msg)
{
// 将log消息msg写到每个目标sink上
for (auto &sink : sinks_)
{
if (sink->should_log(msg.level))
{
SPDLOG_TRY
{
sink->log(msg);
}
SPDLOG_LOGGER_CATCH(msg.source)
}
}
// 如果msg的flush level满足条件, 就冲刷所有sink
if (should_flush_(msg))
{
flush_();
}
}
// 子类async_logger的sink_it, 为异步写log消息提供实现
// send the log message to the thread pool
SPDLOG_INLINE void spdlog::async_logger::sink_it_(const details::log_msg &msg)
{
if (auto pool_ptr = thread_pool_.lock())
{
// post log消息到环形队列, 交给线程池处理
pool_ptr->post_log(shared_from_this(), msg, overflow_policy_);
}
else // 线程池thread_pool_ 已经释放
{
throw_spdlog_ex("async log: thread pool doesn't exist anymore");
}
}
foreach_pop是通过不断从环形队列头弹出元素（log消息），然后作为fun的参数进行回调的。该操作会清空回溯栈内容。
// pop all items in the q and apply the given fun on each of them.
SPDLOG_INLINE void backtracer::foreach_pop(std::function<void(const details::log_msg &)> fun)
{
std::lock_guard<std::mutex> lock{mutex_};
// 从环形队列头循环取出元素并回调fun
while (!messages_.empty())
{
auto &front_msg = messages_.front();
fun(front_msg);
messages_.pop_front();
}
}
全局level操作
个人认为spdlog关于日志等级的操作，并不是对称的，不知出于何种原因，get_level()取的是default logger的level，而set_level()却设置的是global_level，并且影响所有已注册的logger。
// get_level返回的是default logger的log level
// Get global logging level
SPDLOG_INLINE level::level_enum get_level()
{
return default_logger_raw()->level();
}
SPDLOG_INLINE spdlog::logger *default_logger_raw()
{
return details::registry::instance().get_default_raw();
}
// get_default_raw 返回default_logger_的raw pointer
SPDLOG_INLINE logger *registry::get_default_raw()
{
return default_logger_.get();
}
set_level()实现：
SPDLOG_INLINE void set_level(level::level_enum log_level)
{
details::registry::instance().set_level(log_level);
}
// registry::set_level 设置全局log level, 影响所有已注册logger
SPDLOG_INLINE void registry::set_level(level::level_enum log_level)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
for (auto &l : loggers_)
{
l.second->set_level(log_level);
}
global_log_level_ = log_level;
}
flush_on()类似于set_level，设置的是flush_level_，并且影响所有已注册logger的flush level。
SPDLOG_INLINE void flush_on(level::level_enum log_level)
{
details::registry::instance().flush_on(log_level);
}
// registry::flush_on 设置全局flush level, 影响所有已注册logger
SPDLOG_INLINE void registry::flush_on(level::level_enum log_level)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
for (auto &l : loggers_)
{
l.second->flush_on(log_level);
}
flush_level_ = log_level;
}
// Get global logging level
SPDLOG_API level::level_enum get_level();
// Set global logging level
SPDLOG_API void set_level(level::level_enum log_level);
// Determine whether the default logger should log messages with a certain level
SPDLOG_API bool should_log(level::level_enum lvl);
// Set global flush level
SPDLOG_API void flush_on(level::level_enum log_level);
flush_every定时冲刷
利用registry::flush_every 启动一个全局定时器，定时冲刷log消息到目标。
// 全局接口, 定时flush所有已注册logger, 时间间隔interval由调用者决定
template<typename Rep, typename Period>
inline void flush_every(std::chrono::duration<Rep, Period> interval)
{
details::registry::instance().flush_every(interval);
}
template<typename Rep, typename Period>
void registry::flush_every(std::chrono::duration<Rep, Period> interval)
{
std::lock_guard<std::mutex> lock(flusher_mutex_);
auto clbk = [this]() { this->flush_all(); }; // 子线程循环定时回调的匿名函数
periodic_flusher_ = details::make_unique<periodic_worker>(clbk, interval);
}
drop清除logger
- 清除指定logger name的logger对象
要清除的logger对象，分两种情况：1）属于已注册的logger对象；2）默认的logger对象（default logger）。
如果是第1）种情况，就从map中删除；如果是第2）种情况，就释放所指对象。
// 根据logger name 清除logger对象
SPDLOG_INLINE void registry::drop(const std::string &logger_name)
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
loggers_.erase(logger_name); // 从map中擦除logger
if (default_logger_ && default_logger_->name() == logger_name)
{
default_logger_.reset();
}
}
- 清除所有logger对象
清除所有logger对象：已经注册的logger对象 + 默认的logger对象。
// 清除所有logger对象
SPDLOG_INLINE void registry::drop_all()
{
std::lock_guard<std::mutex> lock(logger_map_mutex_);
loggers_.clear();
default_logger_.reset();
}
关闭log功能
如果用户想手动关闭spdlog的日志记录功能（log功能），释放相关资源，该怎么办？
可以调用shutdown()。registry关闭log功能，有三类资源：
1）periodic_flusher_开启了一个子线程，因此需要手动释放；
2）已注册logger对象+默认的logger对象，需要调用drop_all()释放；
3）用于异步写log的线程池资源，需要手动释放；
// 清除所有资源以及关闭registry启动的线程
SPDLOG_INLINE void shutdown()
{
details::registry::instance().shutdown();
}
// clean all resources and threads started by the registry
SPDLOG_INLINE void registry::shutdown()
{
{
std::lock_guard<std::mutex> lock(flusher_mutex_);
periodic_flusher_.reset();
}
drop_all();
{
std::lock_guard<std::recursive_mutex> lock(tp_mutex_);
tp_.reset();
}
}
设置自动注册
如果用户想控制新建的logger对象，调用initialize_logger()后，是否自动添加进全局注册表，可以通过set_automatic_registration()来设置。
// Automatic registration of loggers when using spdlog::create() or spdlog::create_async
SPDLOG_INLINE void set_automatic_registration(bool automatic_registration)
{
details::registry::instance().set_automatic_registration(automatic_registration);
}
默认logger
- 获取共享指针管理的logger
用户可以直接通过全局default_logger()接口，获取单例registry的default_logger对象。其实现也是转发给registry::default_logger()
// get shared_ptr of default logger
SPDLOG_INLINE std::shared_ptr<spdlog::logger> default_logger()
{
return details::registry::instance().default_logger();
}
- 获取logger对象原生指针
转发给registry::get_default_raw()。
// get raw pointer of default logger
SPDLOG_INLINE spdlog::logger *default_logger_raw()
{
return details::registry::instance().get_default_raw();
}
- 设置默认logger
转发给registry::set_default_logger()。
SPDLOG_INLINE void set_default_logger(std::shared_ptr<spdlog::logger> default_logger)
{
details::registry::instance().set_default_logger(std::move(default_logger));
}
写log
既然能通过default_logger(), default_logger_raw()获取default logger，那么用户如何方便地写日志内容呢？
可以通过spdlog.h中定义的一组便捷接口，使用默认的logger写log。
- log()写日志版本
spdlog实现了2个重载函数模板log：第一个支持调用者指定源文件；第二个源文件为空。
// 写log便捷接口, 重载函数模板
// 支持源文件的log版本
// 要写的正文内容是格式串形式
template<typename... Args>
inline void log(source_loc source, level::level_enum lvl, format_string_t<Args...> fmt, Args &&... args)
{
default_logger_raw()->log(source, lvl, fmt, std::forward<Args>(args)...);
}
// 源文件为空的log版本
// 要写的正文内容是格式串形式
template<typename... Args>
inline void log(level::level_enum lvl, format_string_t<Args...> fmt, Args &&... args)
{
default_logger_raw()->log(source_loc{}, lvl, fmt, std::forward<Args>(args)...);
}
// 源文件由调用者指定
// 要写正文msg的类型T是模板参数, 如果T不能转换为format string(包括string_view/wstring_view), 就直接将msg当做string
template<typename T>
inline void log(source_loc source, level::level_enum lvl, const T &msg)
{
default_logger_raw()->log(source, lvl, msg);
}
// 源文件为空
// 要写正文msg的类型T是模板参数, 通常要求T可转换为format string(string_view/wstring_view)
template<typename T>
inline void log(level::level_enum lvl, const T &msg)
{
default_logger_raw()->log(lvl, msg);
}
- 使用固定log level写日志
如果用户想要写log的level固定，还有使用更简便的一组接口，实现也是转发给logger类对应的接口。
// 一组全局的固定log level的写log接口
template<typename... Args>
inline void trace(format_string_t<Args...> fmt, Args &&... args)
{
default_logger_raw()->trace(fmt, std::forward<Args>(args)...);
}
template<typename... Args>
inline void debug(format_string_t<Args...> fmt, Args &&... args)
{
default_logger_raw()->debug(fmt, std::forward<Args>(args)...);
}
template<typename... Args>
inline void info(format_string_t<Args...> fmt, Args &&... args)
{
default_logger_raw()->info(fmt, std::forward<Args>(args)...);
}
template<typename... Args>
inline void warn(format_string_t<Args...> fmt, Args &&... args)
{
default_logger_raw()->warn(fmt, std::forward<Args>(args)...);
}
template<typename... Args>
inline void error(format_string_t<Args...> fmt, Args &&... args)
{
default_logger_raw()->error(fmt, std::forward<Args>(args)...);
}
template<typename... Args>
inline void critical(format_string_t<Args...> fmt, Args &&... args)
{
default_logger_raw()->critical(fmt, std::forward<Args>(args)...);
}
// 要写的正文内容msg类型T, 通常要求T可转换为format string(string_view/wstring_view)
template<typename T>
inline void trace(const T &msg)
{
default_logger_raw()->trace(msg);
}
template<typename T>
inline void debug(const T &msg)
{
default_logger_raw()->debug(msg);
}
template<typename T>
inline void info(const T &msg)
{
default_logger_raw()->info(msg);
}
template<typename T>
inline void warn(const T &msg)
{
default_logger_raw()->warn(msg);
}
template<typename T>
inline void error(const T &msg)
{
default_logger_raw()->error(msg);
}
template<typename T>
inline void critical(const T &msg)
{
default_logger_raw()->critical(msg);
}
知识点
std::enable_if, is_convertible_to_any_format_string
两个重要元函数std::enable_if, is_convertible_to_any_format_string
logger有一个非常重要的实现logger::log()，用到了2个元函数：std::enable_if和自定义is_convertible_to_any_format_string。
// T cannot be statically converted to format string (including string_view/wstring_view)
template<class T, typename std::enable_if<!is_convertible_to_any_format_string<const T &>::value, int>::type = 0>
void logger::log(source_loc loc, level::level_enum lvl, const T &msg)
{
log(loc, lvl, "{}", msg);
}
std::enable_if作用是满足条件（第一个模板参数）时类型（第二个参数）有效。可能实现如下，当模板参数B为true时，可以通过::type得到T的类型；否则，就没有定义::type，无法通过::type得到T的类型。如果B为false，程序通过::type获取T的类型时，就会编译报错。
// 通用版本
template<bool B, class T = void>
struct enable_if {};
// 偏特化版本
template<class T>
struct enable_if<true, T> { using type = T; };
// enable_if_t定义
template< bool B, class T = void >
using enable_if_t = typename enable_if<B,T>::type;
is_convertible_to_any_format_string 是通过std::is_convertible判断T是否能转化成string_view_t或者wstring_view_t，::value取回结果（true/false），实现如下：
// 如果T类型能转化成format string, 那么::value/::value_type()/::operator()就会得到true;
// 否则, 得到false
// format string是指:
// 1) fmt::basic_string_view<char>, 即std::string_view_t的实现
// 2) fmt::basic_string_view<wchar_t>, 即std::wstring_view_t的实现
template<class T>
struct is_convertible_to_any_format_string : std::integral_constant<bool,
is_convertible_to_basic_format_string<T, char>::value ||
is_convertible_to_basic_format_string<T, wchar_t>::value>
{};
// std::integral_constant
// ::value_type 返回_Ty类型, ::type 返回
template <class _Ty, _Ty _Val>
struct integral_constant {
// 值元函数拥有内嵌变量::value
static constexpr _Ty value = _Val;
// 内嵌类型
using value_type = _Ty;
using type = integral_constant;
// 内嵌函数
constexpr operator value_type() const noexcept {
return value;
}
// _NODISCARD是 [[nodiscard]] 别名, 调用函数处没有获取返回值, 编译器会警告
_NODISCARD constexpr value_type operator()() const noexcept {
return value;
}
};
template <bool _Val>
using bool_constant = integral_constant<bool, _Val>;
using true_type = bool_constant<true>;
using false_type = bool_constant<false>;
// is_convertible_to_basic_format_string 判断类型T是否能转化成类型Char
// 当T可以转换成fmt::basic_string_view<Char>(即std::string_view_t) 或者 将T去掉cv属性(const/volatile)后与fmt::basic_runtime<Char>同类型时, 则能通过::value得到true; 否则, 得到false
// fmt::basic_runtime<Char>的本质是fmt::basic_string_view<Char>
template<class T, class Char = char>
struct is_convertible_to_basic_format_string
: std::integral_constant<bool,
std::is_convertible<T, fmt::basic_string_view<Char>>::value || std::is_same<remove_cvref_t<T>, fmt::basic_runtime<Char>>::value>
{};
// std::is_convertible 判断_From类型是否能转化成_To类型
// 如果能, 那么调用者通过::value返回true; 否则, 返回false
template <class _From, class _To>
struct is_convertible : bool_constant<__is_convertible_to(_From, _To)> {
// determine whether _From is convertible to _To
};
spdlog库系列：spdlog库笔记汇总
