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

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

Class template asynchronous_sink

boost::log::sinks::asynchronous_sink — Asynchronous logging sink frontend.

Synopsis

// In header: <boost/log/sinks/async_frontend.hpp>

template<typename SinkBackendT, 
         typename QueueingStrategyT = unbounded_fifo_queue> 
class asynchronous_sink : public basic_sink_frontend,
                          private locking_ptr_counter_base,
                          public QueueingStrategyT
{
public:
  // types
  typedef SinkBackendT           sink_backend_type;   // Sink implementation type. 
  typedef implementation_defined locked_backend_ptr;  // A pointer type that locks the backend until it's destroyed. 

  // member classes/structs/unions

  // A scope guard that resets a flag on destructor.

  class scoped_flag {
  public:
    // construct/copy/destruct
    explicit scoped_flag(frontend_mutex_type &, condition_variable_any &, 
                         volatile bool &);
    scoped_flag(scoped_flag const &);
    scoped_flag& operator=(scoped_flag const &);
    ~scoped_flag();
  };

  // A scope guard that implements thread ID management.

  class scoped_thread_id {
  public:
    // construct/copy/destruct
    scoped_thread_id(frontend_mutex_type &, condition_variable_any &, 
                     thread::id &, bool volatile &);
    scoped_thread_id(unique_lock< frontend_mutex_type > &, 
                     condition_variable_any &, thread::id &, bool volatile &);
    scoped_thread_id(scoped_thread_id const &);
    scoped_thread_id& operator=(scoped_thread_id const &);
    ~scoped_thread_id();
  };

  // construct/copy/destruct
  asynchronous_sink(bool = true);
  explicit asynchronous_sink(shared_ptr< sink_backend_type > const &, 
                             bool = true);
  ~asynchronous_sink();

  // public member functions
  locked_backend_ptr locked_backend();
  void consume(record_view const &);
  bool try_consume(record_view const &);
  void run();
  void stop();
  void feed_records();
  void flush();
};

Description

The frontend starts a separate thread on construction. All logging records are passed to the backend in this dedicated thread only.

asynchronous_sink public construct/copy/destruct

  1. asynchronous_sink(bool start_thread = true);

    Default constructor. Constructs the sink backend instance. Requires the backend to be default-constructible.

    Parameters:

    start_thread

    If true, the frontend creates a thread to feed log records to the backend. Otherwise no thread is started and it is assumed that the user will call either run or feed_records himself.

  2. explicit asynchronous_sink(shared_ptr< sink_backend_type > const & backend, 
                               bool start_thread = true);

    Constructor attaches user-constructed backend instance

    Parameters:

    backend

    Pointer to the backend instance.

    start_thread

    If true, the frontend creates a thread to feed log records to the backend. Otherwise no thread is started and it is assumed that the user will call either run or feed_records himself.

    Requires:

    backend is not NULL.

  3. ~asynchronous_sink();

    Destructor. Implicitly stops the dedicated feeding thread, if one is running.

asynchronous_sink public member functions

  1. locked_backend_ptr locked_backend();

    Locking accessor to the attached backend

  2. void consume(record_view const & rec);

    Enqueues the log record to the backend

  3. bool try_consume(record_view const & rec);

    The method attempts to pass logging record to the backend

  4. void run();

    The method starts record feeding loop and effectively blocks until either of this happens:

    • the thread is interrupted due to either standard thread interruption or a call to stop

    • an exception is thrown while processing a log record in the backend, and the exception is not terminated by the exception handler, if one is installed

    Requires:

    The sink frontend must be constructed without spawning a dedicated thread

  5. void stop();

    The method softly interrupts record feeding loop. This method must be called when the run method execution has to be interrupted. Unlike regular thread interruption, calling stop will not interrupt the record processing in the middle. Instead, the sink frontend will attempt to finish its business with the record in progress and return afterwards. This method can be called either if the sink was created with a dedicated thread, or if the feeding loop was initiated by user.

    [Note] Note

    Returning from this method does not guarantee that there are no records left buffered in the sink frontend. It is possible that log records keep coming during and after this method is called. At some point of execution of this method log records stop being processed, and all records that come after this point are put into the queue. These records will be processed upon further calls to run or feed_records.

  6. void feed_records();

    The method feeds log records that may have been buffered to the backend and returns

    Requires:

    The sink frontend must be constructed without spawning a dedicated thread

  7. void flush();

    The method feeds all log records that may have been buffered to the backend and returns. Unlike feed_records, in case of ordering queueing the method also feeds records that were enqueued during the ordering window, attempting to empty the queue completely.

    Requires:

    The sink frontend must be constructed without spawning a dedicated thread


PrevUpHomeNext