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
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
//! THE GOODBYE: the teardown a declaration OPTS IN to, and the chain that is never interrupted.
//!
//! Most constructed values need nothing said to them. A pool closes its connections as it drops, a
//! file handle closes itself, and a process that is exiting anyway takes the rest with it — so DROP
//! is the shipped teardown and it is the right one for almost everything. What it cannot do is
//! AWAIT: a flush that has to reach a store, a device released politely, a lock removed from a table
//! somebody else will read are all goodbyes that take a future, and a `Drop` has nowhere to put one.
//!
//! [`AsyncTeardown`] is that door, and it is an opt-in for exactly that reason. A declaration enrols in
//! it because its value genuinely has something to say; everything else says nothing and drops, and
//! neither posture costs the other anything.
//!
//! # ONE chain, walked backwards, whatever road each goodbye took to reach it
//!
//! Goodbyes are said in REVERSE ENROLMENT order — the launch's own LIFO, the same shape the ignition
//! starts in and the shutdown stops in. What is enrolled, in order, is the whole launch:
//!
//! | built | enrolled | said |
//! |---|---|---|
//! | the RESOURCES, first of all | first | LAST |
//! | the NODES, as the wiring registers their parties | next | in the middle, last-registered first |
//! | whatever the ignition still HOLDS | last | FIRST |
//!
//! so a resource outlives every node that was handed a handle to it, which is what makes
//! [`Arc::into_inner`](std::sync::Arc::into_inner) the honest release: by the time the resources are
//! reached, the node values that held a [`Shared`](crate::Shared) clone have said their own goodbyes
//! and gone.
//!
//! The three ways a goodbye REACHES this chain are [`Said`]'s three arms, and they exist because a
//! node's value is not in the launch's hands at all — it is on an engine. See [`Settlement`], which
//! is the seat the two engine roads hand it back through.
//!
//! # The chain is never interrupted, and the report is what carries the refusals
//!
//! Every goodbye is said even where an earlier one refused. A teardown that fails has failed at
//! something the process was leaving behind anyway; stopping there would abandon every value after
//! it in the list for the sake of a value that is already gone. So a refusal is OBSERVED through the
//! taps and named in the report, and the walk keeps going.
//!
//! A LEAK is the same posture one step milder: a resource somebody outside the deployment still
//! holds cannot be unsealed, so its goodbye is SKIPPED — observed, named in the report, and never
//! waited on. Blocking until the last handle went away would turn one application's forgotten clone
//! into a shutdown that never returns.
//!
//! # It serves the orderly shutdown AND the failed launch, on both sides of the ignition
//!
//! The protocol is one and it is spent on three occasions: at the end of an orderly shutdown, on
//! the unwind of a launch that failed AFTER something ignited, and on the unwind of one that failed
//! BEFORE anything did. There is no second teardown mechanism anywhere — see
//! [`Ignition::unwind`](super::Ignition::unwind), [`Creation::unwind`](super::Creation::unwind) and
//! [`Wiring::unwind`](super::Wiring::unwind), all three of which spend
//! [`farewell`] and [`Resources::release`](super::Resources) exactly as
//! [`App::shutdown`](super::App::shutdown) does.
//!
//! What differs between them is only WHERE the value is when the chain is walked, which is the same
//! taxonomy [`Said`] already is. Post-ignition a running loop has to be told, so the goodbye travels
//! back from its engine through the party's settlement seat. Pre-ignition nothing runs and ownership
//! never left the launch walk, so [`Staging`](super::Staging) holds the values themselves and the
//! chain consumes them where they stand.
//!
//! What says NO goodbye is the abort: [`App::abort`](super::App::abort), a shutdown past its
//! deadline, and an unwind that had to abandon somebody. All three run where something may still be
//! moving, and a teardown that flushes a store while the node writing to it is still running is a
//! worse ending than an un-torn value. Everything enrolled is then named in the report as a goodbye
//! that was never told to be said.
//!
//! The one class still left to its own [`Drop`] is a resident this walk's own ignition pass had not
//! reached when an EARLIER one of them refused an engine — see
//! [`Ignition::unwind`](super::Ignition::unwind), which owns that moment and says so.
use ;
use Arc;
use Utf8Bytes;
use crate;
use ;
/// An error whose type this crate cannot name.
///
/// The erased refusal, and the goodbye family's own word for one: the chain holds declarations of
/// every type at once, so a list cannot be generic over each of their errors separately. It is
/// spelled once here and named everywhere else rather than written out inline, which is what keeps
/// the family recognisable as one.
pub type BoxedError = ;
/// A goodbye IN FLIGHT, driven where it was made.
///
/// Not `Send`, and that is the point of having two of these: a value pinned to its own engine makes
/// a future pinned to that engine too, and demanding otherwise would refuse the very nodes teardown
/// matters most for — a model context, an FFI session, a device handle.
pub type Goodbye = ;
/// A goodbye that TRAVELS — the one the settle seat carries back to the chain.
///
/// `Send`, because a channel demands it and nothing else does. It is boxed at the only place that
/// knows the value's type, so the chain itself carries no generics at all.
pub type Posted = ;
/// A value with something to SAY before the process leaves it — the opt-in goodbye.
///
/// # It CONSUMES, because a goodbye happens once
///
/// `self` by value, so a value that has said goodbye cannot be used afterwards and cannot say it
/// twice. That is also what makes the ordinary posture honest: a type with no impl here is torn down
/// by [`Drop`], which consumes too.
///
/// # ASYNC, which is the whole reason it exists
///
/// A flush, a graceful release and a lock removal all reach something outside the process, so the
/// contract is a future — the one thing [`Drop`] cannot be. The future is not `Send`: it is created
/// and driven in one place, and a node whose value cannot cross threads is a supported shape here
/// exactly as it is at [`AsyncConstructor`](super::AsyncConstructor).
///
/// A body that DOES cross threads may hand its goodbye to the chain instead of driving it in place,
/// and that road asks for the one thing this contract does not promise — see
/// [`Ignition::task_saying_goodbye`](super::Ignition::task_saying_goodbye), which is where the
/// promise is demanded and where a `!Send` goodbye is refused.
///
/// # Examples
///
/// ```
/// use ingraph::AsyncTeardown;
///
/// /// A device this node opened, which would rather be released than reclaimed.
/// struct Camera {
/// handle: u32,
/// }
///
/// impl AsyncTeardown for Camera {
/// async fn teardown(self) -> Result<(), ingraph::BoxedError> {
/// // Whatever saying goodbye takes — a flush, a release, a lock removed.
/// assert_ne!(self.handle, 0);
/// Ok(())
/// }
/// }
/// ```
/// One enrolled teardown that did not say goodbye — the shutdown report's un-torn class.
///
/// Four ways in, and [`error`](Self::error) and [`leaked`](Self::leaked) are which:
///
/// - a goodbye that was SAID and refused carries the value's own refusal;
/// - one that was never told to be said carries none — that is what an abort leaves behind, a
/// shutdown that gave up waiting not then starting to flush stores whose nodes may still be
/// writing to them;
/// - one whose value was pinned to a thread that vanished before its turn came carries none either,
/// which is the honest reading of a body that panicked;
/// - and a resource somebody else still holds is [`leaked`](Self::leaked) — told, unsealable,
/// skipped.
/// Why an enrolled goodbye is in the report — see [`Untorn`], whose four ways in these are.
/// One enrolled goodbye: whose it is, and how the chain gets at it.
pub
/// The three roads a goodbye reaches the chain by.
///
/// They differ by WHERE the value is when the chain is walked, which is the whole taxonomy: in the
/// launch's own hands, or on an engine that has already handed its goodbye back, or on an engine
/// that is still holding it and waiting to be told.
/// What a HELD goodbye answers when the chain finally asks for it.
pub
/// How one goodbye ended.
/// ONE reading of the settle seat — see [`collected`], whose answer this is.
///
/// The two halves are the shutdown report's two classes of party, and they are DISJOINT by
/// construction: every registered party is in exactly one of them, and a silent settlement is in
/// neither, which is the shipped posture's whole cost.
pub
/// READ the settle seat once: the goodbyes the parties handed back, and who handed nothing back.
///
/// The step between the wait and the chain, and the only thing that empties the settle seat. What it
/// answers is in the order the wiring walk registered the parties, so the chain's own `.rev()` says
/// them last-registered first — which is the order the ignition started them in, run backwards.
///
/// A party that settled silently contributes nothing, which is what the shipped posture costs: no
/// row, no allocation, no name in the report.
///
/// # Both classes come out of ONE take, and that is what makes them disjoint
///
/// A settlement can be taken exactly once — [`Party::goodbye`](super::shutdown::Party) empties the
/// seat and the emptying is atomic — so the take IS the membership decision: what is in the seat is
/// this party's goodbye and never also its absence, and what is not is its absence and never also a
/// goodbye. Whichever side of this line a party settles on, it lands in one class.
///
/// Reading the seat TWICE would not have that property, and this function exists in this shape
/// because the report once did: a LOOK to count who had not settled, and a TAKE further down to
/// build the chain, put a party that settled between the two in BOTH — unanswered by the first
/// reading and holding an un-said goodbye by the second. Counting and collecting are one walk here
/// for that reason, and the classes cannot disagree because there is nothing for them to disagree
/// about.
pub
/// Say every goodbye in `farewells`, LAST ENROLLED FIRST, and never stop for a refusal.
///
/// Sequential rather than joined: a teardown may be the very thing another one is waiting to be
/// finished with, and reverse enrolment order is the only order this walk knows to be safe — it is
/// the order everything was built in, run backwards.
///
/// Every ending that is not a clean goodbye is observed under its own name and collected; what comes
/// back is the report's un-torn class, in the order the goodbyes were said.
pub async
/// Tell the taps how one goodbye ended, under the name it was enrolled by.
///
/// The seam a refused goodbye, an abandoned one and a leaked resource all report through, which is
/// the whole reason each of them wears [`Error`] below: [`Failure`] erases a value that IS an error,
/// and *nobody was there to say it to* is a fact the framework has to turn into one.
/// A teardown's own refusal, wearing [`Error`] so a tap can be told about it.
///
/// What it forwards is the refusal's own rendering and the refusal's own source, so nothing about
/// the chain a tap walks says this wrapper's name.
;
/// A goodbye whose engine had already gone when its turn came.
;
/// A resource somebody outside the deployment is still holding.