Boost C++ 库

#include <boost/log/attributes/constant.hpp>

最简单和最常用的属性类型是某种类型的常量值。这种属性类型使用 constant 类模板实现。该模板使用属性值类型进行参数化。常量值应传递给属性构造函数。这是一个例子

void foo()
{
    src::logger lg;

    // Register a constant attribute that always yields value -5
    lg.add_attribute("MyInteger", attrs::constant< int >(-5));

    // Register another constant attribute. Make it a string this time.
    lg.add_attribute("MyString", attrs::constant< std::string >("Hello world!"));

    // There is also a convenience generator function. "MyInteger2" is constant< int > here.
    lg.add_attribute("MyInteger2", attrs::make_constant(10));
}

就是这样，对于常量属性，您能做的并不多。当人们想要突出显示某些日志记录或只是将一些数据传递给 sink 后端（例如，将统计参数传递给收集器）时，常量非常有用。

#include <boost/log/attributes/mutable_constant.hpp>

这种属性是 常量属性 的扩展。mutable_constant 类模板除了能够存储某些值之外，还有两个区别

为了更改属性的存储值，必须调用 set 方法

void foo()
{
    src::logger lg;

    // Register a mutable constant attribute that always yields value -5
    attrs::mutable_constant< int > attr(-5);
    lg.add_attribute("MyInteger", attr);
    BOOST_LOG(lg) << "This record has MyInteger == -5";

    // Change the attribute value
    attr.set(100);
    BOOST_LOG(lg) << "This record has MyInteger == 100";
}

在多线程应用程序中，set 方法调用必须与 get_value 调用（一般来说，每次进行日志记录时都会发生）进行序列化。默认情况下，mutable_constant 不以任何方式序列化调用，而是假定用户将在外部执行此操作。但是，mutable_constant 模板提供了三个额外的模板参数：同步原语类型、作用域独占锁类型和作用域共享锁类型。如果指定了同步原语类型，则作用域独占锁类型是强制参数。如果未指定作用域共享锁类型，则属性将回退到独占锁而不是共享锁。例如

// This mutable constant will always lock exclusively
// either for reading or storing the value
typedef attrs::mutable_constant<
    int,                                        // attribute value type
    boost::mutex,                               // synchronization primitive
    boost::lock_guard< boost::mutex >           // exclusive lock type
> exclusive_mc;
exclusive_mc my_int1(10);

// This mutable constant will use shared clocking for reading the value
// and exclusive locking for storing
typedef attrs::mutable_constant<
    int,                                        // attribute value type
    boost::shared_mutex,                        // synchronization primitive
    boost::unique_lock< boost::shared_mutex >,  // exclusive lock type
    boost::shared_lock< boost::shared_mutex >   // shared lock type
> shared_mc;
shared_mc my_int2(20);

BOOST_LOG_INLINE_GLOBAL_LOGGER_INIT(my_logger, src::logger_mt)
{
    src::logger_mt lg;
    lg.add_attribute("MyInteger1", my_int1);
    lg.add_attribute("MyInteger2", my_int2);

    return lg;
}

void foo()
{
    src::logger_mt& lg = get_my_logger();

    // This is safe, even if executed in multiple threads
    my_int1.set(200);
    BOOST_LOG(lg) << "This record has MyInteger1 == 200";

    my_int2.set(300);
    BOOST_LOG(lg) << "This record has MyInteger2 == 300";
}

可变常量通常用作记录器内部的辅助属性，用于存储可能在某些事件上更改的属性。与常规常量不同，常规常量在值修改的情况下需要重新注册，而可变常量允许就地修改值。

#include <boost/log/attributes/counter.hpp>

计数器是最简单的属性之一，每次请求时都会生成一个新值。计数器通常用于标识日志记录或计数某些事件，例如接受的网络连接。counter 类模板提供了这种功能。此模板使用计数器值类型进行参数化，该类型应支持算术运算，例如 operator + 和 operator -。计数器属性允许在构造时指定初始值和步长（可以为负数）。

BOOST_LOG_INLINE_GLOBAL_LOGGER_INIT(my_logger, src::logger_mt)
{
    src::logger_mt lg;

    // This counter will count lines, starting from 0
    lg.add_attribute("LineCounter", attrs::counter< unsigned int >());

    // This counter will count backwards, starting from 100 with step -5
    lg.add_attribute("CountDown", attrs::counter< int >(100, -5));

    return lg;
}

void foo()
{
    src::logger_mt& lg = get_my_logger();
    BOOST_LOG(lg) << "This record has LineCounter == 0, CountDown == 100";
    BOOST_LOG(lg) << "This record has LineCounter == 1, CountDown == 95";
    BOOST_LOG(lg) << "This record has LineCounter == 2, CountDown == 90";
}

	注意
	不要期望具有 counter 属性的日志记录在生成的日志中始终具有升序或降序的计数器值。在多线程应用程序中，不同线程获取的计数器值可能以任何顺序到达 sink。原理 更详细地解释了为什么会发生这种情况。因此，更准确地说，counter 属性生成升序或降序的标识符，而不是它以任一顺序计数日志记录。

