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
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
//! THE CONTEXT: what ONE NODE is handed for its working life — the deployment it belongs to, the
//! wind-down line it hears on, and its own name.
//!
//! Every compute face in this crate takes one, first after `self`, and it is the same value at every
//! kind: [`Operator::accept`](crate::Operator::accept) borrows it once per delivery,
//! [`StreamOperator::run`](crate::StreamOperator::run) borrows it for one delivery's whole life, and
//! [`AutonomousOperator::run`](crate::AutonomousOperator::run) and
//! [`Source::run`](crate::Source::run) — the two kinds whose `run` IS the node's whole life — take it
//! BY VALUE for the same reason they take `self` that way: there is nothing after them.
//!
//! # It is a WINDOW and not a bag
//!
//! Three doors and no more:
//!
//! | door | what it answers |
//! |---|---|
//! | [`shutdown`](Context::shutdown) | the node's own wind-down line — *stop taking new work* |
//! | [`shared`](Context::shared) | a resource the deployment built, by type |
//! | [`node`](Context::node) | who this is, which is what a body's own logs and errors want |
//!
//! Nothing else belongs here. A per-item fact rides the [`Delivery`](crate::Delivery); a per-emission
//! one rides the [`Emitter`](crate::Emitter); a per-CLOCK least-privilege handle rides the
//! [grants](crate::Grant) a declaration wrote. See [`shared`](Context::shared) for the two-roads note
//! that keeps this window and those grants apart on purpose.
//!
//! # ONE LINE covers three ways of being told
//!
//! A node's [`ShutdownSignal`] is not a second announcement beside the deployment's; it is the road
//! every wind-down arrives by. [`App::shutdown`](crate::App::shutdown)'s first step announces on
//! every [`Stopper`](crate::Stopper) the launch kept, a caller that wants ONE node stopped announces
//! on that node's own, and a source registered through
//! [`App::halt_on`](crate::App::halt_on) reaches the same walk. So a body that reads
//! `ctx.shutdown()` mid-item hears all three through one door, and no deployment-wide tenant had to
//! be minted beside the per-node lines to make it so.
//!
//! # The RESOURCES are `Option`, and that is the hand-wired case rather than a defect
//!
//! A deployment always shares its map. A hand-driven test — an `accept` called directly, a lane a
//! test drives itself — has no launch and therefore no map, and the honest answer to
//! `ctx.shared::<R>()` there is the same refusal a launch gives for a resource nothing built:
//! [`MissingResourceError`] naming `R`. It is never a panic, which is what
//! [`Emitter::shared`]'s own note used to say one organ over — the door moved here and the reading
//! came with it.
use Arc;
use Utf8Bytes;
use crate::;
use ;
/// ONE NODE's window onto the world it runs in.
///
/// Built by the framework at the mount — one per node, carrying that node's own wind-down line —
/// and by [`new`](Self::new) where a test drives a body by hand.
///
/// # `Send + Sync`, and it costs nothing to promise
///
/// A name, a handle onto a map that is already `Send + Sync`, and two halves of a channel that is.
/// The whole value crosses onto whatever engine the node was placed on, which is what a seat handed
/// to a body has to be able to do.
///
/// # Examples
///
/// ```
/// use ingraph::{AsyncResource, Context, Resources, Shared};
/// use std::sync::Arc;
///
/// struct Egemma {
/// dim: usize,
/// }
///
/// impl AsyncResource for Egemma {
/// type Options = usize;
/// type Error = core::convert::Infallible;
///
/// async fn build(_ctx: &Resources, dim: usize) -> Result<Self, Self::Error> {
/// Ok(Self { dim })
/// }
/// }
///
/// let resources = Resources::new().with(Shared::new(Egemma { dim: 768 }));
/// let ctx = Context::new("embed").sharing(Arc::new(resources));
///
/// assert_eq!(ctx.node().as_str(), "embed");
/// assert_eq!(ctx.shared::<Egemma>().expect("the launch built it").dim, 768);
///
/// // A context nobody else holds a line onto never reads as stopping.
/// assert!(!ctx.shutdown().is_shutdown());
/// ```