Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

Class core

boost::log::core — Logging library core class.

Synopsis

// In header: <boost/log/core/core.hpp>


class core {
public:
  // types
  typedef unspecified exception_handler_type;  // Exception handler function type. 

  // construct/copy/destruct
  core(core const &) = delete;
  core & operator=(core const &) = delete;
  ~core();

  // public member functions
  bool set_logging_enabled(bool = true);
  bool get_logging_enabled() const;
  void set_filter(filter const &);
  void reset_filter();
  void add_sink(shared_ptr< sinks::sink > const &);
  void remove_sink(shared_ptr< sinks::sink > const &);
  void remove_all_sinks();
  void flush();
  std::pair< attribute_set::iterator, bool > 
  add_global_attribute(attribute_name const &, attribute const &);
  void remove_global_attribute(attribute_set::iterator);
  attribute_set get_global_attributes() const;
  void set_global_attributes(attribute_set const &);
  std::pair< attribute_set::iterator, bool > 
  add_thread_attribute(attribute_name const &, attribute const &);
  void remove_thread_attribute(attribute_set::iterator);
  attribute_set get_thread_attributes() const;
  void set_thread_attributes(attribute_set const &);
  void set_exception_handler(exception_handler_type const &);
  record open_record(attribute_set const &);
  record open_record(attribute_value_set const &);
  record open_record(attribute_value_set &&);
  void push_record(record &&);

  // public static functions
  static core_ptr get();
};

Description

The logging core is used to interconnect log sources and sinks. It also provides a number of basic features, like global filtering and global and thread-specific attribute storage.

The logging core is a singleton. Users can acquire the core instance by calling the static method get.

core public construct/copy/destruct

  1. core(core const &) = delete;
  2. core & operator=(core const &) = delete;
  3. ~core();

    Destructor. Destroys the core, releases any sinks and attributes that were registered.

