Skip to main content

solverforge_scoring/api/
node_sharing.rs

1//! Diagnostics describing how many named terminals share one relational node.
2//!
3//! The canonical grouping migration routes every grouped, cross-grouped,
4//! projected, and complemented stream through the single `GroupNode` operator.
5//! These diagnostics report how many `#[solverforge_constraints]` terminals were
6//! authored over that one shared accumulator, which is the compiler-owned
7//! sharing contract made visible to operators.
8
9/// Identity of the shared node within the compiled constraint program.
10#[derive(Debug, PartialEq, Eq, Hash)]
11pub struct SharedNodeId(pub usize);
12
13/// The relational family of the shared node, named for diagnostics only.
14#[derive(Debug, PartialEq, Eq, Hash)]
15pub enum SharedNodeOperation {
16    /// Grouped rows over a unary stream.
17    Grouped,
18    /// Projected rows grouped into a shared accumulator.
19    ProjectedGrouped,
20    /// Cross-bi joined rows grouped into a shared accumulator.
21    CrossGrouped,
22    /// Cross-bi joined rows grouped, then complemented with default rows.
23    CrossComplementedGrouped,
24    /// Projected rows grouped, then complemented with default rows.
25    ProjectedComplementedGrouped,
26}
27
28/// A single shared node's diagnostics: its shared consumers and root
29/// notification bookkeeping while the terminal was incrementally live.
30#[derive(Debug, PartialEq, Eq)]
31pub struct SharedNodeDiagnostics {
32    /// Identity of the shared node.
33    pub id: SharedNodeId,
34    /// Compiler fingerprint of the node's structure.
35    pub fingerprint: String,
36    /// Relational family of the node.
37    pub operation: SharedNodeOperation,
38    /// Names of the terminals authored over this node.
39    pub terminal_consumers: Vec<String>,
40    /// Number of entity notifications that changed at least one of the node's
41    /// rows.
42    pub update_count: usize,
43    /// Number of group keys whose collector result a notification changed,
44    /// summed over notifications. One notification can change several keys,
45    /// or none while still changing rows (a complemented or joined node's
46    /// non-grouped side).
47    pub changed_key_count: usize,
48}
49
50impl SharedNodeDiagnostics {
51    /// Creates diagnostics from their parts.
52    pub fn new(
53        id: SharedNodeId,
54        fingerprint: impl Into<String>,
55        operation: SharedNodeOperation,
56        terminal_consumers: Vec<String>,
57        update_count: usize,
58        changed_key_count: usize,
59    ) -> Self {
60        Self {
61            id,
62            fingerprint: fingerprint.into(),
63            operation,
64            terminal_consumers,
65            update_count,
66            changed_key_count,
67        }
68    }
69}