#include <boost/log/attributes/clock.hpp>

任何日志记录库的“必备”功能之一是支持为每个日志记录附加时间戳。该库为此目的提供了两个属性：utc_clock 和 local_clock。前者返回当前的 UTC 时间，后者返回当前的本地时间。在这两种情况下，返回的时间戳都以目标平台的最高精度获取。属性值是 boost::posix_time::ptime（参见 Boost.DateTime）。用法非常简单明了

BOOST_LOG_DECLARE_GLOBAL_LOGGER(my_logger, src::logger_mt)

void foo()
{
    logging::core::get()->add_global_attribute(
        "TimeStamp",
        attrs::local_clock());

    // Now every log record ever made will have a time stamp attached
    src::logger_mt& lg = get_my_logger();
    BOOST_LOG(lg) << "This record has a time stamp";
}

	注意
	与任何其他属性一样，系统时钟属性的值是在日志记录创建时获得的，而不是在 sink 中处理日志记录时获得的。这意味着 (a) 附加到日志记录的时间戳始终反映事件发生的时间点，而不是存储日志记录的时间，并且 (b) 如果同一日志记录由多个 sink 处理，即使在不同的时间点，这些 sink 也将处理（例如，存储在其各自的文件中）相同的时间戳。这是系统时钟属性的一个有用属性，尽管它可能导致输出中日志记录的 弱排序。

#include <boost/log/attributes/timer.hpp>

当需要估计某些长时间运行的过程的持续时间时，timer 属性非常有用。该属性返回自属性构造以来经过的时间。属性值类型为 boost::posix_time::ptime::time_duration_type（参见 Boost.DateTime）。

// The class represents a single peer-to-peer connection
class network_connection
{
    src::logger m_logger;

public:
    network_connection()
    {
        m_logger.add_attribute("Duration", attrs::timer());
        BOOST_LOG(m_logger) << "Connection established";
    }
    ~network_connection()
    {
        // This log record will show the whole life time duration of the connection
        BOOST_LOG(m_logger) << "Connection closed";
    }
};

该属性提供高分辨率的时间估计，甚至可以用作简单的就地性能分析工具。

	提示
	timer 属性甚至可以在不重新编译的情况下用于分析不同模块中的代码。诀窍是用线程特定的 timer 作用域属性 包装对外部模块的昂贵调用，这将使用时间读数标记从模块内部进行的所有日志记录。

#include <boost/log/attributes/named_scope.hpp>

// Supporting headers
#include <boost/log/support/exception.hpp>

日志记录库支持在应用程序执行期间维护作用域堆栈跟踪。此堆栈可以写入日志或用于其他需求（例如，在抛出异常时保存导致异常的确切调用序列）。每个堆栈元素包含以下信息（参见 named_scope_entry 结构体模板定义）

作用域堆栈在内部实现为线程特定的全局存储。有一个 named_scope 属性，允许将此堆栈挂钩到日志记录管道中。此属性生成嵌套类型 named_scope::scope_stack 的值，该值是作用域堆栈的实例。可以按以下方式注册属性

logging::core::get()->add_global_attribute("Scope", attrs::named_scope());

请注意，全局注册属性是完全有效的，因为作用域堆栈无论如何都是线程本地的。这也将隐式地将作用域跟踪添加到应用程序的所有线程，这通常正是所需要的。

现在我们可以使用宏 BOOST_LOG_FUNCTION 和 BOOST_LOG_NAMED_SCOPE（后者接受作用域名作为其参数）标记执行作用域。这些宏会自动将源代码位置信息添加到每个作用域条目。示例如下

void foo(int n)
{
    // Mark the scope of the function foo
    BOOST_LOG_FUNCTION();

    switch (n)
    {
    case 0:
        {
            // Mark the current scope
            BOOST_LOG_NAMED_SCOPE("case 0");
            BOOST_LOG(lg) << "Some log record";
            bar(); // call some function
        }
        break;

    case 1:
        {
            // Mark the current scope
            BOOST_LOG_NAMED_SCOPE("case 1");
            BOOST_LOG(lg) << "Some log record";
            bar(); // call some function
        }
        break;

    default:
        {
            // Mark the current scope
            BOOST_LOG_NAMED_SCOPE("default");
            BOOST_LOG(lg) << "Some log record";
            bar(); // call some function
        }
        break;
    }
}

