## 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, public unbounded_fifo_queue
    {
    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

      // Function object to run the log record feeding thread.

      class run_func {
      public:
        // types
        typedef void result_type;

        // public member functions
        explicit run_func(asynchronous_sink *) noexcept;
        result_type operator()() const;
      };

      // A scope guard that implements active operation management.

      class scoped_feeding_operation {
      public:

        // public member functions
        explicit scoped_feeding_operation(asynchronous_sink &);
        ~scoped_feeding_operation();
        scoped_feeding_operation(scoped_feeding_operation const &) = delete;
        scoped_feeding_operation &
        operator=(scoped_feeding_operation const &) = delete;
      };

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

      class scoped_flag {
      public:

        // public member functions
        explicit scoped_flag(frontend_mutex_type &, std::condition_variable_any &,
                             boost::atomic< bool > &);
        ~scoped_flag();
        scoped_flag(scoped_flag const &) = delete;
        scoped_flag & operator=(scoped_flag const &) = delete;
      };

      // public member functions
      explicit asynchronous_sink(bool = true);
      explicit asynchronous_sink(shared_ptr< sink_backend_type > const &,
                                 bool = true);
      template<typename... Args> explicit asynchronous_sink(Args &&...);
      ~asynchronous_sink() noexcept;
      locked_backend_ptr locked_backend();
      virtual void consume(record_view const &);
      virtual bool try_consume(record_view const &);
      void run();
      void stop();
      void feed_records();
      virtual void flush();
    };

## Description

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

The user can prevent spawning the internal thread by specifying `start_thread` parameter with the value of `false` on construction. In this case log records will be buffered in the internal queue until the user calls `run`, `feed_records` or `flush` in his own thread. Log record queueing strategy is specified in the `QueueingStrategyT` template parameter.

### `asynchronous_sink` public member functions

1.     explicit 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 `run`, `feed_records` or `flush` 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 `run`, `feed_records` or `flush` himself.
   Requires: | backend is not `NULL`.

3.     template<typename... Args> explicit asynchronous_sink(Args &&... args);

   Constructor that passes arbitrary named parameters to the interprocess sink backend constructor. Refer to the backend documentation for the list of supported parameters.

   The frontend uses the following named 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 `run`, `feed_records` or `flush` himself.

4.     ~asynchronous_sink() noexcept;

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

5.     locked_backend_ptr locked_backend();

   Locking accessor to the attached backend

6.     virtual void consume(record_view const & rec);

   Enqueues the log record to the backend

7.     virtual bool try_consume(record_view const & rec);

   The method attempts to pass logging record to the backend

8.     void run();

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

   - the thread is interrupted due to 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

9.     void stop();

   The method softly interrupts record feeding loop. This method must be called when `run`, `feed_records` or `flush` 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 an internal dedicated thread, or if the feeding loop was initiated by user.

   If no record feeding operation is in progress, calling `stop` marks the sink frontend so that the next feeding operation stops immediately.

   | 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`.

   | Note
   If the record feeding loop is being run in a user's thread (i.e. `start_thread` was specified as `false` on frontend construction), this method does not guarantee that upon return the thread has returned from the record feeding loop or that it won't enter it in the future. The method only ensures that the record feeding thread will eventually return from the feeding loop. It is user's responsibility to synchronize with the user's record feeding thread.

10.     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

11.     virtual 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 drain the queue completely.