Writing your own sources

Boost , Chapter 1. Boost.Log v2 , Extending the library

#include <boost/log/sources/threading_models.hpp>
#include <boost/log/sources/basic_logger.hpp>

Чтобы проиллюстрировать все эти длинные рекомендации, давайте реализуем простую функцию регистратора. Предположим, мы хотим, чтобы наш регистратор мог пометить отдельные записи журнала. Другими словами, регистратор должен временно добавить атрибут к своему набору атрибутов, испустить запись регистрации, а затем автоматически удалить атрибут. Несколько похожая функциональность может быть достигнута с помощью расширенных атрибутов, хотя синтаксис может усложнить обертывание его в аккуратный макрос:

// We want something equivalent to this
{
    BOOST_LOG_SCOPED_LOGGER_TAG(logger, "Tag", "[GUI]");
    BOOST_LOG(logger) << "The user has confirmed his choice";
}

Давайте объявим нашу функцию регистратора:

template< typename BaseT >
class record_tagger_feature :
    public BaseT                        
{
public:
    // Let's import some types that we will need. These imports should be public,
    // in order to allow other features that may derive from record_tagger to do the same.
    typedef typename BaseT::char_type char_type;
    typedef typename BaseT::threading_model threading_model;
public:
    // Default constructor. Initializes m_Tag to an invalid value.
    record_tagger_feature();
    // Copy constructor. Initializes m_Tag to a value, equivalent to that.m_Tag.
    record_tagger_feature(record_tagger_feature const& that);
    // Forwarding constructor with named parameters
    template< typename ArgsT >
    record_tagger_feature(ArgsT const& args);
    // The method will require locking, so we have to define locking requirements for it.
    // We use the strictest_lock trait in order to choose the most restricting lock type.
    typedef typename logging::strictest_lock<
        boost::lock_guard< threading_model >,
        typename BaseT::open_record_lock,
        typename BaseT::add_attribute_lock,
        typename BaseT::remove_attribute_lock
    >::type open_record_lock;
protected:
    // Lock-less implementation of operations
    template< typename ArgsT >
    logging::record open_record_unlocked(ArgsT const& args);
};
// A convenience metafunction to specify the feature
// in the list of features of the final logger later
struct record_tagger :
    public boost::mpl::quote1< record_tagger_feature >
{
};

Вы можете видеть, что мы используем шаблон strictest_lock, чтобы определить типы блокировок, которые удовлетворяют требованиям безопасности потока базового класса для методов, которые должны быть вызваны из соответствующих методов record_tagger_feature. Определение open_record_lock показывает, что реализация open_record_unlocked для функции record_tagger_feature требует эксклюзивной блокировки (которой является lock_guard) для регистратора, но также учитывает требования к блокировке open_record_unlocked, add_attribute_unlocked способов базового класса, поскольку для этого придется их вызывать. Сгенерированный метод open_record конечного класса регистратора будет использовать этот типдеф для автоматического получения соответствующего типа блокировки перед пересылкой на методы open_record_unlocked.

На самом деле, в этом конкретном примере не было необходимости использовать черту strictest_lock, потому что все наши методы требуют исключительной блокировки, которая уже является самой строгой. Тем не менее, этот шаблон может пригодиться, если вы используете общую блокировку.

Реализация публичного интерфейса становится довольно тривиальной:

template< typename BaseT >
record_tagger_feature< BaseT >::record_tagger_feature()
{
}
template< typename BaseT >
record_tagger_feature< BaseT >::record_tagger_feature(record_tagger_feature const& that) :
    BaseT(static_cast< BaseT const& >(that))
{
}
template< typename BaseT >
template< typename ArgsT >
record_tagger_feature< BaseT >::record_tagger_feature(ArgsT const& args) : BaseT(args)
{
}

Теперь, поскольку вся блокировка извлекается в общедоступный интерфейс, у нас есть большая часть нашей логики функций, которая будет реализована в защищенной части интерфейса. Чтобы установить значение тега в регистраторе, нам нужно будет ввести новое ключевое слово Boost.Parameter. Следуя рекомендациям из этой библиотечной документации, лучше ввести ключевое слово в специальное пространство имен:

