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/current_function.hpp> 24 #include <boost/type_traits/conditional.hpp> 25 #include <boost/log/detail/config.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 * impl(value_type const & value)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_ 476