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
named_scope_list_nodeboost::attributes::aux::named_scope_list_node52 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 */
named_scope_entryboost::attributes::named_scope_entry104 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
iter()167 iter() : m_pNode(NULL) {}
iter(aux::named_scope_list_node * pNode)168 explicit iter(aux::named_scope_list_node* pNode) : m_pNode(pNode) {}
iter(iter<false> const & that)169 iter(iter< false > const& that) : m_pNode(that.m_pNode) {}
170
171 //! Assignment
172 template< bool f >
operator =(iter<f> const & that)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 >
operator ==(iter<f> const & that) const181 bool operator== (iter< f > const& that) const { return (m_pNode == that.m_pNode); }
182 template< bool f >
operator !=(iter<f> const & that) const183 bool operator!= (iter< f > const& that) const { return (m_pNode != that.m_pNode); }
184
185 // Modification
operator ++()186 iter& operator++ ()
187 {
188 m_pNode = m_pNode->_m_pNext;
189 return *this;
190 }
operator --()191 iter& operator-- ()
192 {
193 m_pNode = m_pNode->_m_pPrev;
194 return *this;
195 }
operator ++(int)196 iter operator++ (int)
197 {
198 iter tmp(*this);
199 m_pNode = m_pNode->_m_pNext;
200 return tmp;
201 }
operator --(int)202 iter operator-- (int)
203 {
204 iter tmp(*this);
205 m_pNode = m_pNode->_m_pPrev;
206 return tmp;
207 }
208
209 // Dereferencing
operator ->() const210 pointer operator-> () const { return static_cast< pointer >(m_pNode); }
operator *() const211 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 */
named_scope_list()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 */
operator =(named_scope_list const & that)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 */
begin() const288 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 */
end() const292 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 */
rbegin() const296 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 */
rend() const300 const_reverse_iterator rend() const { return const_reverse_iterator(begin()); }
301
302 /*!
303 * \return The number of elements in the container
304 */
size() const305 size_type size() const { return m_Size; }
306 /*!
307 * \return true if the container is empty and false otherwise
308 */
empty() const309 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 */
back() const319 const_reference back() const { return *rbegin(); }
320 /*!
321 * \return First pushed scope entry
322 */
front() const323 const_reference front() const { return *begin(); }
324 };
325
326 //! Stream output operator
327 template< typename CharT, typename TraitsT >
operator <<(std::basic_ostream<CharT,TraitsT> & strm,named_scope_list const & sl)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 */
sentryboost::attributes::named_scope::sentry374 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 */
~sentryboost::attributes::named_scope::sentry383 ~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