ceph/src/boost/boost/log/core/core.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   core/core.hpp
   9  * \author Andrey Semashev
  10  * \date   19.04.2007
  11  *
  12  * This header contains logging core class definition.
  13  */
  14
  15 #ifndef BOOST_LOG_CORE_CORE_HPP_INCLUDED_
  16 #define BOOST_LOG_CORE_CORE_HPP_INCLUDED_
  17
  18 #include <utility>
  19 #include <boost/smart_ptr/shared_ptr.hpp>
  20 #include <boost/move/core.hpp>
  21 #include <boost/log/detail/config.hpp>
  22 #include <boost/log/detail/light_function.hpp>
  23 #include <boost/log/core/record.hpp>
  24 #include <boost/log/attributes/attribute_set.hpp>
  25 #include <boost/log/attributes/attribute_name.hpp>
  26 #include <boost/log/attributes/attribute.hpp>
  27 #include <boost/log/attributes/attribute_value_set.hpp>
  28 #include <boost/log/expressions/filter.hpp>
  29 #include <boost/log/detail/header.hpp>
  30
  31 #ifdef BOOST_HAS_PRAGMA_ONCE
  32 #pragma once
  33 #endif
  34
  35 namespace boost {
  36
  37 BOOST_LOG_OPEN_NAMESPACE
  38
  39 #ifndef BOOST_LOG_DOXYGEN_PASS
  40
  41 namespace sinks {
  42
  43 class sink;
  44
  45 } // namespace sinks
  46
  47 #endif // BOOST_LOG_DOXYGEN_PASS
  48
  49 class core;
  50
  51 typedef shared_ptr< core > core_ptr;
  52
  53 /*!
  54  * \brief Logging library core class
  55  *
  56  * The logging core is used to interconnect log sources and sinks. It also provides
  57  * a number of basic features, like global filtering and global and thread-specific attribute storage.
  58  *
  59  * The logging core is a singleton. Users can acquire the core instance by calling the static method <tt>get</tt>.
  60  */
  61 class core
  62 {
  63 public:
  64     //! Exception handler function type
  65     typedef boost::log::aux::light_function< void () > exception_handler_type;
  66
  67 private:
  68     //! Implementation type
  69     struct implementation;
  70     friend struct implementation;
  71
  72 private:
  73     //! A pointer to the implementation
  74     implementation* m_impl;
  75
  76 private:
  77     //! \cond
  78     core();
  79     //! \endcond
  80
  81 public:
  82     /*!
  83      * Destructor. Destroys the core, releases any sinks and attributes that were registered.
  84      */
  85     ~core();
  86
  87     /*!
  88      * \return The method returns a pointer to the logging core singleton instance.
  89      */
  90     BOOST_LOG_API static core_ptr get();
  91
  92     /*!
  93      * The method enables or disables logging.
  94      *
  95      * Setting this status to \c false allows you to completely wipe out any logging activity, including
  96      * filtering and generation of attribute values. It is useful if you want to completely disable logging
  97      * in a running application. The state of logging does not alter any other properties of the logging
  98      * library, such as filters or sinks, so you can enable logging with the very same settings that you had
  99      * when the logging was disabled.
 100      * This feature may also be useful if you want to perform major changes to logging configuration and
 101      * don't want your application to block on opening or pushing a log record.
 102      *
 103      * By default logging is enabled.
 104      *
 105      * \param enabled The actual flag of logging activity.
 106      * \return The previous value of enabled/disabled logging flag
 107      */
 108     BOOST_LOG_API bool set_logging_enabled(bool enabled = true);
 109     /*!
 110      * The method allows to detect if logging is enabled. See the comment for \c set_logging_enabled.
 111      */
 112     BOOST_LOG_API bool get_logging_enabled() const;
 113
 114     /*!
 115      * The method sets the global logging filter. The filter is applied to every log record that is processed.
 116      *
 117      * \param filter The filter function object to be installed.
 118      */
 119     BOOST_LOG_API void set_filter(filter const& filter);
 120     /*!
 121      * The method removes the global logging filter. All log records are passed to sinks without global filtering applied.
 122      */
 123     BOOST_LOG_API void reset_filter();
 124
 125     /*!
 126      * The method adds a new sink. The sink is included into logging process immediately after being added and until being removed.
 127      * No sink can be added more than once at the same time. If the sink is already registered, the call is ignored.
 128      *
 129      * \param s The sink to be registered.
 130      */
 131     BOOST_LOG_API void add_sink(shared_ptr< sinks::sink > const& s);
 132     /*!
 133      * The method removes the sink from the output. The sink will not receive any log records after removal.
 134      * The call has no effect if the sink is not registered.
 135      *
 136      * \param s The sink to be unregistered.
 137      */
 138     BOOST_LOG_API void remove_sink(shared_ptr< sinks::sink > const& s);
 139     /*!
 140      * The method removes all registered sinks from the output. The sinks will not receive any log records after removal.
 141      */
 142     BOOST_LOG_API void remove_all_sinks();
 143
 144     /*!
 145      * The method performs flush on all registered sinks.
 146      *
 147      * \note This method may take long time to complete as it may block until all sinks manage to process all buffered log records.
 148      *       The call will also block all logging attempts until the operation completes.
 149      */
 150     BOOST_LOG_API void flush();
 151
 152     /*!
 153      * The method adds an attribute to the global attribute set. The attribute will be implicitly added to every log record.
 154      *
 155      * \param name The attribute name.
 156      * \param attr The attribute factory.
 157      * \return A pair of values. If the second member is \c true, then the attribute is added and the first member points to the
 158      *         attribute. Otherwise the attribute was not added and the first member points to the attribute that prevents
 159      *         addition.
 160      */
 161     BOOST_LOG_API std::pair< attribute_set::iterator, bool > add_global_attribute(attribute_name const& name, attribute const& attr);
 162     /*!
 163      * The method removes an attribute from the global attribute set.
 164      *
 165      * \pre The attribute was added with the \c add_global_attribute call.
 166      * \post The attribute is no longer registered as a global attribute. The iterator is invalidated after removal.
 167      *
 168      * \param it Iterator to the previously added attribute.
 169      */
 170     BOOST_LOG_API void remove_global_attribute(attribute_set::iterator it);
 171
 172     /*!
 173      * The method returns a copy of the complete set of currently registered global attributes.
 174      */
 175     BOOST_LOG_API attribute_set get_global_attributes() const;
 176     /*!
 177      * The method replaces the complete set of currently registered global attributes with the provided set.
 178      *
 179      * \note The method invalidates all iterators and references that may have been returned
 180      *       from the \c add_global_attribute method.
 181      *
 182      * \param attrs The set of attributes to be installed.
 183      */
 184     BOOST_LOG_API void set_global_attributes(attribute_set const& attrs);
 185
 186     /*!
 187      * The method adds an attribute to the thread-specific attribute set. The attribute will be implicitly added to
 188      * every log record made in the current thread.
 189      *
 190      * \note In single-threaded build the effect is the same as adding the attribute globally. This, however, does
 191      *       not imply that iterators to thread-specific and global attributes are interchangeable.
 192      *
 193      * \param name The attribute name.
 194      * \param attr The attribute factory.
 195      * \return A pair of values. If the second member is \c true, then the attribute is added and the first member points to the
 196      *         attribute. Otherwise the attribute was not added and the first member points to the attribute that prevents
 197      *         addition.
 198      */
 199     BOOST_LOG_API std::pair< attribute_set::iterator, bool > add_thread_attribute(attribute_name const& name, attribute const& attr);
 200     /*!
 201      * The method removes an attribute from the thread-specific attribute set.
 202      *
 203      * \pre The attribute was added with the \c add_thread_attribute call.
 204      * \post The attribute is no longer registered as a thread-specific attribute. The iterator is invalidated after removal.
 205      *
 206      * \param it Iterator to the previously added attribute.
 207      */
 208     BOOST_LOG_API void remove_thread_attribute(attribute_set::iterator it);
 209
 210     /*!
 211      * The method returns a copy of the complete set of currently registered thread-specific attributes.
 212      */
 213     BOOST_LOG_API attribute_set get_thread_attributes() const;
 214     /*!
 215      * The method replaces the complete set of currently registered thread-specific attributes with the provided set.
 216      *
 217      * \note The method invalidates all iterators and references that may have been returned
 218      *       from the \c add_thread_attribute method.
 219      *
 220      * \param attrs The set of attributes to be installed.
 221      */
 222     BOOST_LOG_API void set_thread_attributes(attribute_set const& attrs);
 223
 224     /*!
 225      * The method sets exception handler function. The function will be called with no arguments
 226      * in case if an exception occurs during either \c open_record or \c push_record method
 227      * execution. Since exception handler is called from a \c catch statement, the exception
 228      * can be rethrown in order to determine its type.
 229      *
 230      * By default no handler is installed, thus any exception is propagated as usual.
 231      *
 232      * \sa See also: <tt>utility/exception_handler.hpp</tt>
 233      * \param handler Exception handling function
 234      *
 235      * \note The exception handler can be invoked in several threads concurrently.
 236      *       Thread interruptions are not affected by exception handlers.
 237      */
 238     BOOST_LOG_API void set_exception_handler(exception_handler_type const& handler);
 239
 240     /*!
 241      * The method attempts to open a new record to be written. While attempting to open a log record all filtering is applied.
 242      * A successfully opened record can be pushed further to sinks by calling the \c push_record method or simply destroyed by
 243      * destroying the returned object.
 244      *
 245      * More than one open records are allowed, such records exist independently. All attribute values are acquired during opening
 246      * the record and do not interact between records.
 247      *
 248      * The returned records can be copied, however, they must not be passed between different threads.
 249      *
 250      * \param source_attributes The set of source-specific attributes to be attached to the record to be opened.
 251      * \return A valid log record if the record is opened, an invalid record object if not (e.g. because it didn't pass filtering).
 252      *
 253      * \b Throws: If an exception handler is installed, only throws if the handler throws. Otherwise may
 254      *            throw if one of the sinks throws, or some system resource limitation is reached.
 255      */
 256     BOOST_LOG_API record open_record(attribute_set const& source_attributes);
 257     /*!
 258      * The method attempts to open a new record to be written. While attempting to open a log record all filtering is applied.
 259      * A successfully opened record can be pushed further to sinks by calling the \c push_record method or simply destroyed by
 260      * destroying the returned object.
 261      *
 262      * More than one open records are allowed, such records exist independently. All attribute values are acquired during opening
 263      * the record and do not interact between records.
 264      *
 265      * The returned records can be copied, however, they must not be passed between different threads.
 266      *
 267      * \param source_attributes The set of source-specific attribute values to be attached to the record to be opened.
 268      * \return A valid log record if the record is opened, an invalid record object if not (e.g. because it didn't pass filtering).
 269      *
 270      * \b Throws: If an exception handler is installed, only throws if the handler throws. Otherwise may
 271      *            throw if one of the sinks throws, or some system resource limitation is reached.
 272      */
 273     BOOST_LOG_API record open_record(attribute_value_set const& source_attributes);
 274     /*!
 275      * The method attempts to open a new record to be written. While attempting to open a log record all filtering is applied.
 276      * A successfully opened record can be pushed further to sinks by calling the \c push_record method or simply destroyed by
 277      * destroying the returned object.
 278      *
 279      * More than one open records are allowed, such records exist independently. All attribute values are acquired during opening
 280      * the record and do not interact between records.
 281      *
 282      * The returned records can be copied, however, they must not be passed between different threads.
 283      *
 284      * \param source_attributes The set of source-specific attribute values to be attached to the record to be opened. The contents
 285      *                          of this container are unspecified after this call.
 286      * \return A valid log record if the record is opened, an invalid record object if not (e.g. because it didn't pass filtering).
 287      *
 288      * \b Throws: If an exception handler is installed, only throws if the handler throws. Otherwise may
 289      *            throw if one of the sinks throws, or some system resource limitation is reached.
 290      */
 291     BOOST_FORCEINLINE record open_record(BOOST_RV_REF(attribute_value_set) source_attributes)
 292     {
 293         return open_record_move(static_cast< attribute_value_set& >(source_attributes));
 294     }
 295
 296     /*!
 297      * The method pushes the record to sinks. The record is moved from in the process.
 298      *
 299      * \pre <tt>!!rec == true</tt>
 300      * \post <tt>!rec == true</tt>
 301      * \param rec A previously successfully opened log record.
 302      *
 303      * \b Throws: If an exception handler is installed, only throws if the handler throws. Otherwise may
 304      *            throw if one of the sinks throws.
 305      */
 306     BOOST_FORCEINLINE void push_record(BOOST_RV_REF(record) rec)
 307     {
 308         push_record_move(static_cast< record& >(rec));
 309     }
 310
 311     BOOST_DELETED_FUNCTION(core(core const&))
 312     BOOST_DELETED_FUNCTION(core& operator= (core const&))
 313
 314 #ifndef BOOST_LOG_DOXYGEN_PASS
 315 private:
 316     //! Opens log record. This function is mostly needed to maintain ABI stable between C++03 and C++11.
 317     BOOST_LOG_API record open_record_move(attribute_value_set& source_attributes);
 318     //! The method pushes the record to sinks.
 319     BOOST_LOG_API void push_record_move(record& rec);
 320 #endif // BOOST_LOG_DOXYGEN_PASS
 321 };
 322
 323 BOOST_LOG_CLOSE_NAMESPACE // namespace log
 324
 325 } // namespace boost
 326
 327 #include <boost/log/detail/footer.hpp>
 328
 329 #endif // BOOST_LOG_CORE_CORE_HPP_INCLUDED_