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
//! `Marshal` trait: jobs whose captured state can cross a process
//! boundary.
//!
//! ## Why a new trait beside `Send`?
//!
//! `Send` says "moveable across threads in the same address space."
//! An environment-capturing closure can be `Send` (the heap pointers
//! it captures are valid in the spawning process) but not portable
//! across processes (those heap pointers are meaningless in any
//! other address space).
//!
//! `Marshal` is the stricter contract:
//!
//! 1. The work can be reduced to a `(closure_id: u32, args: [u8;
//! N])` pair.
//! 2. Both processes have registered the same handler under the same
//! deterministic `closure_id`.
//! 3. The args fit in [`super::super::backend::shared_mem::chase_lev_mmf::ARGS_INLINE_BYTES`].
//!
//! ## Shape
//!
//! ```
//! struct AddOp { a: u32, b: u32 }
//!
//! impl flynnel::sched::Marshal for AddOp {
//! const HANDLER_NAME: &'static str = "flynnel.demo.add";
//!
//! fn marshal_args(&self) -> Vec<u8> {
//! let mut buf = Vec::with_capacity(8);
//! buf.extend_from_slice(&self.a.to_le_bytes());
//! buf.extend_from_slice(&self.b.to_le_bytes());
//! buf
//! }
//! }
//! ```
//!
//! The handler at the receiving end decodes `args` symmetrically and
//! returns a result `Vec<u8>` that the originator decodes after the
//! latch is published.
//!
//! ## Integration boundary
//!
//! `Marshal` is the data-shape contract. The transport for a marshal
//! job is the MMF Chase-Lev deque at
//! [`super::super::backend::shared_mem::chase_lev_mmf`]; the
//! result-publication transport is the MMF latch arena at
//! [`super::super::backend::shared_mem::latch_mmf`]. The high-level
//! dispatch API that glues these together lives in
//! [`super::super::backend::shared_mem::chase_lev_backend`].
use cratepass_registry;
/// A job whose captured state can be serialized + dispatched across
/// a process boundary.
///
/// Implementors declare a stable handler name and a `marshal_args`
/// serializer. Both processes must register a handler under
/// [`pass_registry::hash_name`] of the same `HANDLER_NAME` before the
/// originator can dispatch this work.
/// Helper: register a Marshal type's handler in this process.
///
/// The handler receives the bytes produced by
/// [`Marshal::marshal_args`] and returns either a result blob or an
/// error. Typical usage:
///
/// ```
/// # struct AddOp { a: u32, b: u32 }
/// # impl flynnel::sched::Marshal for AddOp {
/// # const HANDLER_NAME: &'static str = "flynnel.doc.register.add";
/// # fn marshal_args(&self) -> Vec<u8> {
/// # let mut buf = Vec::with_capacity(8);
/// # buf.extend_from_slice(&self.a.to_le_bytes());
/// # buf.extend_from_slice(&self.b.to_le_bytes());
/// # buf
/// # }
/// # }
/// flynnel::sched::register_marshal_handler::<AddOp>(|args| {
/// let a = u32::from_le_bytes(args[0..4].try_into().unwrap());
/// let b = u32::from_le_bytes(args[4..8].try_into().unwrap());
/// Ok((a + b).to_le_bytes().to_vec())
/// });
/// ```
///
/// Each peer process must call this for every Marshal type it needs
/// to execute. The originator does NOT need to register the handler
/// if it only dispatches and never drains.