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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
//! **astrs-node-api** — the AstRS node API (blueprint §9.1).
//!
//! The flagship user-facing surface: everything a robotics node needs to join
//! a dataflow, read its inputs and publish its outputs, and nothing it does
//! not.
//!
//! ```no_run
//! use astrs_node_api::prelude::*;
//!
//! fn main() -> Result<(), NodeError> {
//! let (mut node, mut events) = Node::init_from_env()?;
//! let mut echo = node.raw_output("echo")?;
//!
//! while let Some(event) = events.recv() {
//! match event {
//! Event::Input { id, data, meta } if id == "frames" => {
//! echo.send_bytes(data.to_vec(), meta.follow())?;
//! }
//! Event::Stop(_) => break,
//! _ => {}
//! }
//! }
//! Ok(())
//! }
//! ```
//!
//! # The surface, in one table
//!
//! | Area | Entry points |
//! |---|---|
//! | Init | [`Node::init_from_env`], [`Node::builder`], [`Node::init_from_node_id`], [`Node::init_testing`] |
//! | Events | [`EventStream::recv`], [`EventStream::recv_async`], `Iterator`, [`Stream`], [`EventStream::merge_external`] |
//! | Sending | [`Output::send`], [`RawOutput::send_bytes`], [`RawOutput::send_batch`], [`RawOutput::send_array`], [`RawOutput::allocate`] (and [`RawOutput::send_arrow`] under `arrow-interop`) |
//! | Patterns | [`Node::service_request`], [`Node::service_response`], [`Node::goal`], [`Node::goal_status`], [`Node::stream_chunk`] |
//! | Logging | [`Node::log_error`] … [`Node::log_trace`], [`Node::log_with_fields`] |
//! | Introspection | [`Node::id`], [`Node::dataflow_id`], [`Node::descriptor`], [`Node::is_restart`], [`Node::restart_count`], [`Node::hlc_now`] |
//! | Extensions | [`Node::ext_store`], [`Node::ext_load`], [`Node::ext_drop`] |
//!
//! # How the pieces fit
//!
//! ```text
//! Node ──────────────► SessionHandle ──► writer task ──► framed UDS/TCP ──► daemon
//! │ ▲ │
//! │ output::<T>() │ NodeRequest │ NodeEvent
//! ▼ │ ▼
//! Output<T> ── threshold ──►│ reader task ──► EventMux
//! │ (§6.2) │ │ (queue policy)
//! └── SHM Producer ────────┘ ▼
//! (after RouteUpgrade, §6.3) EventStream ──► your loop
//! ```
//!
//! Every layer is testable without a daemon: [`Node::init_testing`] spins an
//! in-process [`testing::MockDaemon`] speaking the real §7.3 wire
//! protocol over a `tokio::io::duplex` pair, so a node's whole lifecycle —
//! register, subscribe, inputs, patterns, stop — is a unit test.
//!
//! # Zero copy, both ways
//!
//! §6.3's slow-start handshake is wired at **both** ends, and a node writes no
//! code for either:
//!
//! | End | What arrives | What this crate does |
//! |---|---|---|
//! | producer | `NodeEvent::RouteUpgrade` | opens a shared-memory producer; [`RawOutput::allocate`] hands back the ring slot itself ([`session::routes`]) |
//! | consumer | `NodeEvent::InputRouteUpgrade` | attaches the segment and reads samples in place, so `Event::Input`'s payload is [`Payload::is_zero_copy`] ([`session::inputs`]) |
//!
//! Both directions fall back the same way: a downgrade, a dead producer or a
//! stale generation puts the route back on the reliable daemon path, and the
//! node's event loop does not notice. [`Node::route_planes`] and
//! [`Node::input_planes`] report where each end currently is; a message's
//! [`Payload::slot`] says where in the ring it came from, which is what turns
//! "zero copy" into something a test can check.
//!
//! [`Payload::zero_copy`] stays public for a node that brokers a segment
//! itself — a recorder replaying into a ring, an embedder outside the
//! daemon's graph — but nothing in a normal pipeline needs it any more.
//!
//! # Features
//!
//! | Feature | Default | What it adds |
//! |---|---|---|
//! | `arrow-interop` | no | [`RawOutput::send_arrow`] / [`Output::send_arrow`] — publishing arrow-rs values through `astrs-data`'s bridge (blueprint §6.1, §9.1). See [`output::arrow`]. |
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
/// The read-only views [`Payload::view`] decodes into (blueprint §9.1's
/// `let img: ImageView = data.view()?;`).
///
/// They belong to `astrs-data` — a view is a checked window over columns
/// somebody else built, and the layout rules it checks are that crate's — but
/// the line that *names* them is a node's event loop, so a node reaches them
/// here rather than through a second crate. [`ImageView`] has a
/// [`FromPayload`] implementation (see [`message::media`]); [`TensorView`] is
/// the general n-dimensional form the same module builds on.
pub use ;
/// Everything a node's `main` needs, in one import.
///
/// ```no_run
/// use astrs_node_api::prelude::*;
///
/// fn main() -> Result<(), NodeError> {
/// let (mut node, mut events) = Node::init_from_env()?;
/// while let Some(event) = events.recv() {
/// if event.is_stop() {
/// break;
/// }
/// }
/// let _ = &mut node;
/// Ok(())
/// }
/// ```