执行 foo 后，我们将能够在日志中看到 bar 函数是从 foo 调用的，更准确地说，是从与 n 值对应的 case 语句调用的。当跟踪仅在从特定位置调用 bar 时才出现的细微错误时，这可能非常有用（例如，如果 bar 在该特定位置传递了无效参数）。

	注意
	BOOST_LOG_FUNCTION 宏使用编译器特定的扩展来从封闭函数生成作用域名。C++11 为此目的定义了一个标准宏 __func__，但它并非普遍支持。此外，字符串的格式未标准化，并且可能因编译器而异。因此，通常建议使用 BOOST_LOG_NAMED_SCOPE 而不是 BOOST_LOG_FUNCTION，以确保一致且可移植的行为。

	警告
	BOOST_LOG_FUNCTION 和 BOOST_LOG_NAMED_SCOPE 宏实际上在堆栈上形成了一个作用域描述符的链表，该链表在控制进入和离开 LIFO（后进先出）顺序的作用域时自动维护。属性实现依赖于此 LIFO 顺序。当执行切换到另一个堆栈并在任意点返回时，这会中断，这允许控制以任何顺序进入和离开作用域。这发生在线程上下文切换时，例如在使用协程或低级系统 API（如 ucontext 和 fibers）时。在利用此类上下文切换功能的代码中使用命名作用域需要仔细编程，以维护使用命名作用域宏标记的作用域的进入/离开的 LIFO 顺序。否则，使用命名作用域将导致未定义的行为，应避免使用。请注意，对于任意上下文切换，作用域列表无论如何都不会提供有意义的信息。

另一个好的用例是将作用域堆栈信息附加到异常。借助 Boost.Exception，这是可能的

void bar(int x)
{
    BOOST_LOG_FUNCTION();

    if (x < 0)
    {
        // Attach a copy of the current scope stack to the exception
        throw boost::enable_error_info(std::range_error("x must not be negative"))
            << logging::current_scope();
    }
}

void foo()
{
    BOOST_LOG_FUNCTION();

    try
    {
        bar(-1);
    }
    catch (std::range_error& e)
    {
        // Acquire the scope stack from the exception object
        BOOST_LOG(lg) << "bar call failed: " << e.what() << ", scopes stack:\n"
            << *boost::get_error_info< logging::current_scope_info >(e);
    }
}

	注意
	为了编译此代码，必须包含 Boost.Exception 支持头文件。

	注意
	我们不会将 named_scope 属性注入到异常中。由于作用域堆栈是全局维护的，因此抛出异常将导致堆栈展开，并因此截断全局堆栈。相反，我们在抛出点通过调用 current_scope 创建作用域堆栈的副本。即使全局堆栈实例在堆栈展开期间发生更改，此副本也将保持完整无缺。

#include <boost/log/attributes/current_process_id.hpp>

了解生成日志的进程标识符通常很有用，尤其是在日志最终可以合并不同进程的输出的情况下。current_process_id 属性是一个常量，它格式化为当前进程标识符。属性的值类型可以由 current_process_id::value_type typedef 确定。

void foo()
{
    logging::core::get()->add_global_attribute(
        "ProcessID",
        attrs::current_process_id());
}

#include <boost/log/attributes/current_process_name.hpp>

current_process_name 生成带有当前进程可执行名称的 std::string 值。

	注意
	此属性并非普遍可移植，尽管支持 Windows、Linux 和 OS X。该属性也可能在其他 POSIX 系统上工作，但尚未经过测试。如果无法获取进程名称，则该属性将生成一个带有进程 ID 的字符串。

void foo()
{
    logging::core::get()->add_global_attribute(
        "Process",
        attrs::current_process_name());
}

#include <boost/log/attributes/current_thread_id.hpp>

库的多线程构建也支持 current_thread_id 属性，其值类型为 current_thread_id::value_type。该属性将生成特定于调用线程的值。用法类似于进程 ID。

void foo()
{
    logging::core::get()->add_global_attribute(
        "ThreadID",
        attrs::current_thread_id());
}

	提示
	您可能已经注意到该属性是全局注册的。这不会导致所有线程在日志记录中具有相同的 ThreadID，因为该属性将始终返回线程特定的值。额外的好处是，您不必在线程初始化例程中执行任何操作即可在日志记录中具有线程特定的属性值。

#include <boost/log/attributes/function.hpp>

此属性是用户定义的函数对象的简单包装器。每次尝试获取属性值都会导致函数对象调用。调用的结果作为属性值返回（这意味着函数不得返回 void）。函数对象属性可以使用 make_function 辅助函数构造，如下所示

void foo()
{
    logging::core::get()->add_global_attribute("MyRandomAttr", attrs::make_function(&std::rand));
}

也支持自动生成的函数对象，如 Boost.Bind 或 C++ 标准库中定义的函数对象。

	注意
	一些有缺陷的编译器可能无法正确支持 result_of 构造。此元函数在 make_function 函数中用于自动检测函数对象的返回类型。如果 result_of 中断或检测到不正确的类型，可以尝试显式指定函数对象的返回类型作为 make_function 函数的模板参数。