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 */ open_record(BOOST_RV_REF (attribute_value_set)source_attributes)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 */ push_record(BOOST_RV_REF (record)rec)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_ 330