log/attributes/named_scope.hpp

0001 /*
0002  *          Copyright Andrey Semashev 2007 - 2015.
0003  * Distributed under the Boost Software License, Version 1.0.
0004  *    (See accompanying file LICENSE_1_0.txt or copy at
0005  *          http://www.boost.org/LICENSE_1_0.txt)
0006  */
0007 /*!
0008  * \file
0009  * \author Andrey Semashev
0010  * \date   24.06.2007
0011  *
0012  * The header contains implementation of named scope container and an attribute that allows to
0013  * put the named scope to log. A number of convenience macros are also provided.
0014  */
0015
0016 #ifndef BOOST_LOG_ATTRIBUTES_NAMED_SCOPE_HPP_INCLUDED_
0017 #define BOOST_LOG_ATTRIBUTES_NAMED_SCOPE_HPP_INCLUDED_
0018
0019 #include <ostream>
0020 #include <memory>
0021 #include <iterator>
0022 #include <cstddef>
0023 #include <boost/current_function.hpp>
0024 #include <boost/type_traits/conditional.hpp>
0025 #include <boost/log/detail/config.hpp>
0026 #include <boost/log/utility/string_literal.hpp>
0027 #include <boost/log/utility/unique_identifier_name.hpp>
0028 #include <boost/log/utility/unused_variable.hpp>
0029 #include <boost/log/attributes/attribute.hpp>
0030 #include <boost/log/attributes/attribute_cast.hpp>
0031 #include <boost/log/detail/allocator_traits.hpp>
0032 #include <boost/log/detail/header.hpp>
0033
0034 #ifdef BOOST_HAS_PRAGMA_ONCE
0035 #pragma once
0036 #endif
0037
0038 namespace boost {
0039
0040 BOOST_LOG_OPEN_NAMESPACE
0041
0042 namespace attributes {
0043
0044 namespace aux {
0045
0046     //! Double-linked list node
0047     struct named_scope_list_node
0048     {
0049         mutable named_scope_list_node* _m_pPrev;
0050         mutable named_scope_list_node* _m_pNext;
0051
0052         named_scope_list_node() BOOST_NOEXCEPT { _m_pPrev = _m_pNext = this; }
0053     };
0054
0055 } // namespace aux
0056
0057 /*!
0058  * \brief The structure contains all information about a named scope
0059  *
0060  * The named scope entries are stored as elements of \c basic_named_scope_list container, which
0061  * in turn can be acquired either from the \c basic_named_scope attribute value or from a thread-local
0062  * instance.
0063  */
0064 struct named_scope_entry
0065     //! \cond
0066     : public aux::named_scope_list_node
0067     //! \endcond
0068 {
0069     /*!
0070      * \brief Scope entry type
0071      *
0072      * Describes scope name specifics
0073      */
0074     enum scope_name_type
0075     {
0076         general,   //!< The scope name contains some unstructured string that should not be interpreted by the library
0077         function   //!< The scope name contains a function signature
0078     };
0079
0080     /*!
0081      * The scope name (e.g. a function signature)
0082      */
0083     string_literal scope_name;
0084     /*!
0085      * The source file name
0086      */
0087     string_literal file_name;
0088     /*!
0089      * The line number in the source file
0090      */
0091     unsigned int line;
0092     /*!
0093      * The scope name type
0094      */
0095     scope_name_type type;
0096
0097     /*!
0098      * Initializing constructor
0099      *
0100      * \post <tt>scope_name == sn && file_name == fn && line == ln</tt>
0101      *
0102      * \b Throws: Nothing.
0103      */
0104     named_scope_entry(string_literal const& sn, string_literal const& fn, unsigned int ln, scope_name_type t = general) BOOST_NOEXCEPT :
0105         scope_name(sn),
0106         file_name(fn),
0107         line(ln),
0108         type(t)
0109     {
0110     }
0111 };
0112
0113 /*!
0114  * \brief The class implements the list of scopes
0115  *
0116  * The scope list provides a read-only access to a doubly-linked list of scopes.
0117  */
0118 class named_scope_list
0119     //! \cond
0120     : protected std::allocator< named_scope_entry >
0121     //! \endcond
0122 {
0123 public:
0124     //! Allocator type
0125     typedef std::allocator< named_scope_entry > allocator_type;
0126
0127     //  Standard types
0128     typedef log::aux::allocator_traits< allocator_type >::value_type value_type;
0129     typedef log::aux::allocator_traits< allocator_type >::size_type size_type;
0130     typedef log::aux::allocator_traits< allocator_type >::difference_type difference_type;
0131     typedef log::aux::allocator_traits< allocator_type >::pointer pointer;
0132     typedef log::aux::allocator_traits< allocator_type >::const_pointer const_pointer;
0133     typedef value_type& reference;
0134     typedef value_type const& const_reference;
0135
0136 #ifndef BOOST_LOG_DOXYGEN_PASS
0137
0138 protected:
0139     //! Iterator class
0140 #ifndef BOOST_LOG_NO_MEMBER_TEMPLATE_FRIENDS
0141     template< bool fConstV > class iter;
0142     template< bool fConstV > friend class iter;
0143 #endif
0144     template< bool fConstV >
0145     class iter
0146     {
0147         friend class iter< !fConstV >;
0148
0149     public:
0150         //  Standard typedefs
0151         typedef named_scope_list::difference_type difference_type;
0152         typedef named_scope_list::value_type value_type;
0153         typedef typename boost::conditional<
0154             fConstV,
0155             named_scope_list::const_reference,
0156             named_scope_list::reference
0157         >::type reference;
0158         typedef typename boost::conditional<
0159             fConstV,
0160             named_scope_list::const_pointer,
0161             named_scope_list::pointer
0162         >::type pointer;
0163         typedef std::bidirectional_iterator_tag iterator_category;
0164
0165     public:
0166         //  Constructors
0167         iter() : m_pNode(NULL) {}
0168         explicit iter(aux::named_scope_list_node* pNode) : m_pNode(pNode) {}
0169         iter(iter< false > const& that) : m_pNode(that.m_pNode) {}
0170
0171         //! Assignment
0172         template< bool f >
0173         iter& operator= (iter< f > const& that)
0174         {
0175             m_pNode = that.m_pNode;
0176             return *this;
0177         }
0178
0179         //  Comparison
0180         template< bool f >
0181         bool operator== (iter< f > const& that) const { return (m_pNode == that.m_pNode); }
0182         template< bool f >
0183         bool operator!= (iter< f > const& that) const { return (m_pNode != that.m_pNode); }
0184
0185         //  Modification
0186         iter& operator++ ()
0187         {
0188             m_pNode = m_pNode->_m_pNext;
0189             return *this;
0190         }
0191         iter& operator-- ()
0192         {
0193             m_pNode = m_pNode->_m_pPrev;
0194             return *this;
0195         }
0196         iter operator++ (int)
0197         {
0198             iter tmp(*this);
0199             m_pNode = m_pNode->_m_pNext;
0200             return tmp;
0201         }
0202         iter operator-- (int)
0203         {
0204             iter tmp(*this);
0205             m_pNode = m_pNode->_m_pPrev;
0206             return tmp;
0207         }
0208
0209         //  Dereferencing
0210         pointer operator-> () const { return static_cast< pointer >(m_pNode); }
0211         reference operator* () const { return *static_cast< pointer >(m_pNode); }
0212
0213     private:
0214         aux::named_scope_list_node* m_pNode;
0215     };
0216
0217 public:
0218     typedef iter< true > const_iterator;
0219     typedef iter< false > iterator;
0220     typedef std::reverse_iterator< const_iterator > const_reverse_iterator;
0221     typedef std::reverse_iterator< iterator > reverse_iterator;
0222
0223 protected:
0224     //! The root node of the container
0225     aux::named_scope_list_node m_RootNode;
0226     //! The size of the container
0227     size_type m_Size;
0228     //! The flag shows if the contained elements are dynamically allocated
0229     bool m_fNeedToDeallocate;
0230
0231 #else // BOOST_LOG_DOXYGEN_PASS
0232
0233     /*!
0234      * A constant iterator to the sequence of scopes. Complies to bidirectional iterator requirements.
0235      */
0236     typedef implementation_defined const_iterator;
0237     /*!
0238      * An iterator to the sequence of scopes. Complies to bidirectional iterator requirements.
0239      */
0240     typedef implementation_defined iterator;
0241     /*!
0242      * A constant reverse iterator to the sequence of scopes. Complies to bidirectional iterator requirements.
0243      */
0244     typedef implementation_defined const_reverse_iterator;
0245     /*!
0246      * A reverse iterator to the sequence of scopes. Complies to bidirectional iterator requirements.
0247      */
0248     typedef implementation_defined reverse_iterator;
0249
0250 #endif // BOOST_LOG_DOXYGEN_PASS
0251
0252 public:
0253     /*!
0254      * Default constructor
0255      *
0256      * \post <tt>empty() == true</tt>
0257      */
0258     named_scope_list() : m_Size(0), m_fNeedToDeallocate(false) {}
0259     /*!
0260      * Copy constructor
0261      *
0262      * \post <tt>std::equal(begin(), end(), that.begin()) == true</tt>
0263      */
0264     BOOST_LOG_API named_scope_list(named_scope_list const& that);
0265     /*!
0266      * Destructor. Destroys the stored entries.
0267      */
0268     BOOST_LOG_API ~named_scope_list();
0269
0270     /*!
0271      * Assignment operator
0272      *
0273      * \post <tt>std::equal(begin(), end(), that.begin()) == true</tt>
0274      */
0275     named_scope_list& operator= (named_scope_list const& that)
0276     {
0277         if (this != &that)
0278         {
0279             named_scope_list tmp(that);
0280             swap(tmp);
0281         }
0282         return *this;
0283     }
0284
0285     /*!
0286      * \return Constant iterator to the first element of the container.
0287      */
0288     const_iterator begin() const { return const_iterator(m_RootNode._m_pNext); }
0289     /*!
0290      * \return Constant iterator to the after-the-last element of the container.
0291      */
0292     const_iterator end() const { return const_iterator(const_cast< aux::named_scope_list_node* >(&m_RootNode)); }
0293     /*!
0294      * \return Constant iterator to the last element of the container.
0295      */
0296     const_reverse_iterator rbegin() const { return const_reverse_iterator(end()); }
0297     /*!
0298      * \return Constant iterator to the before-the-first element of the container.
0299      */
0300     const_reverse_iterator rend() const { return const_reverse_iterator(begin()); }
0301
0302     /*!
0303      * \return The number of elements in the container
0304      */
0305     size_type size() const { return m_Size; }
0306     /*!
0307      * \return true if the container is empty and false otherwise
0308      */
0309     bool empty() const { return (m_Size == 0); }
0310
0311     /*!
0312      * Swaps two instances of the container
0313      */
0314     BOOST_LOG_API void swap(named_scope_list& that);
0315
0316     /*!
0317      * \return Last pushed scope entry
0318      */
0319     const_reference back() const { return *rbegin(); }
0320     /*!
0321      * \return First pushed scope entry
0322      */
0323     const_reference front() const { return *begin(); }
0324 };
0325
0326 //! Stream output operator
0327 template< typename CharT, typename TraitsT >
0328 inline std::basic_ostream< CharT, TraitsT >& operator<< (std::basic_ostream< CharT, TraitsT >& strm, named_scope_list const& sl)
0329 {
0330     if (strm.good())
0331     {
0332         named_scope_list::const_iterator it = sl.begin(), end = sl.end();
0333         if (it != end)
0334         {
0335             strm << it->scope_name.c_str();
0336             for (++it; it != end; ++it)
0337                 strm << "->" << it->scope_name.c_str();
0338         }
0339     }
0340     return strm;
0341 }
0342
0343 /*!
0344  * \brief A class of an attribute that holds stack of named scopes of the current thread
0345  *
0346  * The basic_named_scope attribute is essentially a hook to the thread-specific instance of
0347  * scope list. This means that the attribute will generate different values if get_value is
0348  * called in different threads. The attribute generates value with stored type
0349  * <tt>basic_named_scope_list< CharT ></tt>.
0350  *
0351  * The attribute class can also be used to gain access to the scope stack instance, e.g. to
0352  * get its copy or to push or pop a scope entry. However, it is highly not recommended to
0353  * maintain scope list manually. Use \c BOOST_LOG_NAMED_SCOPE or \c BOOST_LOG_FUNCTION macros instead.
0354  */
0355 class BOOST_LOG_API named_scope :
0356     public attribute
0357 {
0358 public:
0359     //! Scope names stack (the attribute value type)
0360     typedef named_scope_list value_type;
0361     //! Scope entry
0362     typedef value_type::value_type scope_entry;
0363
0364     //! Sentry object class to automatically push and pop scopes
0365     struct sentry
0366     {
0367         /*!
0368          * Constructor. Pushes the specified scope to the end of the thread-local list of scopes.
0369          *
0370          * \param sn Scope name.
0371          * \param fn File name, in which the scope is located.
0372          * \param ln Line number in the file.
0373          * \param t Scope name type.
0374          */
0375         sentry(string_literal const& sn, string_literal const& fn, unsigned int ln, scope_entry::scope_name_type t = scope_entry::general) BOOST_NOEXCEPT :
0376             m_Entry(sn, fn, ln, t)
0377         {
0378             named_scope::push_scope(m_Entry);
0379         }
0380
0381         /*!
0382          * Destructor. Removes the last pushed scope from the thread-local list of scopes.
0383          */
0384         ~sentry() BOOST_NOEXCEPT
0385         {
0386             named_scope::pop_scope();
0387         }
0388
0389         BOOST_DELETED_FUNCTION(sentry(sentry const&))
0390         BOOST_DELETED_FUNCTION(sentry& operator= (sentry const&))
0391
0392     private:
0393         scope_entry m_Entry;
0394     };
0395
0396 private:
0397     //! Attribute implementation class
0398     struct BOOST_SYMBOL_VISIBLE impl;
0399
0400 public:
0401     /*!
0402      * Constructor. Creates an attribute.
0403      */
0404     named_scope();
0405     /*!
0406      * Constructor for casting support
0407      */
0408     explicit named_scope(cast_source const& source);
0409
0410     /*!
0411      * The method pushes the scope to the back of the current thread's scope list
0412      *
0413      * \b Throws: Nothing.
0414      */
0415     static void push_scope(scope_entry const& entry) BOOST_NOEXCEPT;
0416     /*!
0417      * The method pops the last pushed scope from the current thread's scope list
0418      *
0419      * \b Throws: Nothing.
0420      */
0421     static void pop_scope() BOOST_NOEXCEPT;
0422
0423     /*!
0424      *  \return The current thread's list of scopes
0425      *
0426      *  \note The returned reference is only valid until the current thread ends. The scopes in the
0427      *        returned container may change if the execution scope is changed (i.e. either \c push_scope
0428      *        or \c pop_scope is called). User has to copy the stack if he wants to keep it intact regardless
0429      *        of the execution scope.
0430      */
0431     static value_type const& get_scopes();
0432 };
0433
0434 } // namespace attributes
0435
0436 BOOST_LOG_CLOSE_NAMESPACE // namespace log
0437
0438 } // namespace boost
0439
0440 #ifndef BOOST_LOG_DOXYGEN_PASS
0441
0442 #define BOOST_LOG_NAMED_SCOPE_INTERNAL(var, name, file, line, type)\
0443     BOOST_LOG_UNUSED_VARIABLE(::boost::log::attributes::named_scope::sentry, var, (name, file, line, type));
0444
0445 #endif // BOOST_LOG_DOXYGEN_PASS
0446
0447 /*!
0448  * Macro for scope markup. The specified scope name is pushed to the end of the current thread scope list.
0449  */
0450 #define BOOST_LOG_NAMED_SCOPE(name)\
0451     BOOST_LOG_NAMED_SCOPE_INTERNAL(BOOST_LOG_UNIQUE_IDENTIFIER_NAME(_boost_log_named_scope_sentry_), name, __FILE__, __LINE__, ::boost::log::attributes::named_scope_entry::general)
0452
0453 /*!
0454  * Macro for function scope markup. The scope name is constructed with help of compiler and contains the current function signature.
0455  * The scope name is pushed to the end of the current thread scope list.
0456  *
0457  * Not all compilers have support for this macro. The exact form of the scope name may vary from one compiler to another.
0458  */
0459 #define BOOST_LOG_FUNCTION()\
0460     BOOST_LOG_NAMED_SCOPE_INTERNAL(BOOST_LOG_UNIQUE_IDENTIFIER_NAME(_boost_log_named_scope_sentry_), BOOST_CURRENT_FUNCTION, __FILE__, __LINE__, ::boost::log::attributes::named_scope_entry::function)
0461
0462 /*!
0463  * Macro for function scope markup. The scope name is constructed with help of compiler and contains the current function name. It may be shorter than what \c BOOST_LOG_FUNCTION macro produces.
0464  * The scope name is pushed to the end of the current thread scope list.
0465  *
0466  * Not all compilers have support for this macro. The exact form of the scope name may vary from one compiler to another.
0467  */
0468 #if defined(_MSC_VER) || defined(__GNUC__)
0469 #define BOOST_LOG_FUNC() BOOST_LOG_NAMED_SCOPE(__FUNCTION__)
0470 #else
0471 #define BOOST_LOG_FUNC() BOOST_LOG_FUNCTION()
0472 #endif
0473
0474 #include <boost/log/detail/footer.hpp>
0475
0476 #endif // BOOST_LOG_ATTRIBUTES_NAMED_SCOPE_HPP_INCLUDED_