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
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
//! THE RESOURCES: the type-erased map a deployment reaches its shared handles through.
//!
//! ONE map, and `Resources` is its whole name. It held the word `Context` while it was the only
//! thing a construction was handed; that word now names the PER-NODE window
//! ([`Context`](crate::Context)) — a node's own wind-down line, its own name, and a handle onto
//! this map — and the map kept the plural noun that says what it is. A body reaches a resource
//! through `ctx.shared::<R>()`, which is this map's own [`shared`](Resources::shared) one seat out.
//!
//! [`AsyncResource`]s are built ONCE, by the launch, before any node is constructed — a model context is
//! loaded on nobody's behalf in particular, and every node that declared `Shared<R>` gets a clone of
//! the same handle. What carries them from the resource pass to the node pass is this: one
//! framework-owned map, keyed by the resource's own type, handed to each construction as `&Resources`.
//!
//! # Why ERASED, when every lookup is typed
//!
//! The map holds resources of types this crate cannot name — a deployment's resources are its own —
//! so the storage is `dyn Any` and the DOOR is typed: [`shared`](Resources::shared) takes `R` as a
//! parameter and hands back a [`Shared<R>`], with the downcast the map's business and never a
//! caller's. It is `async-graphql`'s `Resources` shape, taken deliberately: a construction reaches for
//! what it needs by type, and nothing threads a per-node tuple of handles through a walk that cannot
//! know their arity.
//!
//! # The ONE honest tooth
//!
//! A lookup for a resource the DECLARATION never demanded is a launch-time refusal naming the type,
//! not a silent `None`. The demand scan reads a node's declared `Shared<R>` FIELDS; it cannot see
//! inside a hand-written [`AsyncConstructor`](super::AsyncConstructor) body, so a body that reaches past its
//! own declaration is a mistake the map has to report rather than one the walk can prevent. The
//! context pattern accepts that gap in exchange for its ergonomics, exactly as `async-graphql` does,
//! and [`MissingResourceError`] is the record of the trade.
//!
//! # THE RELEASE, which is the mirror of everything above
//!
//! ResourceCatalog are built FIRST, so they are released LAST — after every node that was handed a clone
//! has said its own goodbye and gone. [`release`](Resources::release) is that step, and what makes it
//! honest is [`Arc::into_inner`](std::sync::Arc::into_inner): a [`Shared<R>`] is a handle among
//! handles, so the map's own is the LAST one only when every borrower has finished, and unsealing it
//! is a question rather than an assertion.
//!
//! A resource whose last handle is not the map's is LEAKED — an application kept a clone of its own
//! — and the answer to that is to say so and move on. Its goodbye is skipped, the taps are told
//! under its name and the report carries the row. Waiting would be the alternative, and waiting for
//! a handle somebody else forgot to drop is a shutdown that never returns.
use ;
use ;
use crate::;
use ;
/// The shared resources a launch built, reachable by type.
///
/// Populated by the launch walk — resources first, then nodes, so a construction always finds what
/// the pass before it built — and handed to every [`AsyncConstructor`](super::AsyncConstructor) as `&Resources`.
/// A hand-wired arrangement builds one with [`with`](Self::with) and gets the same doors.
///
/// # `Send + Sync`, and it costs nothing to promise
///
/// The values are [`Shared<R>`] handles and [`AsyncResource`] is `Send + Sync` by supertrait, so the map
/// crosses threads because everything in it already does. That is what lets one context be borrowed
/// by constructions running wherever the launch runs.
///
/// # Examples
///
/// ```
/// use ingraph::{Resources, AsyncResource, Shared};
///
/// 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 ctx = Resources::new().with(Shared::new(Egemma { dim: 768 }));
///
/// // The door is typed: the map holds `dyn Any`, and a caller never downcasts.
/// let model = ctx.shared::<Egemma>().expect("the launch built it");
/// assert_eq!(model.dim, 768);
///
/// // A resource nothing built is a refusal that NAMES the type, never a silent `None`.
/// struct Whisper;
/// # impl AsyncResource for Whisper {
/// # type Options = ();
/// # type Error = core::convert::Infallible;
/// # async fn build(_ctx: &Resources, _: ()) -> Result<Self, Self::Error> { Ok(Self) }
/// # }
/// let refusal = ctx.shared::<Whisper>().expect_err("nothing built one");
/// assert!(refusal.to_string().contains("Whisper"));
/// ```
/// RELEASE the deployment's resources — the chain's last step, over the map behind `ctx`.
///
/// [`Resources::release`] needs the map by value, and what a running world holds is an
/// [`Arc`] of one. So this is the unsealing one layer up, and it is
/// [`Arc::into_inner`](std::sync::Arc::into_inner) for the same reason it is inside: whether this
/// handle is the last is a question rather than an assumption.
///
/// Where it is NOT the last, every enrolled resource is unreachable — the map holding it is still
/// somebody's — so each is reported as held rather than silently skipped. The count such a row
/// carries is the MAP's remaining holders, which is the honest number for the fact being reported:
/// how many parties can still reach the resource.
pub async
/// One resource's enrolled goodbye: whose it is, which entry of the map holds it, and how to unseal
/// it.
///
/// `unseal` is a plain function POINTER rather than a boxed closure, and it can be because the
/// monomorphised function item below is the whole of what has to be remembered: the value itself
/// stays in the map until the release pulls it out, so nothing is captured and nothing is allocated
/// for an enrolment that may never be spent.
/// Take `R` back out of its handle, and answer the goodbye — or the leak.
///
/// The one place [`Arc::into_inner`](std::sync::Arc::into_inner) is spent, and it is spent rather
/// than `try_unwrap` for the reason the two differ: `into_inner` promises that exactly one of
/// several concurrent callers wins, so a resource whose last two handles are dropped at once is
/// still torn down once rather than by neither of them.
///
/// The goodbye it answers with is [`AsyncResource::goodbye`] — the resource-side seat, defaulted to a
/// drop — so this function is monomorphised for every enrolled resource without any of them owing a
/// [`AsyncTeardown`] impl.
/// A construction reached for a resource nothing built — the resource map's one honest refusal.
///
/// It names the TYPE, which is the whole of what a reader needs: the fix is either declaring the
/// resource with `#[ingraph::resource]` or spelling the `Shared<R>` field that would have made the
/// demand scan build it.