namespace my_keywords {
    BOOST_PARAMETER_KEYWORD(tag_ns, tag)
}

Открытие нового альбома может выглядеть примерно так:

template< typename BaseT >
template< typename ArgsT >
logging::record record_tagger_feature< BaseT >::open_record_unlocked(ArgsT const& args)
{
    // Extract the named argument from the parameters pack
    std::string tag_value = args[my_keywords::tag | std::string()];
    logging::attribute_set& attrs = BaseT::attributes();
    logging::attribute_set::iterator tag = attrs.end();
    if (!tag_value.empty())
    {
        // Add the tag as a new attribute
        std::pair<
            logging::attribute_set::iterator,
            bool
        > res = BaseT::add_attribute_unlocked("Tag",
            attrs::constant< std::string >(tag_value));
        if (res.second)
            tag = res.first;
    }
    // In any case, after opening a record remove the tag from the attributes
    BOOST_SCOPE_EXIT_TPL((&tag)(&attrs))
    {
        if (tag != attrs.end())
            attrs.erase(tag);
    }
    BOOST_SCOPE_EXIT_END
    // Forward the call to the base feature
    return BaseT::open_record_unlocked(args);
}

Здесь мы добавляем новый атрибут со значением тега, если он указан в вызове open_record. Когда запись журнала открывается, все значения атрибутов приобретаются и блокируются после записи, поэтому мы удаляем тег из набора атрибутов с блоком Boost.ScopeExit.

Хорошо, у нас есть функция, и пришло время ввести ее в лесоруб. Предположим, что мы хотим объединить его со стандартным уровнем жесткости. Нет проблем:

template< typename LevelT = int >
class my_logger :
    public src::basic_composite_logger<
        char,                           
        my_logger< LevelT >,            
        src::single_thread_model,       
        src::features<                  
            src::severity< LevelT >,
            record_tagger
        >
    >
{
    // The following line will automatically generate forwarding constructors that
    // will call to the corresponding constructors of the base class
    BOOST_LOG_FORWARD_LOGGER_MEMBERS_TEMPLATE(my_logger)
};

Как видите, создание лесозаготовителя – довольно простая процедура. Макро BOOST_LOG_FORWARD_LOGGER_MEMBERS_TEMPLATE, которое вы видите здесь, просто для удобства: оно разворачивается в конструктор по умолчанию, конструктор копий, оператор назначения и ряд конструкторов для поддержки названных аргументов. Для нешаблонных лесорубов существует аналогичная BOOST_LOG_FORWARD_LOGGER_MEMBERS macro.

Предполагая, что мы определили уровни тяжести, как это:

enum severity_level
{
    normal,
    warning,
    error
};

теперь мы можем использовать наш регистратор следующим образом:

void manual_logging()
{
    my_logger< severity_level > logger;
    logging::record rec = logger.open_record((keywords::severity = normal, my_keywords::tag = "GUI"));
    if (rec)
    {
        logging::record_ostream strm(rec);
        strm << "The user has confirmed his choice";
        strm.flush();
        logger.push_record(boost::move(rec));
    }
}

Вся эта вербальность обычно не требуется. Можно определить специальный макрос, чтобы сделать код более лаконичным:

#define LOG_WITH_TAG(lg, sev, tg) \
    BOOST_LOG_WITH_PARAMS((lg), (keywords::severity = (sev))(my_keywords::tag = (tg)))
void logging_function()
{
    my_logger< severity_level > logger;
    LOG_WITH_TAG(logger, normal, "GUI") << "The user has confirmed his choice";
}

См. полный код .

Guidelines for designers of standalone logging sources

В общем, вы можете внедрять новые источники журналирования так, как вам нравится, библиотека не предписывает никаких требований к проектированию источников журналов. Тем не менее, есть некоторые заметки о том, как источники журналов должны взаимодействовать с ядром журналирования.

Статья Writing your own sources раздела Chapter 1. Boost.Log v2 Extending the library может быть полезна для разработчиков на c++ и boost.

:: Главная :: Extending the library ::