Class template ordering_asynchronous

Class template ordering_asynchronous_sink

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

Synopsis

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

template<typename SinkBackendT> 
class ordering_asynchronous_sink :
  public ordering_asynchronous_frontend< SinkBackendT::char_type >
{
public:
  // types
  typedef SinkBackendT           sink_backend_type;   // Sink implementation type. 
  typedef base_type::char_type   char_type;           // Character type. 
  typedef base_type::record_type record_type;         // Log record type. 
  typedef base_type::string_type string_type;         // String type to be used as a message text holder. 
  typedef implementation_defined locked_backend_ptr;  // A pointer type that locks the backend until it's destroyed. 

  // construct/copy/destruct
  template<typename... ArgsT> 
    explicit ordering_asynchronous_sink(shared_ptr< sink_backend_type > const &, 
                                        ArgsT...const &);
  template<typename... ArgsT> 
    explicit ordering_asynchronous_sink(ArgsT...const &);

  // public member functions
  locked_backend_ptr locked_backend() const;
  void run();
  bool stop();
  void feed_records(posix_time::time_duration = get_ordering_window());
  posix_time::time_duration get_ordering_window() const;

  // public static functions
  static posix_time::time_duration get_default_ordering_window();
};

Description

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

`ordering_asynchronous_sink` public construct/copy/destruct

template<typename... ArgsT> 
  explicit ordering_asynchronous_sink(shared_ptr< sink_backend_type > const & backend, 
                                      ArgsT...const & args);

Constructor attaches a user-constructed backend instance

Parameters:

args

One or several additional named parameters for the frontend. The following parameters are supported:

order - An ordering predicate that will be used to order log records. The predicate should accept two objects of type record_type and return bool. This parameter is mandatory.
ordering_window - A time latency for which log records can be delayed within the frontend in order to apply ordering. Should be specified as a Boost.DateTime posix_time::time_duration value. Optional parameter, some predefined system-specific value is used if not specified.
start_thread - If true, the frontend will start a dedicated thread to feed log records to the backend. Otherwise the user is expected to call either run or feed_records to feed records.

backend

Pointer to the backend instance.

Requires:

backend is not NULL.

template<typename... ArgsT> 
  explicit ordering_asynchronous_sink(ArgsT...const & args);

Constructor creates the frontend and the backend with the specified parameters

Parameters:

args

One or several additional construction named parameters. These parameters will be forwarded to the backend constructor. However, the frontend will use the following ones of them:

order - An ordering predicate that will be used to order log records. The predicate should accept two objects of type record_type and return bool. This parameter is mandatory.
ordering_window - A time latency for which log records can be delayed within the frontend in order to apply ordering. Should be specified as a Boost.DateTime posix_time::time_duration value. Optional parameter, some predefined system-specific value is used if not specified.
start_thread - If true, the frontend will start a dedicated thread to feed log records to the backend. Otherwise the user is expected to call either run or feed_records to feed records.

`ordering_asynchronous_sink` public member functions

locked_backend_ptr locked_backend() const;

Locking accessor to the attached backend

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

bool 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 (including feeding the rest of the buffered records to the backend) and return afterwards. This method can be called either if the sink was created with a dedicated thread, or if the run method was called by user.

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.

void feed_records(posix_time::time_duration ordering_window = get_ordering_window());

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

	Note
	In order to perform a full flush the ordering_window parameter should be specified as 0.

Parameters:

ordering_window

The function will not feed records that arrived to the frontend within the specified ordering window time duration.

Requires:

The sink frontend must be constructed without spawning a dedicated thread

```
posix_time::time_duration get_ordering_window() const;
```
Returns ordering window size specified during initialization

`ordering_asynchronous_sink` public static functions

```
static posix_time::time_duration get_default_ordering_window();
```
Returns default ordering window size. The default window size is specific to the operating system thread scheduling mechanism.