core public member functions

  1. bool set_logging_enabled(bool enabled = true);

    The method enables or disables logging.

    Setting this status to false allows you to completely wipe out any logging activity, including filtering and generation of attribute values. It is useful if you want to completely disable logging in a running application. The state of logging does not alter any other properties of the logging library, such as filters or sinks, so you can enable logging with the very same settings that you had when the logging was disabled. This feature may also be useful if you want to perform major changes to logging configuration and don't want your application to block on opening or pushing a log record.

    By default logging is enabled.

    Parameters:

    enabled

    The actual flag of logging activity.

    Returns:

    The previous value of enabled/disabled logging flag

  2. bool get_logging_enabled() const;

    The method allows to detect if logging is enabled. See the comment for set_logging_enabled.

  3. void set_filter(filter const & filter);

    The method sets the global logging filter. The filter is applied to every log record that is processed.

    Parameters:

    filter

    The filter function object to be installed.

  4. void reset_filter();

    The method removes the global logging filter. All log records are passed to sinks without global filtering applied.

  5. void add_sink(shared_ptr< sinks::sink > const & s);

    The method adds a new sink. The sink is included into logging process immediately after being added and until being removed. No sink can be added more than once at the same time. If the sink is already registered, the call is ignored.

    Parameters:

    s

    The sink to be registered.

  6. void remove_sink(shared_ptr< sinks::sink > const & s);

    The method removes the sink from the output. The sink will not receive any log records after removal. The call has no effect if the sink is not registered.

    Parameters:

    s

    The sink to be unregistered.

  7. void remove_all_sinks();

    The method removes all registered sinks from the output. The sinks will not receive any log records after removal.

  8. void flush();

    The method performs flush on all registered sinks.

    [Note] Note

    This method may take long time to complete as it may block until all sinks manage to process all buffered log records. The call will also block all logging attempts until the operation completes.

  9. std::pair< attribute_set::iterator, bool > 
    add_global_attribute(attribute_name const & name, attribute const & attr);

    The method adds an attribute to the global attribute set. The attribute will be implicitly added to every log record.

    Parameters:

    attr

    The attribute factory.

    name

    The attribute name.

    Returns:

    A pair of values. If the second member is true, then the attribute is added and the first member points to the attribute. Otherwise the attribute was not added and the first member points to the attribute that prevents addition.

  10. void remove_global_attribute(attribute_set::iterator it);

    The method removes an attribute from the global attribute set.

    Parameters:

    it

    Iterator to the previously added attribute.

    Requires:

    The attribute was added with the add_global_attribute call.

    Postconditions:

    The attribute is no longer registered as a global attribute. The iterator is invalidated after removal.

  11. attribute_set get_global_attributes() const;

    The method returns a copy of the complete set of currently registered global attributes.

  12. void set_global_attributes(attribute_set const & attrs);

    The method replaces the complete set of currently registered global attributes with the provided set.

    [Note] Note

    The method invalidates all iterators and references that may have been returned from the add_global_attribute method.

    Parameters:

    attrs

    The set of attributes to be installed.

  13. std::pair< attribute_set::iterator, bool > 
    add_thread_attribute(attribute_name const & name, attribute const & attr);

    The method adds an attribute to the thread-specific attribute set. The attribute will be implicitly added to every log record made in the current thread.

    [Note] Note

    In single-threaded build the effect is the same as adding the attribute globally. This, however, does not imply that iterators to thread-specific and global attributes are interchangeable.

    Parameters:

    attr

    The attribute factory.

    name

    The attribute name.

    Returns:

    A pair of values. If the second member is true, then the attribute is added and the first member points to the attribute. Otherwise the attribute was not added and the first member points to the attribute that prevents addition.

  14. void remove_thread_attribute(attribute_set::iterator it);

    The method removes an attribute from the thread-specific attribute set.

    Parameters:

    it

    Iterator to the previously added attribute.

    Requires:

    The attribute was added with the add_thread_attribute call.

    Postconditions:

    The attribute is no longer registered as a thread-specific attribute. The iterator is invalidated after removal.

  15. attribute_set get_thread_attributes() const;

    The method returns a copy of the complete set of currently registered thread-specific attributes.

  16. void set_thread_attributes(attribute_set const & attrs);

    The method replaces the complete set of currently registered thread-specific attributes with the provided set.

    [Note] Note

    The method invalidates all iterators and references that may have been returned from the add_thread_attribute method.

    Parameters:

    attrs

    The set of attributes to be installed.

  17. void set_exception_handler(exception_handler_type const & handler);

    The method sets exception handler function. The function will be called with no arguments in case if an exception occurs during either open_record or push_record method execution. Since exception handler is called from a catch statement, the exception can be rethrown in order to determine its type.

    By default no handler is installed, thus any exception is propagated as usual.

    See Also:

    See also: utility/exception_handler.hpp

    [Note] Note

    The exception handler can be invoked in several threads concurrently. Thread interruptions are not affected by exception handlers.

    Parameters:

    handler

    Exception handling function

  18. record open_record(attribute_set const & source_attributes);

    The method attempts to open a new record to be written. While attempting to open a log record all filtering is applied. A successfully opened record can be pushed further to sinks by calling the push_record method or simply destroyed by destroying the returned object.

    More than one open records are allowed, such records exist independently. All attribute values are acquired during opening the record and do not interact between records.

    The returned records can be copied, however, they must not be passed between different threads.

    Throws: If an exception handler is installed, only throws if the handler throws. Otherwise may throw if one of the sinks throws, or some system resource limitation is reached.

    Parameters:

    source_attributes

    The set of source-specific attributes to be attached to the record to be opened.

    Returns:

    A valid log record if the record is opened, an invalid record object if not (e.g. because it didn't pass filtering).

  19. record open_record(attribute_value_set const & source_attributes);

    The method attempts to open a new record to be written. While attempting to open a log record all filtering is applied. A successfully opened record can be pushed further to sinks by calling the push_record method or simply destroyed by destroying the returned object.

    More than one open records are allowed, such records exist independently. All attribute values are acquired during opening the record and do not interact between records.

    The returned records can be copied, however, they must not be passed between different threads.

    Throws: If an exception handler is installed, only throws if the handler throws. Otherwise may throw if one of the sinks throws, or some system resource limitation is reached.

    Parameters:

    source_attributes

    The set of source-specific attribute values to be attached to the record to be opened.

    Returns:

    A valid log record if the record is opened, an invalid record object if not (e.g. because it didn't pass filtering).

  20. record open_record(attribute_value_set && source_attributes);

    The method attempts to open a new record to be written. While attempting to open a log record all filtering is applied. A successfully opened record can be pushed further to sinks by calling the push_record method or simply destroyed by destroying the returned object.

    More than one open records are allowed, such records exist independently. All attribute values are acquired during opening the record and do not interact between records.

    The returned records can be copied, however, they must not be passed between different threads.

    Throws: If an exception handler is installed, only throws if the handler throws. Otherwise may throw if one of the sinks throws, or some system resource limitation is reached.

    Parameters:

    source_attributes

    The set of source-specific attribute values to be attached to the record to be opened. The contents of this container are unspecified after this call.

    Returns:

    A valid log record if the record is opened, an invalid record object if not (e.g. because it didn't pass filtering).

  21. void push_record(record && rec);

    The method pushes the record to sinks. The record is moved from in the process.

    Throws: If an exception handler is installed, only throws if the handler throws. Otherwise may throw if one of the sinks throws.

    Parameters:

    rec

    A previously successfully opened log record.

    Requires:

    !!rec == true

    Postconditions:

    !rec == true

core public static functions

  1. static core_ptr get();

    Returns:

    The method returns a pointer to the logging core singleton instance.


PrevUpHomeNext