log4cpp源码阅读：Category组件学习
作者：互联网
Category组件在Log4Cpp库中，是真正的Logging对象。我们可以使用category对象来进行各种级别的日志操作，比如debug、warn、info…并且这个对象还可以添加各种appender，用来将日志指令分发给各个appender对象来输出到最终目的地上
Category与Appender对象之间的关系(观察者模式)
category与appender之间是一种目标和观察者关系。也就是说它们之间使用的设计模式就是观察者设计模式：category对象会将具体的debug、warn、info…指令分发给内部添加的append对象。
添加/移除Appender对象
class Category {
private:
typedef std::map<Appender *, bool> OwnsAppenderMap;
AppenderSet _appender; //AppenderSet的具体类型是：typedef std::set<Appender *> AppenderSet;在Appender.hh文件中被定义
OwnsAppenderMap _ownsAppender; // 用来复制实现内部添加的Appender对象能够被安全delet的一个辅助信息
mutable threading::Mutex _appenderSetMutex; //锁：一个辅助数据能够安全访问的手段
public:
virtual void addAppender(Appender* appender);
virtual void addAppender(Appender& appender);
virtual void removeAllAppenders();
virtual void removeAppender(Appender* appender);
virtual bool ownsAppender(Appender* appender) const throw();
}
// 将指定的appender对象，添加到内部的管理容器中，参数无效会抛出std::invalid_argument异常
void Category::addAppender(Appender* appender) {
if (appender) {
threading::ScopedLock lock(_appenderSetMutex);
{
// 首先检测指定的appender是否已经存在了，只有不存在的时候，才会添加，否则肯定什么也不用做
// 因为传过来的是指针，如果相同的话，则说明根本就是同一个东西
AppenderSet::iterator i = _appender.find(appender);
if (_appender.end() == i) {
// not found
_appender.insert(appender); // 执行真正的添加操作
_ownsAppender[appender] = true;
}
}
} else {
throw std::invalid_argument("NULL appender"); // 注意第二个参数设置为true（当category类执行移除操作的时候，你会知道执行他的用意）
}
}
// 另一重载的appender方法
// 执行的逻辑和addAppender(Appender*)版本基本类似，因为appender是引用，那么他肯定是已经存在的对象，所以不用进行空值检测
// 并且也是在已经存在列表中进行查找，如果不存在的话，他才会添加新的内容
// 唯一不一样的是（这儿需要注意）：当发现appender是还没有添加的appender的时候，除了将appender插入到_appender容易中，还
// _ownsAppender[&appender] = false; 注意这儿设置为false, 而上面那个版本设置为true
void Category::addAppender(Appender& appender) {
threading::ScopedLock lock(_appenderSetMutex);
{
AppenderSet::iterator i = _appender.find(&appender);
if (_appender.end() == i) {
_appender.insert(&appender);
_ownsAppender[&appender] = false;
}
}
}
void Category::removeAllAppenders() {
threading::ScopedLock lock(_appenderSetMutex);
{
for (AppenderSet::iterator i = _appender.begin();
i != _appender.end(); i++) {
// found
OwnsAppenderMap::iterator i2;
if (ownsAppender(*i, i2)) {
delete (*i);
}
}
_ownsAppender.clear(); //将两个用来记录appender的信息的容器中的信息完全删除
_appender.clear();
}
}
// 将当前appender从Category移除
void Category::removeAppender(Appender* appender) {
threading::ScopedLock lock(_appenderSetMutex);
{
AppenderSet::iterator i = _appender.find(appender); //首先进行查找
if (_appender.end() != i) {
OwnsAppenderMap::iterator i2;
// 用来检测当前category对象，是否完全属于appender
// 如果是的话，会将这个appender完全delete掉，然后也会将_ownsAppender中这个map对象的存在也移除掉
if (ownsAppender(*i, i2)) {
_ownsAppender.erase(i2);
delete (*i);
}
_appender.erase(i); // 不管是否属于肯定会将这个对象从_appender中移除掉
} else {
// appender not found
}
}
}
// 检测当前category对象是否完全拥有appender对象（只要完全拥有它才有权使用delete来删除）
bool Category::ownsAppender(Appender* appender) const throw() {
bool owned = false;
threading::ScopedLock lock(_appenderSetMutex);
{
if (NULL != appender) {
OwnsAppenderMap::const_iterator i =
_ownsAppender.find(appender);
if (_ownsAppender.end() != i) {
owned = (*i).second;
}
}
}
return owned;
}
对于目标注册/反注册观察者的方法，总结如下：
- Category实际上使用AppenderSet _appender，来维护添加进来的Appender对象
- Category还使用OwnsAppenderMap _ownsAppender， 来辅助remove方法能够完全释放掉所有已经添加进来的Appender
- Category中的Appender方法，就是类似于观察者模式中的Subject的register方法，而remove方法就类似于Subject中的Unregister方法，可以看到Category完全就是充当一个subject的角色
callAppenders方法(观察者模式中的通知方法)
void Category::callAppenders(const LoggingEvent& event) throw() {
threading::ScopedLock lock(_appenderSetMutex);
{
// 挨个遍历每一个Appender对象，调用appender对象的doAppend方法
if (!_appender.empty()) {
for(AppenderSet::const_iterator i = _appender.begin();
i != _appender.end(); i++) {
(*i)->doAppend(event);
}
}
}
// 下面的代码，你可以暂时不用看，等学完Category的自身结构的时候就明白了
if (getAdditivity() && (getParent() != NULL)) {
getParent()->callAppenders(event);
}
}
我们可以看到，Category::callAppender方法就类似于观察者模式中的Subject的notify方法，而Appender::doAppend方法就类似于观察者模式中的Observer的receive方法。
Category自身的结构（责任链模式）
源码
class Category {
protected:
// 唯一一个可以被子类或者友元调用的构造器
// name是当前category对象的名称
// parent 最后会被设置到_parent属性中（他是我们目前为止唯一需要关心）
// priority 表示这个日志能够处理的最低优先级，如果低于这个优先级的日志操作是不会真正进行的
Category(const std::string& name, Category* parent,
Priority::Value priority = Priority::NOTSET);
private:
Category(const Category& other); //禁止拷贝和赋值
Category& operator=(const Category& other);
Category* _parent; // 执行父category
const std::string _name; //代表category对象的名称
volatile Priority::Value _priority; //代码这个对象所能处理日志的操作的最低优先级
volatile bool _isAdditive; //这个属性，我们暂时不用考虑
}
Category::Category(const std::string& name, Category* parent, Priority::Value priority) :
_name(name),
_parent(parent),
_priority(priority),
_isAdditive(true) {
}
从上面可以看出，Category是一种链式的结果，一个Category对象，还可以指向一个父Category对象，然后父Category对象还可以拥有它自己的父Category，以此类推，可以形成一条很长的Category链。
还可以看到，Category拥有一个唯一的构造器，而且这个构造器是protected的。那么我们怎么实例化它呢？难道我们要继承这个Category类吗？其实Category对象还提供了几个工厂方法。
我们先不要想这些工厂方法，我们先来看一看Category的属性：
- name就是Category类型的名称
- _priority，本质上是一个int类型，Category类的具体日志操作时使用
- _isAdditive，我们来具体看一看。因为我们讲到Category::callAppends方法的时候，里面有一段 代码没有讲，现在我们已经完成了所有必要的基础了，我们回过头来看一下：
void Category::callAppenders(const LoggingEvent& event) throw() {
threading::ScopedLock lock(_appenderSetMutex);
{
// 挨个遍历每一个Appender对象，调用appender对象的doAppend方法
。。。。。。
}
// getAdditivity()就是_isAdditivity属性的访问方法，
// getParent()获取的是_parent属性
// 我们可以看到下面的逻辑是，如果_isAdditivity==true，则会调用
// 父亲的callAppenders方法，但是父亲也是一个Category对象啊，他仍然会
// 调用自己已经添加Appender对象的doAppend方法，然后检测自己的_isAdditivity,来决定是否将这个LoggingEvent
// 继续向上传送处理
if (getAdditivity() && (getParent() != NULL)) {
getParent()->callAppenders(event);
}
}
从这里我们可以看到，其实Category类，还用到了责任链模式：在构造的时候，它会将父Category对象传进来，当执行callAppenders方法的时候，它可以根据_isAdditivity属性的设置情况将event传递给它的父category对象。
到此整个Category的观察者模式部分已经彻底讲解完毕。
Category的工厂方法（工厂方法）
我们先来看下Category::getRoot方法，和Category::getInstance方法的源码
Category& Category::getRoot() {
return getInstance("");
}
Category& Category::getInstance(const std::string& name) {
return HierarchyMaintainer::getDefaultMaintainer().getInstance(name);
}
我们可以看到getRoot静态方法内部调用的是getInstance静态方法，而getInstance静态方法内部调用的是 HierarchyMaintainer::getDefaultMaintainer().getInstance(name)
又：
class Category {
friend class HierarchyMaintainer;
。。。
};
即HierarchyMaintainer是Category的友元类，我们再想到，Category提供了一个唯一实现的构造方法，这个构造方法是protected的。可以推测出，HierarchyMaintainer是Category的工厂类。
HierarchyMaintainer
Category的工厂类，内部负责所有Category对象的构造操作。
我们先来看一下它的数据成员
class HierarchyMaintainer {
public:
typedef std::map<std::string, Category*> CategoryMap;
protected:
CategoryMap _categoryMap;
}
内部包含了一个成员_categoryMap。HierarchyMaintainer 内部创建的Category对象都会保存在_categoryMap容器中，都是通过Category::getInstance方法内部调用的。
下面以HierarchyMaintainer::getDefaultMaintainer().getInstance(name);为引，来看一下整个HierarchyMaintainer类的功能
HierarchyMaintainer::getDefaultMaintainer()方法(一种单例工厂方法的一种实现方式)
class HierarchyMaintainer {
public:
static HierarchyMaintainer& getDefaultMaintainer();
}
// 这个方法是静态的
// 当这个方法第一次被调用的时候，defaultMaintainer会被构造，然后将之返回
// 当下次这个方法被调用时，会直接将此静态对象返回
// 这是单例模式的一种典型实现方式
HierarchyMaintainer& HierarchyMaintainer::getDefaultMaintainer() {
static HierarchyMaintainer defaultMaintainer;
return defaultMaintainer;
}
可以看到，getDefaultMaintainer()其实是HierarchyMaintainer类的一个单例工厂方法。所以HierarchyMaintainer::getDefaultMaintainer().getInstance(name); 内部真正getInstance方法就是HierarchyMaintainer::getInstance方法
HierarchyMaintainer::getInstance方法
class HierarchyMaintainer {
public:
virtual Category& getInstance(const std::string& name);
}
Category& HierarchyMaintainer::getInstance(const std::string& name) {
threading::ScopedLock lock(_categoryMutex); // 确保getInstance()能够多线程安全的访问
return _getInstance(name); //真正的调用的是_getInstance方法
}
这个方法其实是一个包装方法，它是线程安全的，内部调用的是_getInstance方法。
class HierarchyMaintainer {
protected:
virtual Category* _getExistingInstance(const std::string& name);
virtual Category& _getInstance(const std::string& name);
}
Category* HierarchyMaintainer::_getExistingInstance(const std::string& name) {
Category* result = NULL;
CategoryMap::iterator i = _categoryMap.find(name);
if (_categoryMap.end() != i) {
result = (*i).second;
}
return result;
}
Category& HierarchyMaintainer::_getInstance(const std::string& name) {
Category* result;
// 就是就是检测指定name名称的Cateogory对象是否已经被创建，如果创建好的则将之返回（就是利用利用_categoryMap的find方法）
result = _getExistingInstance(name);
if (NULL == result) { // 指定名称的category对象还没有被创建，需要创建一个
// name为""，说明创建的是root
if (name == "") {
// 第二个参数为NULL，表示没有父category指针（根没有父category）
// 即Category::getRoot方法实现是：HierarchyMaintainer::getDefaultMainter().getInstance("");
result = new Category(name, NULL, Priority::INFO);
} else {
// name的格式可以包含多个点：
// 比如 parentparent.parent.son.sonson
std::string parentName;
size_t dotIndex = name.find_last_of('.'); //首先查找的最后一个.的位置
if (name.length() <= dotIndex) { // 这儿为什么是小于等于呢？是因为当name没有找到'.'的时候返回的是std::size_t(-1)
parentName = ""; // 这个值是size_t即unsigned int（是无符号）中最大的值，没有比他再大了
} else {
parentName = name.substr(0, dotIndex); //不包最后点的名称。比方name是parentparent.parent.son.sonson，那么这儿parentName就是parentparent.parent.son
}
Category& parent = _getInstance(parentName); // 递归调用，相当于先创建父category
result = new Category(name, &parent, Priority::NOTSET); // 然后使用创建号的父category来创建子category
}
_categoryMap[name] = result; //最终创建号的category对象，会保存到_categoryMap属性中，以category对象的name为key
}
return *result;
}
这个方法是整个工厂方法的核心所在，主要执行如下流程：
- 检测name是否已经创建号了，如果创建号了，则将之返回
- 检测name是否为空，如果是，那么创建一个根节点（有一个细节，根节点的priority属性默认设置为Priority::INFO），并且将这个新建的节点保存到_categoryMap属性中
- 3.如果name不为空，那么他首先先递归调用_getInstance方法获取 name名称所指定的父节点（比如name是parent.son，那么他会使用 _getInstance(“parent”)来创建父节点），然后使用创建号的父category对象来新建一个子category，也就是指定name的category对象。(这儿 也有一个细节，非根节点的priority属性设置为Priority::NOTSET)，并且将之添加到_categoryMap中(以name为key，以新建的category指针为值)
- 上面递归调用中，比如name=parent.son，那么它会调用_getInstance(“parent”)，然后这个方法内部 又会调用_getInstance("")，此方法返回根节点记为root，然后继续回到_getInstance(“parent”)中，新建一个Category(“parent”, root, Priority::NOTSET)，假设为p，然后将这个对象返回，继续回到_getInstane(“parent.son”)来执行，则会返回Category(“parent.son”, p, Priority:NOTSET)
根据这个_getInstance方法的实现我们可以知道：
- 首先指定的name可以包含几个’.’
- 根Category对象的默认_priority属性是Priority::INFO，其他的非根Category对象的_priority属性Priority::NOTSET属性。
- 所有创建好的Category对象，都被备份到HieratchyMaintainer的_categoryMap属性中
HierarchyMaintainer::~HierarchyMaintainer的析构方法
class HierarchyMaintainer {
public:
virtual ~HierarchyMaintainer();
}
HierarchyMaintainer::~HierarchyMaintainer() {
shutdown();
deleteAllCategories();
}
我们可以看到执行了shutdown()方法和deleteAllCategories()方法。
HierarchyMaintainer::shutdown方法
下面我们看一下shutdown()方法，但是在看这个方法之前，我们要看一下准备：
class HierarchyMaintainer {
public:
typedef void (*shutdown_fun_ptr)(); //定义了一种不带参数没有返回值的函数指针类型，其实就是一种类型回调函数
void register_shutdown_handler(shutdown_fun_ptr handler); //注册指定回调函数到handlers中
private:
typedef std::vector<shutdown_fun_ptr> handlers_t; //用来保存函数指针的容器类型
handlers_t handlers_;
}
//注册指定回调函数到handlers中
void HierarchyMaintainer::register_shutdown_handler(shutdown_fun_ptr handler)
{
handlers_.push_back(handler);
}
即HierarchyMaintainer体供了可以用来扩展的回调函数，至于这些回调函数的具体功能，我们需要看一下这个类的shutdown方法。
class HierarchyMaintainer {
public:
virtual void shutdown();
}
void HierarchyMaintainer::shutdown() {
threading::ScopedLock lock(_categoryMutex); //保证此方法是线程安全的
{
// 清除所有的已经实例化好的Category对象内部的Appender对象（通过调用Category的removeAllAppenders方法来实现，这个方法我们前面已经讨论过）
for(CategoryMap::const_iterator i = _categoryMap.begin(); i != _categoryMap.end(); i++) {
((*i).second)->removeAllAppenders();
}
}
// 调用使用register_shutdown_handler添加过来的回调函数
// 其实你可以看到，他也是有限制的，因为到有一个回调函数发生以后的时候，那么其他的回调函数都没有机会被执行了
// 不知道，是设置者是有心的还是无心的过失，个人认为可以将这个try ... catch...块添加到for循环的内部
try
{
for(handlers_t::const_iterator i = handlers_.begin(), last = handlers_.end(); i != last; ++i)
(**i)();
}
catch(...)
{
}
}
简单总结一下HierarchyMaintainer::shutdown方法功能：
- 清除所有已经创建号的category对象内部已经添加的appener
- 调用所有已经注册进来的回调函数。需要注意的是：这个回调函数不能发生异常，否则可能终止这个回调函数后面注册进来的回调参数
HierarchyMaintainer::deleteAllCategories方法
class HierarchyMaintainer {
public:
virtual void deleteAllCategories();
}
void HierarchyMaintainer::deleteAllCategories() {
threading::ScopedLock lock(_categoryMutex);
{
for(CategoryMap::const_iterator i = _categoryMap.begin(); i != _categoryMap.end(); i++) {
delete ((*i).second);
}
_categoryMap.clear();
}
}
这个方法非常简单，直接delete掉_categoryMap内部的所有的成员，这样就不会发生内存泄露了
上面介绍的getInstance()方法和析构方法是整个类的核心功能所在，即用来创建Category对象，和用来维护已经创建好的Category对象。
小结：
- HierarchyMaintainer方法的工厂方法getInstance()和对每个category对象进行清理的shutdown()方法，和释放内部所有已经创建好的category对象的deleteAllCategories()方法，它们都是线程安全的
- 当HierarchyMaintainer对象被销毁的时候，它会自动调用shutdown()方法和deleteAllCategories()方法。，所以说，对于 整个程序来即使程序最后没有调用Category::shutdown()方法，也不会发生任何资源资料的。这就是说，这个工厂类来负责维护所有已经创建号的category对象的生命周期。
- 3.对于使用getInstance方法创建的含有父亲的category对象，他们的名称是包含有点的名称，而不是最后点号后面的名称，我们可以从 getInstance()中来寻找到原因。
其他方法：
// 是否存在name对象的category
Category* HierarchyMaintainer::getExistingInstance(const std::string& name) {
threading::ScopedLock lock(_categoryMutex);
return _getExistingInstance(name);
}
// 当前已经创建的所有category
std::vector<Category*>* HierarchyMaintainer::getCurrentCategories() const {
std::vector<Category*>* categories = new std::vector<Category*>;
threading::ScopedLock lock(_categoryMutex);
{
for(CategoryMap::const_iterator i = _categoryMap.begin(); i != _categoryMap.end(); i++) {
categories->push_back((*i).second);
}
}
return categories;
}
Category::shutdown()
Category的资源回收方法
class Category {
public:
static void shutdown();
}
void Category::shutdown() {
HierarchyMaintainer::getDefaultMaintainer().shutdown();
}
Category对象的shutdown方法，内部实际上调用的是上一节中介绍的HierarchyMaintainer.shutdown方法。内部执行步骤可以简单回忆一下：
- 调用所有category的removeAllAppenders方法，来delete掉所有拥有的Appender对象，并且清空category对象内部的_appender容器中的内容，和ownsAppender容器中的内容、
- 调用HierarchyMaintainer内部注册进的回调函数。（其实对于这一步，通过阅读Category的整个实现，他并没有注册任何回调函数，也就是 说，这个拓展清理机制，在实际使用中并没有被用到。）
- 补充：所有创建的的category对象，其实并没有被销毁。它的销毁时机是HierarchyMaintainer::getDefaultMaintainer()方法内部定义的static变量被销毁的时候。这里只是销毁了所有被category对象完全拥有的Appender。
看一下Category对象的析构方法：
class Category {
public:
~Category();
......
};
~Category::Category() {removeAllAppenders();}
就是移除内部所有的Appender对象。存在这个方法，单独上来考虑是合理的，但是因为Category对象的生命周期是完全由HierachyMaintainer对象 来维护的，而在HierachyMaintainer的shutdown方法中，拥有此方法的功能，在HierachyMaintainer的析构方法中，也有此功能，所以我认为， 要么这个类的析构方法中不做任何处理，要么将就HierachyMaintainer::shutdown方法，不要提供调用每一个category对象的removeAllAppenders这个流程。 我认为前者更合理，就是不在Category的析构方法中进行任何处理。
Category的日志方法
Category可以用来输出各种不同的日志，并且也处理了一种需求，比如某些情况下，我想输出各种类型的信息，包括错误信息、普通信息、调试信息，但是某些情况下，我们只想看到错误信息。category使用了Prority::Value _priority属性来实现。
Priority这个类，其内部有一个PriorityLevel枚举类型，内部定义了各种枚举常量，定义了一个typedef int Value; 还定义了两工具函数，一个是getPriorityName，可以将Value类型转换为字符串类型，比如getPriorityName(Priority::DEBUG)返回"DEBUG"，一个是 getPriorityValue，将字符串转换为Value，比如getPriorityValue(“DEBUG”) 则输出为Priority::DEBUG，这个方法字符串还可以是数字，比如 getPriorityValue(“123”)则返回则为123，一般不这样使用。
用来确定某种日志级别的操作是否执行的辅助方法是isPriorityEnabled，源码如下：
bool Category::isPriorityEnabled(Priority::Value priority) const throw() {
return(getChainedPriority() >= priority); // 只有当设置的_priority值大于指定priority值的时候才会返回true
}
// 上面getChainedPriority方法的实现
Priority::Value Category::getChainedPriority() const throw() {
// REQUIRE(rootCategory->getPriority() != Priority::NOTSET) ，这儿的条件肯定是成立的，
//因为root对象使用HierachyMaintainer::getInstance("")，内部当name为空，他创建的root的priority值为Priority::INFO
//所以只要不人为将root Category的priority设置为Priority::NOTSET，下面的程序就不会crush
// 子 -> 父 -> 父。。。查找到第一个_priority属性不是设置为Priority::NOTSET，因为root的默认_priority为Priority::INFO
// 这个循环是肯定能够终止的。
const Category* c = this;
while(c->getPriority() >= Priority::NOTSET) {
c = c->getParent();
}
return c->getPriority();
}
void Category::setPriority(Priority::Value priority) {
if ((priority < Priority::NOTSET) || (getParent() != NULL)) {
_priority = priority;
} else {
/* caller tried to set NOTSET priority to root Category.
Bad caller!
*/
throw std::invalid_argument("cannot set priority NOTSET on Root Category");
}
}
正如我们可以看到，当内部设置的_priority的值大于指定的priority值的时候，那么表示进行的操作都是满足的。
下面我们来看一下一个具体的记录日志方法，我们选择的是debug方法，对于其他的info, alert, warn。。。他们的组成都是相同的。我们可以看一下他们的 类似结构：
class Category {
public:
void debug(const char* stringFormat, ...) throw();
void debug(const std::string& message) throw();
inline bool isDebugEnabled() const throw() {
return isPriorityEnabled(Priority::DEBUG);
};
inline CategoryStream debugStream() {
return getStream(Priority::DEBUG);
}
}
class Category {
public:
void info(const char* stringFormat, ...) throw();
void info(const std::string& message) throw();
inline bool isInfoEnabled() const throw() {
return isPriorityEnabled(Priority::INFO);
};
inline CategoryStream infoStream() {
return getStream(Priority::INFO);
}
}
class Category {
public:
void notice(const char* stringFormat, ...) throw();
void notice(const std::string& message) throw();
inline bool isNoticeEnabled() const throw() {
return isPriorityEnabled(Priority::NOTICE);
};
inline CategoryStream noticeStream() {
return getStream(Priority::NOTICE);
}
}
。。。。
下面仅以debug方面的方法来进行系统介绍。
void debug(const char* stringFormat, …)
void Category::debug(const char* stringFormat, ...) throw() {
// 首先检测权限
if (isPriorityEnabled(Priority::DEBUG)) {
va_list va;
va_start(va,stringFormat);
_logUnconditionally(Priority::DEBUG, stringFormat, va); //进行真正的日志操作
va_end(va);
}
}
可以看到，这个类会首先检测当前权限是否支持Priority::DEBUG，只要_priorty > Priority::DEBUG就支持。然后初始化可变参数进行真正的日志操作，然后释放可变参数。所以关键就是_logUnconditionally实现。
_logUnconditionally
class Category {
protected:
virtual void _logUnconditionally(Priority::Value priority,
const char* format,
va_list arguments) throw();
}
void Category::_logUnconditionally(Priority::Value priority,
const char* format,
va_list arguments) throw() {
_logUnconditionally2(priority, StringUtil::vform(format, arguments));
}
_logUnconditionally2
class Category {
protected:
virtual void _logUnconditionally2(Priority::Value priority,
const std::string& message) throw();
}
void Category::_logUnconditionally2(Priority::Value priority,
const std::string& message) throw() {
//组装一个日志事件对象：当前category对象的名称；需要写入的消息；当前线程的NDC值，如果没有使用NDC::put放入的话，则返回为空字符串；这个日志操作的等级
LoggingEvent event(getName(), message, NDC::get(), priority);
callAppenders(event);// 将这个日志事件对象调用我们上面介绍的通知接口，将这个对象分发到各个appener中
}
//---------------------
const std::string& Category::getName() const throw() {
return _name;
}
//---------------------
const std::string& NDC::get() {
if (isUsedNDC)
return getNDC()._get();
else
return emptyString;
}
const std::string& NDC::_get() const {
static std::string empty = "";
return (_stack.empty() ? empty : _stack.back().fullMessage);
}
总结一下void debug(const char* stringFormat, …)的执行流程：首先组织可变参数，然后调用_logUnconditionally分发，而_logUnconditionally内部利用StringUtil::vform方法将可变参数转换为字符串，然后调用 _logUnconditionally2方法，此方法内部构建LoggingEvent对象，然后利用我们前面介绍的通知方法callAllAppener方法，将此LoggingEvent对象分发出去。
void Category::debug(const std::string& message) throw()
void Category::debug(const std::string& message) throw() {
// 先检测当前cateogry权限是否支持debug操作
if (isPriorityEnabled(Priority::DEBUG))
_logUnconditionally2(Priority::DEBUG, message); //直接调用_logUnconditionally2来构建LoggingEvent并且将之分发给
//各个appender对象
}
和使用支持格式化字符串和可变参数的版本相比，少了转换为字符串的过程，而是直接调用_logUnconditionally2来进行 组装日志对象和分发日志对象。
debugStream()
class Category {
public:
...
// 获取的是输出debug信息的流对象，此流输出的所有消息都是debug消息
// 我们可以向这样来使用流
// Category &root = Category::getRoot();
// ... 进行一些设置
// CategoryStream debugStream = root.debugStream();
// debugStream << 3 << "is greater than" << 4 << eol;
inline CategoryStream debugStream() {
return getStream(Priority::DEBUG);
}
};
// 内部直接返回一个CategoryStream对象
CategoryStream Category::getStream(Priority::Value priority) {
return CategoryStream(*this, isPriorityEnabled(priority) ?
priority : Priority::NOTSET); //我们暂时先放一放，下面看一下CategoryStream的实现
我们可以看到debugStream返回的是一个CategoryStream的对象，我们可以看一下CategoryStream的实现
CategoryStream
这个类是一个支持流风格的流，但是它们并没有继承任何已有的流对象，它的内部实现是使用聚合一个字符串流来实现的。这个类算是一个输出流，它的输出目标是某个具体的category对象。
我们先来看一下它的数据成员
class CategoryStream {
private:
Category& _category; // 所关联的category对象
Priority::Value _priority; //日志的等级
union {
std::ostringstream* _buffer;
#if LOG4CPP_HAS_WCHAR_T != 0 // 对于这儿的设计我真的是不敢恭维，等到后面看他的算法实现就知道
std::wostringstream* _wbuffer;
#endif
}; // 作为缓冲区
public:
CategoryStream(Category& category, Priority::Value priority);
}
CategoryStream::CategoryStream(Category& category, Priority::Value priority) :
_category(category),
_priority(priority),
_buffer(NULL) {
}
_cateogory就是最后要输出的目的地，_priority是进行输出操作的等级，_buffer是作为CategoryStream的缓存区而存在的。
CategoryStream::operator<<
class CategoryStream {
public:
template<typename T>
CategoryStream& operator<<(const T& t) {
if (getPriority() != Priority::NOTSET) { //只有当从构造器中传来的priority不是Priority::NOTSET的时候，它才会进行真正的日志输出操作。
if (!_buffer) { // 首先要检查输入流缓冲区是否存在，不存在的话就创建，然后将输出输出到这个缓冲区中
if (!(_buffer = new std::ostringstream)) {
// XXX help help help
}
}
(*_buffer) << t;
}
return *this;
}
// 居然还没有这个实现，不是已经有模板成员方法了吗？（实现逻辑和上面的基本一致）
CategoryStream& operator<<(const char* t);
// 这个方法真搞笑，内部根本就没有用到类型T，为什么要在头上加个T（而且函数根本就没有偏特例化这个概念）
// 并且我经过实测，对于vs2013上来讲，这个方法是永远也调用不到，
// 即使我的输出对象是std::string方法，感觉有点误人子弟啊，有木有。我不知道log4cpp对于编译器兼容考虑还是什么原因
// 总之下面的方法根本就不应该存在
template<typename T>
CategoryStream& operator<<(const std::string& t) {
if (getPriority() != Priority::NOTSET) {
if (!_buffer) {
if (!(_buffer = new std::ostringstream)) {
// XXX help help help
}
}
(*_buffer) << t;
}
return *this;
}
// 同上，内部方法永远无法执行，可能vs2013内置C++编译器看到这种写法，就直接将这个模板成员方法给剔除掉了
#if LOG4CPP_HAS_WCHAR_T != 0
template<typename T>
CategoryStream& operator<<(const std::wstring& t) {
if (getPriority() != Priority::NOTSET) {
if (!_wbuffer) {
if (!(_wbuffer = new std::wostringstream)) {
// XXX help help help
}
}
(*_wbuffer) << t;
}
return *this;
}
#endif
}
我们可以看到，第一个目标方法，已经完成了对各种常用类型的流支持，但是它不支持宽字符类型(不相信的朋友可以试一下， 你先传入一个L"123"到oeprator<<是可以编译通过的，但是输出的内容不是你想要的内容，然后你在传入一个wstring(L"123")到operator<< 中，编译器根本就无法编译成功)。到目前为止，它只是将内容输出到内部的_buffer中，并没有将内容输出到内部的category对象。
而且，在CategoryStream& operator<<(const T& t)模板方法中，会检测_priority属性是否为Priority::NOTSET， 只有当_priority不等于Priority::NOTSET的时候，才会将内容输出到缓冲区中，否则是不进行任何操作的。再次申明这里是非常重要的，明白这儿就会明白Category::debugStream()方法的返回的是CategoryStream(isPriorityEnabled(Priority::DEBUG) ? priority : Priority::NOTSET);当权限不支持debug操作时，这个流是无法进行任何输出操作的
CategoryStream::flush方法
class CategoryStream {
public:
void flush();
}
void CategoryStream::flush() {
if (_buffer) { // 缓冲区存在内容的话，他就会将缓冲区的内容通过_category.log方法输出到_category中
getCategory().log(getPriority(), _buffer->str()); //getCategory()获取的就是通过构造器传进来的_category对象
delete _buffer;
_buffer = NULL;
}
}
我们可以看到，categoryStream的flush操作，就是将缓冲区的内容通过_category.log方法输出到_categroy对象中。其实Cateogory::log方法 和我们上面介绍的debug方法功能是类似的，debug方法只能输出Priority::DEBUG权限的消息，而logg方法则比debug方法都一个功能，那么就是它可以指定一个输出权限。
我们来看一下category::log方法的实现
// 多了一个参数，用来设置输出权限等级，内部实现和debug的内部实现基本一致
void Category::log(Priority::Value priority,
const std::string& message) throw() {
if (isPriorityEnabled(priority))
_logUnconditionally2(priority, message);
}
CategoryStream流控制函数的支持
到目前为止，已经讲述了CategoryStream的数据成员，构造函数，以及operator<<和flush，另外Category还为我们提供了几个 流控制符函数，通过这些函数，我们可以知道向std::cout << std::endl, std::cout << std::flush，实现类似这种风格的 原理，我们来看一下这几个函数。
class CategoryStream {
public:
typedef CategoryStream& (*cspf) (CategoryStream&); //定义了一种函数类型
CategoryStream& operator << (cspf); //关键是这个方法，他让我们支持categoryStream << eol; 这样的写法
std::streamsize width(std::streamsize wide ); // 用来设置每次流输出的宽度，内部是调用的_buffer->width方法来实现的
// 声明了两个友元函数
friend CategoryStream& eol (CategoryStream& os);
friend CategoryStream& left (CategoryStream& os);
}
// 内部直接就是将CategoryStream对象交给pf处理，并且返回其值
CategoryStream& CategoryStream::operator<< (cspf pf) {
return (*pf)(*this);
}
// 执行的功能等价于std::flush，会刷新缓冲区中的内容到Category对象中
CategoryStream& eol (CategoryStream& os) {
if (os._buffer) { //缓冲区中有内容则要缓冲区内容进行刷出
os.flush();
}
return os;
}
// 用来设置缓冲区的对齐方式，内部就是通过std::ostringstream的setf标志来实现
// 当指定的宽度大于实际输出值的宽度的时候，他会自动将内容对齐到左面，右边会留空的
CategoryStream& left (CategoryStream& os) {
if (os._buffer) {
os._buffer->setf(std::ios::left);
}
return os;
}
// 用来设置每次流输出的宽度，内部是调用的_buffer->width方法来实现的
std::streamsize CategoryStream::width(std::streamsize wide ) {
if (getPriority() != Priority::NOTSET) {
if (!_buffer) {
if (!(_buffer = new std::ostringstream)) {
// XXX help help help
}
}
}
return _buffer->width(wide);
}
好了到目前为止，CategoryStream的流控制相关方法，只剩下两个get方法，只是用来获取内部属性，在此就不在啰嗦了。
现在回过头来再看一下Category:;getStream方法实现的getStream()。
CategoryStream Category::getStream(Priority::Value priority) {
return CategoryStream(*this, isPriorityEnabled(priority) ? priority : Priority::NOTSET); //关键就是第二个参数的设置，当priority不在category对象的权限范围内的时候，他会将第二个参数设置为Priority::NOTSET
}
正如我们源码注释讲的那样，当priority不被当前Category对象支持的时候，他会将新建的CategoryStream的_priority属性设置为 Priority::NOTSET，原因，前面在介绍CategoryStream::operator<<(const T&)这个方法时候已经介绍过，这儿再次重复一下：
template<typename T>
CategoryStream& CategoryStream::operator<<(const T& t) {
// 只有当从构造器中传过来的priority不是Priority::NOTSET的时候，它才会进行真正的日志输出操作
if (getPriority() != Priority::NOTSET) {
if (!_buffer) {
if (!(_buffer = new std::ostringstream)) {
// XXX help help help
}
}
(*_buffer) << t;
}
return *this;
}
只有当CategoryStream的_priority属性不是Priority::NOTSET的时候，它才会将输出流中的内容输出到缓冲区中，否则它是什么也不干的。也就是说上面的getStream(Priority::Value priority)对象返回的流有两种，一种是可以进行正常输出的流，一种是不能进行正常输出的流。
总结
- 首先我们讲解了category和appener之间的关系，这里采用了观察者设计模式，并且介绍了相应的注册/反注册方法( addAppender(Appender*), addAppender(Appender&))，和对应的通知方法(callAppenders)。
- 对于添加方法，它内部使用了两个容器来维护内部添加进来的Appender对象，一个AppenderSet _appender用来保存所有添加进来的Appender对象，一个_ownsAppender用来记录某个对象是否被完全拥有。当删除某个Appender对象，获取移除所有Appender对象的时候，，_ownsAppender可以用来 检测某个Apepnder是否能够使用delete运算符来删除掉。
- callAppenders调用每个Appender对象的doAppend方法来讲LoggingEvent对象通知给它们，并且根据_additivity属性来决定是否将此事件传递给它的父类。
- 然后我们分析了Category的结构。Category有一个成员Category *_parent，这个参数是通过构造函数传递进来的。另外，在callAppends方法中，除了通知所有已添加的Appender对象，还会根据_additvity的值来决定是否调用_parent.callAllAppenders方法，父类同样此逻辑。这是典型的责任链模式。
- 再之后我们学习了Category对象的工程方法getRoot()方法和getInstance()方法。它们内部其实调用的是HierachyMaintainer的 getInstance方法，然后我们详细介绍了这个HierachyMaintainer类，他实际上就是Category的工厂类，加上维护类，我们通过阅读源码知道， HierachyMaintainer的getInstance的方法首先是线程安全，并且将传递的名称为""，返回的是根Category，当不为空的时候，我们可以 传递xx.xx.xx来创建一个Category对象，HierachyMaintainer工厂方法会自动构建此链上的相关对象并且将最终对象返回，注意返回的对象的名称 仍然是xx.xx.xx，通过读源码，我们会发现，这个工厂类的getInstance()方法是线程安全的。
- 然后我们介绍了Category对象的shutdown方法，这个类内部调用的仍然是HierachyMaintainer类的shutdown方法，在此方法内部执行如下逻辑， 首先调用所有已经创建好的Category对象的removeAllAppenders方法，然后调用内部注册的好多回调函数（当有异常发生，那么后面的回调函数 都不会被执行）。至于这个利用回调函数来进行额外进行某些操作的特性，在整个Category设计中并没有被使用到。还有呢，在HierachyMaintainer 的析构函数中，会先调用shutdown方法，然后调用removeAllCategories方法，前者已经介绍过，后者，内部实现就是delete所有已经实例化的Category 对象，避免内存发生泄漏。
- 对于HierachyMaintainer，这个类实际被Category使用的对象只有一个，Category获取 HierachyMaintainer对象是通过HierachyMaintainer::getDefaultMaintainer方法来实现。这是个HierachyMaintainer类，并没有对构造器 进行私有化，所以我们认为可能HierachyMaintainer是非严格意义上的单例设计，因为他提供了一个单例的工厂方法。
- 下面我们选择某一个具体的日志操作来介绍，我们选择的是debug操作，我们讲解了Category类对于某些级别的检测方法，isPriorityEnabled方法， 内部是检测_priority是否大于函数传进来的优先级。然后我们介绍了debug的几个重载方法，和debugStream方法，debug两个重载方法执行逻辑 都是一致的，当有格式化字符串和可变参数的时候，他们会构造可变参数然后调用_logUnconditionally方法，此方法内部会利用StringUtil::vform 来将格式化字符串和可变参数转换为字符串。然后调用_logUnconditionally2来进行真正的日志操作，此方法会利用一些信息来构建LoggingEvent对象，然后调用我们上面介绍的通知方法callAppenders来讲LoggingEvent对象通知给已经注册进来的所有的Apender对象，并且根据_additivity属性来 确定是否将此事件传递给父Category对象
- 最后我们讲解了debugStream方法的实现，内部调用的是getStream方法，而getStream方法返回的是一个CategoryStream对象，并且根据是否支持对应的priority操作来将它第二个参数设置为Priority::NOTSET。
- 对于CategoryStream，内部其实是聚合了一个std::ostringstream对象，它是将这个对象作为缓冲区，并且提供了一个支持常用类型的模板方法operator<<来实现对于大多数类型的输出流支持，并且对于 这个模板方法，我们也详细说明了那儿在输出之前他会对内部的_priority属性进行判断，如果只为Priority::NOTSET则不进行任何操作。这儿也就是 Category::getStream那个方法那儿里面那样实现的原因。CategoryStream还为我们提供了控制流输出的函数，比如eol, 比如left。总之当我们不想 使用格式化字符串 + 可变参数的时候，可以尝试使用这个方法。
标签：Category,priority,对象,Priority,源码,方法,appender,log4cpp 来源： https://blog.csdn.net/zhizhengguan/article/details/123221348