ceph/src/boost/boost/log/attributes/named_scope.hpp

   1 /*
   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)
   6  */
   7 /*!
   8  * \file
   9  * \author Andrey Semashev
  10  * \date   24.06.2007
  11  *
  12  * The header contains implementation of named scope container and an attribute that allows to
  13  * put the named scope to log. A number of convenience macros are also provided.
  14  */
  15
  16 #ifndef BOOST_LOG_ATTRIBUTES_NAMED_SCOPE_HPP_INCLUDED_
  17 #define BOOST_LOG_ATTRIBUTES_NAMED_SCOPE_HPP_INCLUDED_
  18
  19 #include <ostream>
  20 #include <memory>
  21 #include <iterator>
  22 #include <cstddef>
  23 #include <boost/log/detail/config.hpp>
  24 #include <boost/current_function.hpp>
  25 #include <boost/type_traits/conditional.hpp>
  26 #include <boost/log/utility/string_literal.hpp>
  27 #include <boost/log/utility/unique_identifier_name.hpp>
  28 #include <boost/log/utility/unused_variable.hpp>
  29 #include <boost/log/attributes/attribute.hpp>
  30 #include <boost/log/attributes/attribute_cast.hpp>
  31 #include <boost/log/detail/allocator_traits.hpp>
  32 #include <boost/log/detail/header.hpp>
  33
  34 #ifdef BOOST_HAS_PRAGMA_ONCE
  35 #pragma once
  36 #endif
  37
  38 namespace boost {
  39
  40 BOOST_LOG_OPEN_NAMESPACE
  41
  42 namespace attributes {
  43
  44 namespace aux {
  45
  46     //! Double-linked list node
  47     struct named_scope_list_node
  48     {
  49         mutable named_scope_list_node* _m_pPrev;
  50         mutable named_scope_list_node* _m_pNext;
  51
  52         named_scope_list_node() BOOST_NOEXCEPT { _m_pPrev = _m_pNext = this; }
  53     };
  54
  55 } // namespace aux
  56
  57 /*!
  58  * \brief The structure contains all information about a named scope
  59  *
  60  * The named scope entries are stored as elements of \c basic_named_scope_list container, which
  61  * in turn can be acquired either from the \c basic_named_scope attribute value or from a thread-local
  62  * instance.
  63  */
  64 struct named_scope_entry
  65     //! \cond
  66     : public aux::named_scope_list_node
  67     //! \endcond
  68 {
  69     /*!
  70      * \brief Scope entry type
  71      *
  72      * Describes scope name specifics
  73      */
  74     enum scope_name_type
  75     {
  76         general,   //!< The scope name contains some unstructured string that should not be interpreted by the library
  77         function   //!< The scope name contains a function signature
  78     };
  79
  80     /*!
  81      * The scope name (e.g. a function signature)
  82      */
  83     string_literal scope_name;
  84     /*!
  85      * The source file name
  86      */
  87     string_literal file_name;
  88     /*!
  89      * The line number in the source file
  90      */
  91     unsigned int line;
  92     /*!
  93      * The scope name type
  94      */
  95     scope_name_type type;
  96
  97     /*!
  98      * Initializing constructor
  99      *
 100      * \post <tt>scope_name == sn && file_name == fn && line == ln</tt>
 101      *
 102      * \b Throws: Nothing.
 103      */
 104     named_scope_entry(string_literal const& sn, string_literal const& fn, unsigned int ln, scope_name_type t = general) BOOST_NOEXCEPT :
 105         scope_name(sn),
 106         file_name(fn),
 107         line(ln),
 108         type(t)
 109     {
 110     }
 111 };
 112
 113 /*!
 114  * \brief The class implements the list of scopes
 115  *
 116  * The scope list provides a read-only access to a doubly-linked list of scopes.
 117  */
 118 class named_scope_list
 119     //! \cond
 120     : protected std::allocator< named_scope_entry >
 121     //! \endcond
 122 {
 123 public:
 124     //! Allocator type
 125     typedef std::allocator< named_scope_entry > allocator_type;
 126
 127     //  Standard types
 128     typedef log::aux::allocator_traits< allocator_type >::value_type value_type;
 129     typedef log::aux::allocator_traits< allocator_type >::size_type size_type;
 130     typedef log::aux::allocator_traits< allocator_type >::difference_type difference_type;
 131     typedef log::aux::allocator_traits< allocator_type >::pointer pointer;
 132     typedef log::aux::allocator_traits< allocator_type >::const_pointer const_pointer;
 133     typedef value_type& reference;
 134     typedef value_type const& const_reference;
 135
 136 #ifndef BOOST_LOG_DOXYGEN_PASS
 137
 138 protected:
 139     //! Iterator class
 140 #ifndef BOOST_LOG_NO_MEMBER_TEMPLATE_FRIENDS
 141     template< bool fConstV > class iter;
 142     template< bool fConstV > friend class iter;
 143 #endif
 144     template< bool fConstV >
 145     class iter
 146     {
 147         friend class iter< !fConstV >;
 148
 149     public:
 150         //  Standard typedefs
 151         typedef named_scope_list::difference_type difference_type;
 152         typedef named_scope_list::value_type value_type;
 153         typedef typename boost::conditional<
 154             fConstV,
 155             named_scope_list::const_reference,
 156             named_scope_list::reference
 157         >::type reference;
 158         typedef typename boost::conditional<
 159             fConstV,
 160             named_scope_list::const_pointer,
 161             named_scope_list::pointer
 162         >::type pointer;
 163         typedef std::bidirectional_iterator_tag iterator_category;
 164
 165     public:
 166         //  Constructors
 167         iter() : m_pNode(NULL) {}
 168         explicit iter(aux::named_scope_list_node* pNode) : m_pNode(pNode) {}
 169         iter(iter< false > const& that) : m_pNode(that.m_pNode) {}
 170
 171         //! Assignment
 172         template< bool f >
 173         iter& operator= (iter< f > const& that)
 174         {
 175             m_pNode = that.m_pNode;
 176             return *this;
 177         }
 178
 179         //  Comparison
 180         template< bool f >
 181         bool operator== (iter< f > const& that) const { return (m_pNode == that.m_pNode); }
 182         template< bool f >
 183         bool operator!= (iter< f > const& that) const { return (m_pNode != that.m_pNode); }
 184
 185         //  Modification
 186         iter& operator++ ()
 187         {
 188             m_pNode = m_pNode->_m_pNext;
 189             return *this;
 190         }
 191         iter& operator-- ()
 192         {
 193             m_pNode = m_pNode->_m_pPrev;
 194             return *this;
 195         }
 196         iter operator++ (int)
 197         {
 198             iter tmp(*this);
 199             m_pNode = m_pNode->_m_pNext;
 200             return tmp;
 201         }
 202         iter operator-- (int)
 203         {
 204             iter tmp(*this);
 205             m_pNode = m_pNode->_m_pPrev;
 206             return tmp;
 207         }
 208
 209         //  Dereferencing
 210         pointer operator-> () const { return static_cast< pointer >(m_pNode); }
 211         reference operator* () const { return *static_cast< pointer >(m_pNode); }
 212
 213     private:
 214         aux::named_scope_list_node* m_pNode;
 215     };
 216
 217 public:
 218     typedef iter< true > const_iterator;
 219     typedef iter< false > iterator;
 220     typedef std::reverse_iterator< const_iterator > const_reverse_iterator;
 221     typedef std::reverse_iterator< iterator > reverse_iterator;
 222
 223 protected:
 224     //! The root node of the container
 225     aux::named_scope_list_node m_RootNode;
 226     //! The size of the container
 227     size_type m_Size;
 228     //! The flag shows if the contained elements are dynamically allocated
 229     bool m_fNeedToDeallocate;
 230
 231 #else // BOOST_LOG_DOXYGEN_PASS
 232
 233     /*!
 234      * A constant iterator to the sequence of scopes. Complies to bidirectional iterator requirements.
 235      */
 236     typedef implementation_defined const_iterator;
 237     /*!
 238      * An iterator to the sequence of scopes. Complies to bidirectional iterator requirements.
 239      */
 240     typedef implementation_defined iterator;
 241     /*!
 242      * A constant reverse iterator to the sequence of scopes. Complies to bidirectional iterator requirements.
 243      */
 244     typedef implementation_defined const_reverse_iterator;
 245     /*!
 246      * A reverse iterator to the sequence of scopes. Complies to bidirectional iterator requirements.
 247      */
 248     typedef implementation_defined reverse_iterator;
 249
 250 #endif // BOOST_LOG_DOXYGEN_PASS
 251
 252 public:
 253     /*!
 254      * Default constructor
 255      *
 256      * \post <tt>empty() == true</tt>
 257      */
 258     named_scope_list() : m_Size(0), m_fNeedToDeallocate(false) {}
 259     /*!
 260      * Copy constructor
 261      *
 262      * \post <tt>std::equal(begin(), end(), that.begin()) == true</tt>
 263      */
 264     BOOST_LOG_API named_scope_list(named_scope_list const& that);
 265     /*!
 266      * Destructor. Destroys the stored entries.
 267      */
 268     BOOST_LOG_API ~named_scope_list();
 269
 270     /*!
 271      * Assignment operator
 272      *
 273      * \post <tt>std::equal(begin(), end(), that.begin()) == true</tt>
 274      */
 275     named_scope_list& operator= (named_scope_list const& that)
 276     {
 277         if (this != &that)
 278         {
 279             named_scope_list tmp(that);
 280             swap(tmp);
 281         }
 282         return *this;
 283     }
 284
 285     /*!
 286      * \return Constant iterator to the first element of the container.
 287      */
 288     const_iterator begin() const { return const_iterator(m_RootNode._m_pNext); }
 289     /*!
 290      * \return Constant iterator to the after-the-last element of the container.
 291      */
 292     const_iterator end() const { return const_iterator(const_cast< aux::named_scope_list_node* >(&m_RootNode)); }
 293     /*!
 294      * \return Constant iterator to the last element of the container.
 295      */
 296     const_reverse_iterator rbegin() const { return const_reverse_iterator(end()); }
 297     /*!
 298      * \return Constant iterator to the before-the-first element of the container.
 299      */
 300     const_reverse_iterator rend() const { return const_reverse_iterator(begin()); }
 301
 302     /*!
 303      * \return The number of elements in the container
 304      */
 305     size_type size() const { return m_Size; }
 306     /*!
 307      * \return true if the container is empty and false otherwise
 308      */
 309     bool empty() const { return (m_Size == 0); }
 310
 311     /*!
 312      * Swaps two instances of the container
 313      */
 314     BOOST_LOG_API void swap(named_scope_list& that);
 315
 316     /*!
 317      * \return Last pushed scope entry
 318      */
 319     const_reference back() const { return *rbegin(); }
 320     /*!
 321      * \return First pushed scope entry
 322      */
 323     const_reference front() const { return *begin(); }
 324 };
 325
 326 //! Stream output operator
 327 template< typename CharT, typename TraitsT >
 328 inline std::basic_ostream< CharT, TraitsT >& operator<< (std::basic_ostream< CharT, TraitsT >& strm, named_scope_list const& sl)
 329 {
 330     if (strm.good())
 331     {
 332         named_scope_list::const_iterator it = sl.begin(), end = sl.end();
 333         if (it != end)
 334         {
 335             strm << it->scope_name.c_str();
 336             for (++it; it != end; ++it)
 337                 strm << "->" << it->scope_name.c_str();
 338         }
 339     }
 340     return strm;
 341 }
 342
 343 /*!
 344  * \brief A class of an attribute that holds stack of named scopes of the current thread
 345  *
 346  * The basic_named_scope attribute is essentially a hook to the thread-specific instance of
 347  * scope list. This means that the attribute will generate different values if get_value is
 348  * called in different threads. The attribute generates value with stored type
 349  * <tt>basic_named_scope_list< CharT ></tt>.
 350  *
 351  * The attribute class can also be used to gain access to the scope stack instance, e.g. to
 352  * get its copy or to push or pop a scope entry. However, it is highly not recommended to
 353  * maintain scope list manually. Use \c BOOST_LOG_NAMED_SCOPE or \c BOOST_LOG_FUNCTION macros instead.
 354  */
 355 class BOOST_LOG_API named_scope :
 356     public attribute
 357 {
 358 public:
 359     //! Scope names stack (the attribute value type)
 360     typedef named_scope_list value_type;
 361     //! Scope entry
 362     typedef value_type::value_type scope_entry;
 363
 364     //! Sentry object class to automatically push and pop scopes
 365     struct sentry
 366     {
 367         /*!
 368          * Constructor. Pushes the specified scope to the end of the thread-local list of scopes.
 369          *
 370          * \param sn Scope name.
 371          * \param fn File name, in which the scope is located.
 372          * \param ln Line number in the file.
 373          */
 374         sentry(string_literal const& sn, string_literal const& fn, unsigned int ln, scope_entry::scope_name_type t = scope_entry::general) BOOST_NOEXCEPT :
 375             m_Entry(sn, fn, ln, t)
 376         {
 377             named_scope::push_scope(m_Entry);
 378         }
 379
 380         /*!
 381          * Destructor. Removes the last pushed scope from the thread-local list of scopes.
 382          */
 383         ~sentry() BOOST_NOEXCEPT
 384         {
 385             named_scope::pop_scope();
 386         }
 387
 388         BOOST_DELETED_FUNCTION(sentry(sentry const&))
 389         BOOST_DELETED_FUNCTION(sentry& operator= (sentry const&))
 390
 391     private:
 392         scope_entry m_Entry;
 393     };
 394
 395 private:
 396     //! Attribute implementation class
 397     struct BOOST_SYMBOL_VISIBLE impl;
 398
 399 public:
 400     /*!
 401      * Constructor. Creates an attribute.
 402      */
 403     named_scope();
 404     /*!
 405      * Constructor for casting support
 406      */
 407     explicit named_scope(cast_source const& source);
 408
 409     /*!
 410      * The method pushes the scope to the back of the current thread's scope list
 411      *
 412      * \b Throws: Nothing.
 413      */
 414     static void push_scope(scope_entry const& entry) BOOST_NOEXCEPT;
 415     /*!
 416      * The method pops the last pushed scope from the current thread's scope list
 417      *
 418      * \b Throws: Nothing.
 419      */
 420     static void pop_scope() BOOST_NOEXCEPT;
 421
 422     /*!
 423      *  \return The current thread's list of scopes
 424      *
 425      *  \note The returned reference is only valid until the current thread ends. The scopes in the
 426      *        returned container may change if the execution scope is changed (i.e. either \c push_scope
 427      *        or \c pop_scope is called). User has to copy the stack if he wants to keep it intact regardless
 428      *        of the execution scope.
 429      */
 430     static value_type const& get_scopes();
 431 };
 432
 433 } // namespace attributes
 434
 435 BOOST_LOG_CLOSE_NAMESPACE // namespace log
 436
 437 } // namespace boost
 438
 439 #ifndef BOOST_LOG_DOXYGEN_PASS
 440
 441 #define BOOST_LOG_NAMED_SCOPE_INTERNAL(var, name, file, line, type)\
 442     BOOST_LOG_UNUSED_VARIABLE(::boost::log::attributes::named_scope::sentry, var, (name, file, line, type));
 443
 444 #endif // BOOST_LOG_DOXYGEN_PASS
 445
 446 /*!
 447  * Macro for scope markup. The specified scope name is pushed to the end of the current thread scope list.
 448  */
 449 #define BOOST_LOG_NAMED_SCOPE(name)\
 450     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)
 451
 452 /*!
 453  * Macro for function scope markup. The scope name is constructed with help of compiler and contains the current function signature.
 454  * The scope name is pushed to the end of the current thread scope list.
 455  *
 456  * Not all compilers have support for this macro. The exact form of the scope name may vary from one compiler to another.
 457  */
 458 #define BOOST_LOG_FUNCTION()\
 459     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)
 460
 461 /*!
 462  * 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.
 463  * The scope name is pushed to the end of the current thread scope list.
 464  *
 465  * Not all compilers have support for this macro. The exact form of the scope name may vary from one compiler to another.
 466  */
 467 #if defined(_MSC_VER) || defined(__GNUC__)
 468 #define BOOST_LOG_FUNC() BOOST_LOG_NAMED_SCOPE(__FUNCTION__)
 469 #else
 470 #define BOOST_LOG_FUNC() BOOST_LOG_FUNCTION()
 471 #endif
 472
 473 #include <boost/log/detail/footer.hpp>
 474
 475 #endif // BOOST_LOG_ATTRIBUTES_NAMED_SCOPE_HPP_INCLUDED_