Struct async_logger::AsyncLoggerNB

pub struct AsyncLoggerNB<T: Send + 'static> { /* fields omitted */ }

Logger with non-blocking async processing.

Implementations

impl<T: Send + 'static> AsyncLoggerNB<T>

pub fn new(
    writer: Box<dyn Writer<T>>,
    buf_sz: usize
) -> Result<AsyncLoggerNB<T>, Error>

Create a new AsyncLoggerNB instance with buffer of buf_size items.

Errors

Err is returend if buf_sz is greater than std::isize::MAX or buf_sz is zero or when T has size of zero, or when memory allocation has failed for some reason (e.g. OOM).

Panics

Panics of OS fails to create thread.

pub fn terminate(self)

Flush underlying buffers, and wait until writer thread terminates. Further attempts to write to buffers will return error.

Panics

Panics if some of the internal mutexes is poisoned, or when writer thread paniced.

pub fn write_slice(&self, slice: &[T]) -> Result<(), ()> where
    T: Copy, 

Write a slice of <T>. If the size of slice is larger or equal to 0.8 * buffer_size then buffer is bypassed, and slice is handed directly to writer. Note, in this case message can appear out-of-order. Function blocks if message size is less than 0.8 * buffer_size, and there is not enough free space in any of buffers. As soon as there is free space larger than 0.8 * buffer_size available slice is written and function returns.

Errors

Err is returned when the function tries to put slice in buffer after terminate was called. This is normally not expected, because terminate takes ownership on logger instance.

Panics

This function panics if some of the internal mutexes is poisoned or when writer thread panics.

pub fn reserve_slice(&self, reserve_size: usize) -> Result<Slice<'_, T>, Error> where
    T: Copy, 

This function is similar to write_slice but instead of pushing some slice to buffer it allows reserving some space for writing directly in the underlying destination buffer. This way excessive copy operation from the slice to the internal buffer can be avoided. Thus, this function is more preferable than write_slice but is applicable only when you know the size of the slice you need beforehand. When the size of the slice doesn't matter use reserve_slice_relaxed.

The function returns Slice struct that can be dereferenced as mutable slice of <T>. The client code can use the dereferenced slice to write to it. The client code holds the buffer until Slice instance goes out of scope or is explicitly dropped with drop. That means client's code must take care of not holding the returned Slice instance for too long because it can block other threads.

Errors

If the reserve_size is larger or equal to 0.8 * buffer_size then Err is returned with ErrorKind::RequestedSizeIsTooLong.

Err is also returned when the function is called after terminate was called, but this is normally not expected, because terminate takes ownership on logger instance.

Panics

This function panics if some of the internal mutexes is poisoned or when writer thread panics.

pub fn reserve_slice_relaxed(
    &self,
    reserve_size: usize
) -> Result<Slice<'_, T>, ()> where
    T: Copy, 

This function is similar to reserve_slice but returned Slice struct can have length
from 1 item, and up to reserve_size items.

Errors

Err is returned when the function is called after terminate was called. This is normally not expected, because terminate takes ownership on logger instance.

Panics

This function panics if some of the internal mutexes is poisoned or when writer thread panics.

pub fn write_value(&self, value: T) -> Result<(), ()>

Write a value of type <T>. This method can be used for writing values that do not implement Copy trait, e.g. String, or pointer to a string Box<String>. The function takes ownership of the argument. After the argument is processed by writer drop for it is called automatically.

Function blocks if there is not enough free space in any of buffers. As soon as there is free space available value is written and function returns.

Errors

Err is returned when the function tries to put value in buffer after terminate was called. This is normally not expected, because terminate takes ownership on logger instance.

Panics

This function panics if some of the internal mutexes is poisoned or when writer thread panics.

Examples

use async_logger::{FileWriter, AsyncLoggerNB, Writer};

// implement some custom writer along the way
struct Stub {}
impl Writer<Box<String>> for Stub {
    fn process_slice(&mut self, slice: &[Box<String>]) {}
    fn flush(&mut self) {}
}

let writer_obj: Box<dyn Writer<Box<String>>> = Box::new(Stub {});

let logger = AsyncLoggerNB::new(Box::new(Stub {}), 8192)
    .expect("Failed to create new async logger");

let string_ptr = Box::new("test message".to_owned());
logger.write_value(string_ptr).unwrap();

pub fn flush(&self)

Mark not yet full buffer as ready for writer. This function doesn't call Writer::flush. This function doesn't wait while writer process all the previously written data.

Panics

Panics if some of the internal mutexes is poisoned.

pub fn get_metrics(&self) -> Metrics

Return current values of performance metrics, e.g. wait event information.