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
//! THE CONSTRUCTION CONTRACT: what a node's author writes so a launch can build one.
//!
//! A node is a type an application owns, holding whatever that application's compute needs — a
//! decoder's thread budget, a model handle, an open device. The launch has to produce one, and the
//! only party that knows how is the author. So construction is a CAPABILITY the type implements,
//! exactly as [`AsyncResource`](crate::AsyncResource) is for the things several nodes share.
//!
//! # Two doors, one body
//!
//! [`with_options`](AsyncConstructor::with_options) is the source of truth and the only one an author
//! writes. [`new`](AsyncConstructor::new) exists where the options have a [`Default`] and DELEGATES to
//! it — the options pattern's own law, which is what keeps a hand-wired test and a launch walk from
//! taking two different paths into the same type. The walk itself calls `with_options` and nothing
//! else; `new` is the human's door.
//!
//! # ASYNC, and the exclusive-model default is why
//!
//! A node that owns its model loads the weights inside its own construction — that is the whole
//! point of the exclusive default — so building one is I/O and compute and the contract is a future.
//! The same sentence [`AsyncResource::build`](crate::AsyncResource::build) is written for, one tier down.
//!
//! Unlike that one, the future is NOT `Send`. A node's engine follows the node's own mobility: the
//! default engine is a pinned thread, which is safe for every node and is where a `!Send` citizen
//! lives, so a construction that cannot cross threads is a supported shape rather than a refusal.
//! The async engine is the opt-in that asks for `Send`, and it asks at its own wiring.
use Future;
use Resources;
/// A type a LAUNCH can build — the capability a node's author implements by hand.
///
/// # `type Options` is the AUTHOR's, and a zero-knob node writes `()`
///
/// Bound by nothing here. What options must satisfy is the DEPLOYMENT's question — a node section
/// read out of a file has to deserialize, and that is asked where the sections are declared rather
/// than where one is spent. A node with nothing to configure writes `type Options = ();` and gets
/// [`new`](Self::new) for free.
///
/// # `type Error` is the AUTHOR's too
///
/// Bound-free, per [`Operator::Error`](crate::Operator)'s discipline: a construction refuses in its
/// own currency, and the launch layer is what wraps a typed refusal into a start-up one naming the
/// node.
///
/// # Examples
///
/// ```
/// use ingraph::{AsyncConstructor, Resources};
///
/// /// A node with knobs, and the options that carry them.
/// struct Decode {
/// threads: usize,
/// }
///
/// struct DecodeOptions {
/// threads: usize,
/// }
///
/// impl Default for DecodeOptions {
/// fn default() -> Self {
/// Self { threads: 4 }
/// }
/// }
///
/// impl AsyncConstructor for Decode {
/// type Options = DecodeOptions;
/// type Error = core::convert::Infallible;
///
/// async fn with_options(_ctx: &Resources, options: DecodeOptions) -> Result<Self, Self::Error> {
/// Ok(Self {
/// threads: options.threads,
/// })
/// }
/// }
///
/// # tokio::runtime::Builder::new_current_thread().build().unwrap().block_on(async {
/// let ctx = Resources::new();
///
/// // The launch's door: a present section supplies the options.
/// let tuned = Decode::with_options(&ctx, DecodeOptions { threads: 8 })
/// .await
/// .unwrap();
/// assert_eq!(tuned.threads, 8);
///
/// // The human's door, which exists because the options have a `Default` — and which runs the
/// // very same body.
/// let plain = Decode::new(&ctx).await.unwrap();
/// assert_eq!(plain.threads, 4);
/// # });
/// ```