rasant 0.6.0

Rasant is a lightweight, high performance and flexible Rust library for structured logging.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

//! Generic I/O logging [sink][`sink::Sink`] module.
//!
//! This sink can be used with any [`std::io::Write`] implementing [`Send`],
//! and supports options such as configurable delimiters between log
//! writes, flush-on-write, and buffering via [`std::io::BufWriter`].
use std::io;

use crate::attributes;
use crate::format;
use crate::sink;

/// Configuration struct for an [`IO`] [sink][`sink::Sink`].
pub struct IOConfig<T: io::Write + Send> {
	/// Name for this sink.
	pub name: String,
	/// Output formatting configuration.
	pub formatter_cfg: format::FormatterConfig,
	/// Whether writes to the underlying [`std::io::Write`] are buffered or not, via [`std::io::BufWriter`].
	pub buffered: bool,
	/// Whether to flush immediately after every write operation.
	pub flush_on_write: bool,
	/// Whether to insert a [formatted delimiter][`format::FormatterConfig::delimiter`] before the first log entry.
	pub initial_delimiter: bool,
	/// [`io::Write`]r for this sink.
	pub out: Option<T>,
}

impl<W: io::Write + Send> Default for IOConfig<W> {
	fn default() -> Self {
		Self {
			name: String::from("default"),
			formatter_cfg: format::FormatterConfig::default(),
			buffered: true,
			flush_on_write: false,
			initial_delimiter: false,
			out: None,
		}
	}
}

/// A [sink][`sink::Sink`] for any implementation of [`std::io::Write`] supporting [`Send`].
pub struct IO<'s> {
	name: String,
	formatter: format::Formatter,
	written_to: bool,
	flush_on_write: bool,
	initial_delimiter: bool,
	out: Box<dyn io::Write + Send + 's>,
}

impl<'i> IO<'i> {
	/// Initializes a new [`IO`] [sink][`sink::Sink`], from a given [`IOConfig`].
	pub fn new<T: io::Write + Send + 'i>(conf: IOConfig<T>) -> Self {
		let cout = match conf.out {
			Some(o) => o,
			None => panic!("missing io::Write output for I/O sink"),
		};
		let out: Box<dyn io::Write + Send> = if conf.buffered { Box::new(io::BufWriter::new(cout)) } else { Box::new(cout) };

		Self {
			name: conf.name,
			formatter: format::Formatter::new(conf.formatter_cfg),
			written_to: false,
			initial_delimiter: conf.initial_delimiter,
			flush_on_write: conf.flush_on_write,
			out: out,
		}
	}
}

impl<'i> sink::Sink for IO<'i> {
	fn name(&self) -> &str {
		self.name.as_str()
	}

	fn log(&mut self, update: &sink::LogUpdate, attrs: &attributes::Map) -> io::Result<()> {
		if self.written_to || (!self.written_to && self.initial_delimiter) {
			self.formatter.write_delimiter(&mut self.out)?;
		}

		self.formatter.write(&mut self.out, update, attrs)?;
		self.written_to = true;

		match self.flush_on_write {
			true => self.flush(),
			false => Ok(()),
		}
	}

	fn flush(&mut self) -> io::Result<()> {
		self.out.flush()
	}
}

impl Drop for IO<'_> {
	fn drop(&mut self) {
		// TODO: call self.flush() instead.
		if let Err(e) = self.out.flush() {
			panic!("failed to flush sink {name} on drop(): {e}", name = self.name);
		}
	}
}