rypipe_core/observer.rs
1//! Per-row observer hooks fired by `TableBuilder` during parsing.
2//!
3//! Attach via [`crate::ExecutionPlan::observer`]. Every executor (serial,
4//! parallel, bounded, streaming) builds on `TableBuilder`, so hooks fire on
5//! all of them, called from whichever thread parses the chunk: implementors
6//! must be `Send + Sync` and cheap, since hooks run on the parse hot path.
7//!
8//! Rejected rows are never observed field-by-field: when a row filter
9//! buffers values before the predicate resolves, `on_put_field` fires only
10//! when the buffered row is drained (accepted). One exception: when the
11//! predicate column arrives late in the row, values are pushed directly and
12//! popped on reject, so `on_put_field` may fire for a row that is later
13//! rejected; `on_row_rejected` still reports the rejection.
14
15use crate::Value;
16
17/// Hook points invoked by `TableBuilder` while building a batch.
18///
19/// All methods default to no-ops; implement only the ones you need.
20pub trait RowObserver: Send + Sync {
21 /// A new row started. `row_index` is the number of rows accepted so far.
22 fn on_begin_row(&self, _row_index: usize) {}
23
24 /// A field value landed in a column of an accepted (or not-yet-rejected)
25 /// row. `slot` is the column index in first-appearance order.
26 fn on_put_field(
27 &self,
28 _row_index: usize,
29 _resolved_name: &str,
30 _slot: usize,
31 _value: &Value<'_>,
32 ) {
33 }
34
35 /// The row passed the filter (or no filter) and was committed.
36 fn on_row_accepted(&self, _row_index: usize) {}
37
38 /// The row was rejected by the filter and discarded.
39 fn on_row_rejected(&self, _row_index: usize) {}
40
41 /// A batch/chunk finished. Counts cover the rows since the previous
42 /// finished batch (in streaming mode each emitted batch reports its own
43 /// delta).
44 fn on_chunk_finished(&self, _total: usize, _accepted: usize, _rejected: usize) {}
45}