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
103
104
105
//! Non-fatal parse diagnostics.
//!
//! Batch parsers return `Err` to abort a chunk, but streaming formats need to
//! report recoverable damage (a malformed record, an unterminated section, an
//! item dropped at EOF) without failing the whole feed. Adapters receive a
//! `ParseDiagnostics` and report structured events; the caller decides what to
//! log or count.
/// Sink for parser warnings and counters.
///
/// Implementations are shared across parse threads in the parallel engines, so
/// they must be `Send + Sync` and cheap; a no-op default keeps the common case
/// free.
pub trait ParseDiagnostics: Send + Sync {
/// A recoverable event the caller should surface. `code` is a stable,
/// adapter-defined tag (e.g. `"malformed_item"`); `message` is a
/// human-readable description.
fn warning(&self, _code: &str, _message: &str) {}
/// Increment a named counter (e.g. `"discarded_items"`) by `delta`.
fn counter(&self, _name: &str, _delta: usize) {}
/// Whether any event is pending. Streaming drivers poll this cheaply
/// instead of draining (and allocating) per record.
fn has_events(&self) -> bool {
false
}
}
/// Diagnostics sink that drops everything. Used when the caller does not care
/// about per-record damage.
#[derive(Clone, Copy, Debug, Default)]
pub struct NoopDiagnostics;
impl ParseDiagnostics for NoopDiagnostics {}
/// A diagnostics sink that collects warnings and counters for the caller to
/// drain. Shareable across parse threads.
#[derive(Default)]
pub struct CollectingDiagnostics {
events: std::sync::Mutex<Vec<(String, String)>>,
counters: std::sync::Mutex<std::collections::HashMap<String, usize>>,
}
impl CollectingDiagnostics {
pub fn new() -> Self {
Self::default()
}
/// Take the warnings accumulated since the last call.
pub fn take_events(&self) -> Vec<(String, String)> {
std::mem::take(&mut *self.events.lock().unwrap_or_else(|e| e.into_inner()))
}
/// Snapshot the counters.
pub fn counters(&self) -> std::collections::HashMap<String, usize> {
self.counters
.lock()
.unwrap_or_else(|e| e.into_inner())
.clone()
}
}
impl ParseDiagnostics for CollectingDiagnostics {
fn warning(&self, code: &str, message: &str) {
self.events
.lock()
.unwrap_or_else(|e| e.into_inner())
.push((code.to_string(), message.to_string()));
}
fn counter(&self, name: &str, delta: usize) {
*self
.counters
.lock()
.unwrap_or_else(|e| e.into_inner())
.entry(name.to_string())
.or_insert(0) += delta;
}
fn has_events(&self) -> bool {
!self
.events
.lock()
.unwrap_or_else(|e| e.into_inner())
.is_empty()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn collecting_diagnostics_reports_and_drains() {
let d = CollectingDiagnostics::new();
assert!(!d.has_events());
d.warning("bad_item", "dropped");
d.counter("discarded", 2);
assert!(d.has_events());
assert_eq!(d.take_events().len(), 1);
assert!(!d.has_events());
assert_eq!(d.counters().get("discarded"), Some(&2));
}
}