2 * Copyright Andrey Semashev 2007 - 2015.
3 * Distributed under the Boost Software License, Version 1.0.
4 * (See accompanying file LICENSE_1_0.txt or copy at
5 * http://www.boost.org/LICENSE_1_0.txt)
8 * \file basic_logger.hpp
9 * \author Andrey Semashev
12 * The header contains implementation of a base class for loggers. Convenience macros
13 * for defining custom loggers are also provided.
16 #ifndef BOOST_LOG_SOURCES_BASIC_LOGGER_HPP_INCLUDED_
17 #define BOOST_LOG_SOURCES_BASIC_LOGGER_HPP_INCLUDED_
22 #include <boost/assert.hpp>
23 #include <boost/move/core.hpp>
24 #include <boost/move/utility_core.hpp>
25 #include <boost/core/addressof.hpp>
26 #include <boost/preprocessor/facilities/empty.hpp>
27 #include <boost/preprocessor/facilities/identity.hpp>
28 #include <boost/preprocessor/repetition/enum_params.hpp>
29 #include <boost/preprocessor/repetition/enum_binary_params.hpp>
30 #include <boost/preprocessor/repetition/repeat_from_to.hpp>
31 #include <boost/preprocessor/seq/enum.hpp>
32 #include <boost/log/detail/config.hpp>
33 #include <boost/log/detail/parameter_tools.hpp>
34 #include <boost/log/attributes/attribute_set.hpp>
35 #include <boost/log/attributes/attribute_name.hpp>
36 #include <boost/log/attributes/attribute.hpp>
37 #include <boost/log/core/core.hpp>
38 #include <boost/log/core/record.hpp>
39 #include <boost/log/sources/features.hpp>
40 #include <boost/log/sources/threading_models.hpp>
41 #include <boost/log/detail/header.hpp>
43 #ifdef BOOST_HAS_PRAGMA_ONCE
49 BOOST_LOG_OPEN_NAMESPACE
54 * \brief Basic logger class
56 * The \c basic_logger class template serves as a base class for all loggers
57 * provided by the library. It can also be used as a base for user-defined
58 * loggers. The template parameters are:
60 * \li \c CharT - logging character type
61 * \li \c FinalT - final type of the logger that eventually derives from
62 * the \c basic_logger. There may be other classes in the hierarchy
63 * between the final class and \c basic_logger.
64 * \li \c ThreadingModelT - threading model policy. Must provide methods
65 * of the Boost.Thread locking concept used in \c basic_logger class
66 * and all its derivatives in the hierarchy up to the \c FinalT class.
67 * The \c basic_logger class itself requires methods of the
68 * SharedLockable concept. The threading model policy must also be
69 * default and copy-constructible and support member function \c swap.
70 * There are currently two policies provided: \c single_thread_model
71 * and \c multi_thread_model.
73 * The logger implements fundamental facilities of loggers, such as storing
74 * source-specific attribute set and formatting log record messages. The basic
75 * logger interacts with the logging core in order to apply filtering and
76 * pass records to sinks.
78 template< typename CharT, typename FinalT, typename ThreadingModelT >
80 public ThreadingModelT
82 typedef basic_logger this_type;
83 BOOST_COPYABLE_AND_MOVABLE_ALT(this_type)
87 typedef CharT char_type;
89 typedef FinalT final_type;
90 //! Threading model type
91 typedef ThreadingModelT threading_model;
93 #if !defined(BOOST_LOG_NO_THREADS)
94 //! Lock requirement for the swap_unlocked method
95 typedef boost::log::aux::exclusive_lock_guard< threading_model > swap_lock;
96 //! Lock requirement for the add_attribute_unlocked method
97 typedef boost::log::aux::exclusive_lock_guard< threading_model > add_attribute_lock;
98 //! Lock requirement for the remove_attribute_unlocked method
99 typedef boost::log::aux::exclusive_lock_guard< threading_model > remove_attribute_lock;
100 //! Lock requirement for the remove_all_attributes_unlocked method
101 typedef boost::log::aux::exclusive_lock_guard< threading_model > remove_all_attributes_lock;
102 //! Lock requirement for the get_attributes method
103 typedef boost::log::aux::shared_lock_guard< const threading_model > get_attributes_lock;
104 //! Lock requirement for the open_record_unlocked method
105 typedef boost::log::aux::shared_lock_guard< threading_model > open_record_lock;
106 //! Lock requirement for the set_attributes method
107 typedef boost::log::aux::exclusive_lock_guard< threading_model > set_attributes_lock;
109 typedef no_lock< threading_model > swap_lock;
110 typedef no_lock< threading_model > add_attribute_lock;
111 typedef no_lock< threading_model > remove_attribute_lock;
112 typedef no_lock< threading_model > remove_all_attributes_lock;
113 typedef no_lock< const threading_model > get_attributes_lock;
114 typedef no_lock< threading_model > open_record_lock;
115 typedef no_lock< threading_model > set_attributes_lock;
118 //! Lock requirement for the push_record_unlocked method
119 typedef no_lock< threading_model > push_record_lock;
122 //! A pointer to the logging system
125 //! Logger-specific attribute set
126 attribute_set m_Attributes;
130 * Constructor. Initializes internal data structures of the basic logger class,
131 * acquires reference to the logging core.
139 * Copy constructor. Copies all attributes from the source logger.
141 * \note Not thread-safe. The source logger must be locked in the final class before copying.
143 * \param that Source logger
145 basic_logger(basic_logger const& that) :
146 threading_model(static_cast< threading_model const& >(that)),
147 m_pCore(core::get()),
148 m_Attributes(that.m_Attributes)
152 * Move constructor. Moves all attributes from the source logger.
154 * \note Not thread-safe. The source logger must be locked in the final class before copying.
156 * \param that Source logger
158 basic_logger(BOOST_RV_REF(basic_logger) that) :
159 threading_model(boost::move(static_cast< threading_model& >(that)))
161 m_pCore.swap(that.m_pCore);
162 m_Attributes.swap(that.m_Attributes);
165 * Constructor with named arguments. The constructor ignores all arguments. The result of
166 * construction is equivalent to default construction.
168 template< typename ArgsT >
169 explicit basic_logger(ArgsT const&) :
177 * An accessor to the logging system pointer
179 core_ptr const& core() const { return m_pCore; }
181 * An accessor to the logger attributes
183 attribute_set& attributes() { return m_Attributes; }
185 * An accessor to the logger attributes
187 attribute_set const& attributes() const { return m_Attributes; }
189 * An accessor to the threading model base
191 threading_model& get_threading_model() { return *this; }
193 * An accessor to the threading model base
195 threading_model const& get_threading_model() const { return *this; }
197 * An accessor to the final logger
199 final_type* final_this()
201 BOOST_LOG_ASSUME(this != NULL);
202 return static_cast< final_type* >(this);
205 * An accessor to the final logger
207 final_type const* final_this() const
209 BOOST_LOG_ASSUME(this != NULL);
210 return static_cast< final_type const* >(this);
216 void swap_unlocked(basic_logger& that)
218 get_threading_model().swap(that.get_threading_model());
219 m_Attributes.swap(that.m_Attributes);
223 * Unlocked \c add_attribute
225 std::pair< attribute_set::iterator, bool > add_attribute_unlocked(attribute_name const& name, attribute const& attr)
227 return m_Attributes.insert(name, attr);
231 * Unlocked \c remove_attribute
233 void remove_attribute_unlocked(attribute_set::iterator it)
235 m_Attributes.erase(it);
239 * Unlocked \c remove_all_attributes
241 void remove_all_attributes_unlocked()
243 m_Attributes.clear();
247 * Unlocked \c open_record
249 record open_record_unlocked()
251 return m_pCore->open_record(m_Attributes);
254 * Unlocked \c open_record
256 template< typename ArgsT >
257 record open_record_unlocked(ArgsT const&)
259 return m_pCore->open_record(m_Attributes);
263 * Unlocked \c push_record
265 void push_record_unlocked(BOOST_RV_REF(record) rec)
267 m_pCore->push_record(boost::move(rec));
271 * Unlocked \c get_attributes
273 attribute_set get_attributes_unlocked() const
279 * Unlocked \c set_attributes
281 void set_attributes_unlocked(attribute_set const& attrs)
283 m_Attributes = attrs;
286 //! Assignment is closed (should be implemented through copy and swap in the final class)
287 BOOST_DELETED_FUNCTION(basic_logger& operator= (basic_logger const&))
291 * Free-standing swap for all loggers
293 template< typename CharT, typename FinalT, typename ThreadingModelT >
295 basic_logger< CharT, FinalT, ThreadingModelT >& left,
296 basic_logger< CharT, FinalT, ThreadingModelT >& right)
298 static_cast< FinalT& >(left).swap(static_cast< FinalT& >(right));
302 * \brief A composite logger that inherits a number of features
304 * The composite logger is a helper class that simplifies feature composition into the final logger.
305 * The user's logger class is expected to derive from the composite logger class, instantiated with
306 * the character type, the user's logger class, the threading model and the list of the required features.
307 * The former three parameters are passed to the \c basic_logger class template. The feature list
308 * must be an MPL type sequence, where each element is a unary MPL metafunction class, that upon
309 * applying on its argument results in a logging feature class that derives from the argument.
310 * Every logger feature provided by the library can participate in the feature list.
312 template< typename CharT, typename FinalT, typename ThreadingModelT, typename FeaturesT >
313 class basic_composite_logger :
314 public boost::log::sources::aux::inherit_features<
315 basic_logger< CharT, FinalT, ThreadingModelT >,
320 //! Base type (the hierarchy of features)
321 typedef typename boost::log::sources::aux::inherit_features<
322 basic_logger< CharT, FinalT, ThreadingModelT >,
327 //! The composite logger type (for use in the user's logger class)
328 typedef basic_composite_logger logger_base;
329 BOOST_COPYABLE_AND_MOVABLE_ALT(logger_base)
332 //! Threading model being used
333 typedef typename base_type::threading_model threading_model;
335 #if !defined(BOOST_LOG_NO_THREADS)
339 * Default constructor (default-constructs all features)
341 basic_composite_logger() {}
345 basic_composite_logger(basic_composite_logger const& that) :
348 boost::log::aux::shared_lock_guard< const threading_model >(that.get_threading_model()),
349 static_cast< base_type const& >(that)
356 basic_composite_logger(BOOST_RV_REF(logger_base) that) :
357 base_type(boost::move(static_cast< base_type& >(that)))
361 * Constructor with named parameters
363 template< typename ArgsT >
364 explicit basic_composite_logger(ArgsT const& args) : base_type(args)
369 * The method adds an attribute to the source-specific attribute set. The attribute will be implicitly added to
370 * every log record made with the current logger.
372 * \param name The attribute name.
373 * \param attr The attribute factory.
374 * \return A pair of values. If the second member is \c true, then the attribute is added and the first member points to the
375 * attribute. Otherwise the attribute was not added and the first member points to the attribute that prevents
378 std::pair< attribute_set::iterator, bool > add_attribute(attribute_name const& name, attribute const& attr)
380 typename base_type::add_attribute_lock lock(base_type::get_threading_model());
381 return base_type::add_attribute_unlocked(name, attr);
384 * The method removes an attribute from the source-specific attribute set.
386 * \pre The attribute was added with the add_attribute call for this instance of the logger.
387 * \post The attribute is no longer registered as a source-specific attribute for this logger. The iterator is invalidated after removal.
389 * \param it Iterator to the previously added attribute.
391 void remove_attribute(attribute_set::iterator it)
393 typename base_type::remove_attribute_lock lock(base_type::get_threading_model());
394 base_type::remove_attribute_unlocked(it);
398 * The method removes all attributes from the logger. All iterators and references to the removed attributes are invalidated.
400 void remove_all_attributes()
402 typename base_type::remove_all_attributes_lock lock(base_type::get_threading_model());
403 base_type::remove_all_attributes_unlocked();
407 * The method retrieves a copy of a set with all attributes from the logger.
409 * \return The copy of the attribute set. Attributes are shallow-copied.
411 attribute_set get_attributes() const
413 typename base_type::get_attributes_lock lock(base_type::get_threading_model());
414 return base_type::get_attributes_unlocked();
418 * The method installs the whole attribute set into the logger. All iterators and references to elements of
419 * the previous set are invalidated. Iterators to the \a attrs set are not valid to be used with the logger (that is,
420 * the logger owns a copy of \a attrs after completion).
422 * \param attrs The set of attributes to install into the logger. Attributes are shallow-copied.
424 void set_attributes(attribute_set const& attrs)
426 typename base_type::set_attributes_lock lock(base_type::get_threading_model());
427 base_type::set_attributes_unlocked(attrs);
431 * The method opens a new log record in the logging core.
433 * \return A valid record handle if the logging record is opened successfully, an invalid handle otherwise.
437 // Perform a quick check first
438 if (this->core()->get_logging_enabled())
440 typename base_type::open_record_lock lock(base_type::get_threading_model());
441 return base_type::open_record_unlocked(boost::log::aux::empty_arg_list());
447 * The method opens a new log record in the logging core.
449 * \param args A set of additional named arguments. The parameter is ignored.
450 * \return A valid record handle if the logging record is opened successfully, an invalid handle otherwise.
452 template< typename ArgsT >
453 record open_record(ArgsT const& args)
455 // Perform a quick check first
456 if (this->core()->get_logging_enabled())
458 typename base_type::open_record_lock lock(base_type::get_threading_model());
459 return base_type::open_record_unlocked(args);
465 * The method pushes the constructed message to the logging core
467 * \param rec The log record with the formatted message
469 void push_record(BOOST_RV_REF(record) rec)
471 typename base_type::push_record_lock lock(base_type::get_threading_model());
472 base_type::push_record_unlocked(boost::move(rec));
475 * Thread-safe implementation of swap
477 void swap(basic_composite_logger& that)
479 boost::log::aux::multiple_unique_lock2<
482 > lock(base_type::get_threading_model(), that.get_threading_model());
483 base_type::swap_unlocked(that);
488 * Assignment for the final class. Threadsafe, provides strong exception guarantee.
490 FinalT& assign(FinalT const& that)
492 BOOST_LOG_ASSUME(this != NULL);
493 if (static_cast< FinalT* >(this) != boost::addressof(that))
495 // We'll have to explicitly create the copy in order to make sure it's unlocked when we attempt to lock *this
497 boost::log::aux::exclusive_lock_guard< threading_model > lock(base_type::get_threading_model());
498 base_type::swap_unlocked(tmp);
500 return static_cast< FinalT& >(*this);
504 //! An optimized composite logger version with no multithreading support
505 template< typename CharT, typename FinalT, typename FeaturesT >
506 class basic_composite_logger< CharT, FinalT, single_thread_model, FeaturesT > :
507 public boost::log::sources::aux::inherit_features<
508 basic_logger< CharT, FinalT, single_thread_model >,
513 typedef typename boost::log::sources::aux::inherit_features<
514 basic_logger< CharT, FinalT, single_thread_model >,
519 typedef basic_composite_logger logger_base;
520 BOOST_COPYABLE_AND_MOVABLE_ALT(logger_base)
523 typedef typename base_type::threading_model threading_model;
525 #endif // !defined(BOOST_LOG_NO_THREADS)
528 basic_composite_logger() {}
529 basic_composite_logger(basic_composite_logger const& that) :
530 base_type(static_cast< base_type const& >(that))
533 basic_composite_logger(BOOST_RV_REF(logger_base) that) :
534 base_type(boost::move(static_cast< base_type& >(that)))
537 template< typename ArgsT >
538 explicit basic_composite_logger(ArgsT const& args) : base_type(args)
542 std::pair< attribute_set::iterator, bool > add_attribute(attribute_name const& name, attribute const& attr)
544 return base_type::add_attribute_unlocked(name, attr);
546 void remove_attribute(attribute_set::iterator it)
548 base_type::remove_attribute_unlocked(it);
550 void remove_all_attributes()
552 base_type::remove_all_attributes_unlocked();
554 attribute_set get_attributes() const
556 return base_type::get_attributes_unlocked();
558 void set_attributes(attribute_set const& attrs)
560 base_type::set_attributes_unlocked(attrs);
564 // Perform a quick check first
565 if (this->core()->get_logging_enabled())
566 return base_type::open_record_unlocked(boost::log::aux::empty_arg_list());
570 template< typename ArgsT >
571 record open_record(ArgsT const& args)
573 // Perform a quick check first
574 if (this->core()->get_logging_enabled())
575 return base_type::open_record_unlocked(args);
579 void push_record(BOOST_RV_REF(record) rec)
581 base_type::push_record_unlocked(boost::move(rec));
583 void swap(basic_composite_logger& that)
585 base_type::swap_unlocked(that);
589 FinalT& assign(FinalT that)
591 base_type::swap_unlocked(that);
592 return static_cast< FinalT& >(*this);
597 #ifndef BOOST_LOG_DOXYGEN_PASS
599 #define BOOST_LOG_FORWARD_LOGGER_CONSTRUCTORS_IMPL(class_type, typename_keyword)\
601 BOOST_DEFAULTED_FUNCTION(class_type(), {})\
602 class_type(class_type const& that) : class_type::logger_base(\
603 static_cast< typename_keyword() class_type::logger_base const& >(that)) {}\
604 class_type(BOOST_RV_REF(class_type) that) : class_type::logger_base(\
605 ::boost::move(static_cast< typename_keyword() class_type::logger_base& >(that))) {}\
606 BOOST_LOG_PARAMETRIZED_CONSTRUCTORS_FORWARD(class_type, class_type::logger_base)\
608 #endif // BOOST_LOG_DOXYGEN_PASS
610 #define BOOST_LOG_FORWARD_LOGGER_CONSTRUCTORS(class_type)\
611 BOOST_LOG_FORWARD_LOGGER_CONSTRUCTORS_IMPL(class_type, BOOST_PP_EMPTY)
613 #define BOOST_LOG_FORWARD_LOGGER_CONSTRUCTORS_TEMPLATE(class_type)\
614 BOOST_LOG_FORWARD_LOGGER_CONSTRUCTORS_IMPL(class_type, BOOST_PP_IDENTITY(typename))
616 #define BOOST_LOG_FORWARD_LOGGER_ASSIGNMENT(class_type)\
618 class_type& operator= (BOOST_COPY_ASSIGN_REF(class_type) that)\
620 return class_type::logger_base::assign(static_cast< class_type const& >(that));\
622 class_type& operator= (BOOST_RV_REF(class_type) that)\
624 BOOST_LOG_EXPR_IF_MT(::boost::log::aux::exclusive_lock_guard< class_type::threading_model > lock(this->get_threading_model());)\
625 this->swap_unlocked(that);\
629 #define BOOST_LOG_FORWARD_LOGGER_ASSIGNMENT_TEMPLATE(class_type)\
631 class_type& operator= (BOOST_COPY_ASSIGN_REF(class_type) that)\
633 return class_type::logger_base::assign(static_cast< class_type const& >(that));\
635 class_type& operator= (BOOST_RV_REF(class_type) that)\
637 BOOST_LOG_EXPR_IF_MT(::boost::log::aux::exclusive_lock_guard< typename class_type::threading_model > lock(this->get_threading_model());)\
638 this->swap_unlocked(that);\
642 #define BOOST_LOG_FORWARD_LOGGER_MEMBERS(class_type)\
643 BOOST_COPYABLE_AND_MOVABLE(class_type)\
644 BOOST_LOG_FORWARD_LOGGER_CONSTRUCTORS(class_type)\
645 BOOST_LOG_FORWARD_LOGGER_ASSIGNMENT(class_type)
647 #define BOOST_LOG_FORWARD_LOGGER_MEMBERS_TEMPLATE(class_type)\
648 BOOST_COPYABLE_AND_MOVABLE(class_type)\
649 BOOST_LOG_FORWARD_LOGGER_CONSTRUCTORS_TEMPLATE(class_type)\
650 BOOST_LOG_FORWARD_LOGGER_ASSIGNMENT_TEMPLATE(class_type)
652 } // namespace sources
654 BOOST_LOG_CLOSE_NAMESPACE // namespace log
659 * \brief The macro declares a logger class that inherits a number of base classes
661 * \param type_name The name of the logger class to declare
662 * \param char_type The character type of the logger. Either char or wchar_t expected.
663 * \param base_seq A Boost.Preprocessor sequence of type identifiers of the base classes templates
664 * \param threading A threading model class
666 #define BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, char_type, base_seq, threading)\
668 public ::boost::log::sources::basic_composite_logger<\
672 ::boost::log::sources::features< BOOST_PP_SEQ_ENUM(base_seq) >\
675 BOOST_LOG_FORWARD_LOGGER_MEMBERS(type_name)\
680 #ifdef BOOST_LOG_USE_CHAR
683 * \brief The macro declares a narrow-char logger class that inherits a number of base classes
685 * Equivalent to BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, char, base_seq, single_thread_model)
687 * \param type_name The name of the logger class to declare
688 * \param base_seq A Boost.Preprocessor sequence of type identifiers of the base classes templates
690 #define BOOST_LOG_DECLARE_LOGGER(type_name, base_seq)\
691 BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, char, base_seq, ::boost::log::sources::single_thread_model)
693 #if !defined(BOOST_LOG_NO_THREADS)
696 * \brief The macro declares a narrow-char thread-safe logger class that inherits a number of base classes
698 * Equivalent to <tt>BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, char, base_seq, multi_thread_model< shared_mutex >)</tt>
700 * \param type_name The name of the logger class to declare
701 * \param base_seq A Boost.Preprocessor sequence of type identifiers of the base classes templates
703 #define BOOST_LOG_DECLARE_LOGGER_MT(type_name, base_seq)\
704 BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, char, base_seq,\
705 ::boost::log::sources::multi_thread_model< ::boost::shared_mutex >)
707 #endif // !defined(BOOST_LOG_NO_THREADS)
708 #endif // BOOST_LOG_USE_CHAR
710 #ifdef BOOST_LOG_USE_WCHAR_T
713 * \brief The macro declares a wide-char logger class that inherits a number of base classes
715 * Equivalent to BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, wchar_t, base_seq, single_thread_model)
717 * \param type_name The name of the logger class to declare
718 * \param base_seq A Boost.Preprocessor sequence of type identifiers of the base classes templates
720 #define BOOST_LOG_DECLARE_WLOGGER(type_name, base_seq)\
721 BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, wchar_t, base_seq, ::boost::log::sources::single_thread_model)
723 #if !defined(BOOST_LOG_NO_THREADS)
726 * \brief The macro declares a wide-char thread-safe logger class that inherits a number of base classes
728 * Equivalent to <tt>BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, wchar_t, base_seq, multi_thread_model< shared_mutex >)</tt>
730 * \param type_name The name of the logger class to declare
731 * \param base_seq A Boost.Preprocessor sequence of type identifiers of the base classes templates
733 #define BOOST_LOG_DECLARE_WLOGGER_MT(type_name, base_seq)\
734 BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, wchar_t, base_seq,\
735 ::boost::log::sources::multi_thread_model< ::boost::shared_mutex >)
737 #endif // !defined(BOOST_LOG_NO_THREADS)
738 #endif // BOOST_LOG_USE_WCHAR_T
740 #include <boost/log/detail/footer.hpp>
742 #endif // BOOST_LOG_SOURCES_BASIC_LOGGER_HPP_INCLUDED_