Skip to main content

deq_runtime/controller/
static_controller.rs

1use crate::bin;
2use crate::coordinator;
3use crate::coordinator::{CoordinatorClient, ResetRequest};
4#[cfg(feature = "cli")]
5use crate::util::BitVector;
6use serde::{Deserialize, Serialize};
7use std::sync::Arc;
8#[cfg(feature = "cli")]
9use structdoc::StructDoc;
10use tokio::sync::{Mutex, RwLock};
11use tokio::task::JoinSet;
12use tonic::Status;
13#[cfg(feature = "cli")]
14use tonic::transport::server::Router;
15#[cfg(feature = "cli")]
16use tonic::{Request, Response};
17
18include!("../proto/deq.controller.static_controller.rs");
19
20#[derive(Debug, Clone, Serialize, Deserialize)]
21#[cfg_attr(feature = "cli", derive(StructDoc))]
22#[serde(deny_unknown_fields)]
23pub struct StaticControllerConfig {
24    /// the filepath to the binary protobuf file, see `proto/coordinator.proto`
25    pub filepath: String,
26    #[serde(default)]
27    pub reset_library: bool,
28    #[serde(default)]
29    pub reset_decoder_service: bool,
30}
31
32pub struct StaticController {
33    pub config: StaticControllerConfig,
34    pub library: crate::bin::Library,
35    coordinator: RwLock<Option<CoordinatorClient>>,
36    /// immutable information about the library
37    #[cfg_attr(not(feature = "cli"), allow(dead_code))]
38    info: Arc<StaticControllerInfo>,
39    /// mutable state during runtime
40    #[cfg_attr(not(feature = "cli"), allow(dead_code))]
41    state: Arc<Mutex<StaticControllerState>>,
42}
43
44struct StaticControllerState {
45    /// the next gid to be instantiated
46    next_index: usize,
47    /// the list of gids instantiated
48    gid_vec: Vec<u64>,
49    /// accumulated measurement outcomes received
50    outcomes: Vec<bool>,
51    /// Accumulated per-measurement loss flags, kept in lockstep with `outcomes`.
52    loss_mask: Option<Vec<bool>>,
53    /// Seed selected by the first request in a shot. The outer option records whether
54    /// that request arrived; the inner option preserves an absent seed.
55    decoder_seed: Option<Option<u64>>,
56    /// background decode tasks for streaming mode (dispatched but not yet awaited)
57    pending_decodes: JoinSet<Result<(usize, coordinator::Readouts), Status>>,
58    /// readouts collected from completed background decode tasks
59    pending_readouts: Vec<Option<coordinator::Readouts>>,
60    /// index offset for pending readouts (how many gadgets have been dispatched so far)
61    dispatched_count: usize,
62}
63
64struct StaticControllerInfo {
65    /// the accumulated number of measurements, helpful to determine if sufficient
66    /// number of measurements outcome bits have been received
67    accumulated_measurements: Vec<usize>,
68    /// the number of measurements in total
69    total_measurements: usize,
70}
71
72impl StaticControllerInfo {
73    pub fn new(library: &bin::Library) -> Self {
74        let mut accumulated_measurements: Vec<usize> = vec![];
75        let mut total_measurements: usize = 0;
76        for instruction in library.program.iter() {
77            if let bin::instruction::Create::Gadget(gadget) = instruction.create.as_ref().unwrap() {
78                let gadget_type = library.gadget_types.iter().find(|gt| gt.gtype == gadget.gtype).unwrap();
79                total_measurements += gadget_type.measurements.len();
80                accumulated_measurements.push(total_measurements);
81            }
82        }
83        Self {
84            accumulated_measurements,
85            total_measurements,
86        }
87    }
88}
89
90impl StaticController {
91    pub fn new(config: serde_json::Value) -> Self {
92        let config: StaticControllerConfig = serde_json::from_value(config).unwrap();
93        // read from file
94        let data = std::fs::read(config.filepath.clone()).unwrap();
95        let library: bin::Library = prost::Message::decode(&mut data.as_slice()).unwrap();
96        let info = Arc::new(StaticControllerInfo::new(&library));
97        let state = StaticControllerState {
98            next_index: 0,
99            gid_vec: Vec::with_capacity(info.accumulated_measurements.len()),
100            outcomes: Vec::with_capacity(info.total_measurements),
101            loss_mask: None,
102            decoder_seed: None,
103            pending_decodes: JoinSet::new(),
104            pending_readouts: Vec::new(),
105            dispatched_count: 0,
106        };
107        Self {
108            config,
109            library,
110            coordinator: RwLock::new(None),
111            info,
112            state: Arc::new(Mutex::new(state)),
113        }
114    }
115
116    #[cfg(feature = "cli")]
117    pub fn add_service(self: &Arc<Self>, router: Router) -> Router {
118        let service =
119            static_controller_server::StaticControllerServer::from_arc(self.clone()).max_decoding_message_size(usize::MAX);
120        router.add_service(service)
121    }
122
123    pub async fn start(self: &Arc<Self>, mut client: CoordinatorClient) {
124        let mut coordinator = self.coordinator.write().await;
125        client.load_library(self.library.clone()).await.unwrap();
126        self.reset_and_instantiate_all(&mut client).await;
127        coordinator.replace(client);
128    }
129
130    #[cfg(feature = "cli")]
131    async fn wait_until_library_loaded(&self) -> CoordinatorClient {
132        // tokio::sync::RwLock is a fair lock, so looping is fine
133        while self.coordinator.read().await.is_none() {
134            tokio::task::yield_now().await;
135        }
136        self.coordinator.read().await.clone().unwrap()
137    }
138
139    async fn reset_and_instantiate_all(&self, coordinator: &mut CoordinatorClient) {
140        // since a static program should never change, we reset the coordinator to a minimum extent
141        coordinator
142            .reset(ResetRequest {
143                reset_library: self.config.reset_library,
144                reset_decoder_service: self.config.reset_decoder_service,
145                ..Default::default()
146            })
147            .await
148            .unwrap();
149        let mut gid_vec: Vec<u64> = vec![];
150        let mut cid_vec: Vec<u64> = vec![];
151        for instruction in self.library.program.iter() {
152            match instruction.clone().create.unwrap() {
153                bin::instruction::Create::Gadget(mut gadget) => {
154                    for connector in gadget.connectors.iter_mut() {
155                        connector.gid = gid_vec[(connector.gid as usize) - 1];
156                    }
157                    let gid = coordinator
158                        .execute(bin::Instruction {
159                            create: Some(bin::instruction::Create::Gadget(gadget)),
160                        })
161                        .await
162                        .unwrap()
163                        .id;
164                    gid_vec.push(gid);
165                }
166                bin::instruction::Create::CheckModel(mut check_model) => {
167                    check_model.gid = gid_vec[(check_model.gid as usize) - 1];
168                    let cid = coordinator
169                        .execute(bin::Instruction {
170                            create: Some(bin::instruction::Create::CheckModel(check_model)),
171                        })
172                        .await
173                        .unwrap()
174                        .id;
175                    cid_vec.push(cid);
176                }
177                bin::instruction::Create::ErrorModel(mut error_model) => {
178                    error_model.cid = cid_vec[(error_model.cid as usize) - 1];
179                    let _eid = coordinator
180                        .execute(bin::Instruction {
181                            create: Some(bin::instruction::Create::ErrorModel(error_model)),
182                        })
183                        .await
184                        .unwrap()
185                        .id;
186                }
187            }
188        }
189        let mut state = self.state.lock().await;
190        state.next_index = 0;
191        state.gid_vec = gid_vec;
192        state.outcomes.clear();
193        state.loss_mask = None;
194        state.decoder_seed = None;
195        state.pending_decodes.shutdown().await;
196        state.pending_readouts.clear();
197        state.dispatched_count = 0;
198    }
199}
200
201#[cfg(feature = "cli")]
202#[tonic::async_trait]
203impl static_controller_server::StaticController for StaticController {
204    async fn decode(
205        &self,
206        request: Request<coordinator::Outcomes>,
207    ) -> std::result::Result<Response<coordinator::Readouts>, Status> {
208        let batch = self.decode_gadgets(request).await?.into_inner();
209        Ok(Response::new(coordinator::Readouts::gather(&batch.readouts)?))
210    }
211
212    async fn decode_gadgets(
213        &self,
214        request: Request<coordinator::Outcomes>,
215    ) -> std::result::Result<Response<BatchReadouts>, Status> {
216        let request = request.into_inner();
217        let coordinator = self.wait_until_library_loaded().await;
218
219        let outcomes_bv = request
220            .outcomes
221            .ok_or_else(|| Status::invalid_argument("Outcomes.outcomes is required"))?;
222        let outcomes = crate::misc::bit_vector::unpack_bits(&outcomes_bv.data, outcomes_bv.size);
223        let loss_bits: Option<Vec<bool>> = request.loss_mask.as_ref().map(|bv| {
224            let bits = crate::misc::bit_vector::unpack_bits(&bv.data, bv.size);
225            assert_eq!(
226                bits.len(),
227                outcomes.len(),
228                "loss_mask length ({}) does not match outcomes length ({})",
229                bits.len(),
230                outcomes.len(),
231            );
232            bits
233        });
234
235        let is_complete;
236        {
237            // getting the lock to compute the decode requests and spawn tasks
238            let mut state = self.state.lock().await;
239
240            crate::coordinator::accept_decoder_seed(&mut state.decoder_seed, request.decoder_seed)?;
241
242            // The Some/None choice for `loss_mask` is locked in by the first
243            // decode call of each shot.  Later calls must match that choice.
244            let is_first_call_of_shot = state.outcomes.is_empty();
245            if is_first_call_of_shot {
246                state.loss_mask = loss_bits.clone();
247            } else {
248                match (state.loss_mask.as_mut(), loss_bits.as_ref()) {
249                    (Some(acc), Some(new)) => acc.extend_from_slice(new),
250                    (None, None) => {}
251                    (Some(_), None) => {
252                        return Err(Status::invalid_argument(
253                            "loss_mask was supplied earlier in this shot; subsequent decode \
254                             calls of the same shot must also supply it",
255                        ));
256                    }
257                    (None, Some(_)) => {
258                        return Err(Status::invalid_argument(
259                            "loss_mask was not supplied in the first decode call of this shot; \
260                             subsequent calls must not supply it either",
261                        ));
262                    }
263                }
264            }
265            state.outcomes.extend_from_slice(&outcomes);
266            assert!(state.outcomes.len() <= self.info.total_measurements, "too many outcomes");
267            is_complete = state.outcomes.len() == self.info.total_measurements;
268
269            // send outcomes that are sufficient to decode a gadget
270            while state.next_index < self.info.accumulated_measurements.len() {
271                if state.outcomes.len() < self.info.accumulated_measurements[state.next_index] {
272                    break; // insufficient outcomes
273                }
274                let gid = state.gid_vec[state.next_index];
275                let start = if state.next_index == 0 {
276                    0
277                } else {
278                    self.info.accumulated_measurements[state.next_index - 1]
279                };
280                let end = self.info.accumulated_measurements[state.next_index];
281                let slice: Vec<bool> = state.outcomes[start..end].into();
282                let bit_vector = BitVector {
283                    size: slice.len() as u64,
284                    data: crate::misc::bit_vector::pack_bits(&slice),
285                };
286                let loss_mask_bv = state.loss_mask.as_ref().map(|m| {
287                    let loss_slice: Vec<bool> = m[start..end].into();
288                    BitVector {
289                        size: loss_slice.len() as u64,
290                        data: crate::misc::bit_vector::pack_bits(&loss_slice),
291                    }
292                });
293                let dispatch_idx = state.dispatched_count;
294                let decoder_seed = state.decoder_seed.flatten();
295                state.dispatched_count += 1;
296                state.pending_readouts.push(None);
297
298                let coordinator_clone = coordinator.clone();
299                state.pending_decodes.spawn(async move {
300                    coordinator_clone
301                        .decode(coordinator::Outcomes {
302                            gid,
303                            outcomes: Some(bit_vector),
304                            modifiers: vec![],
305                            loss_mask: loss_mask_bv,
306                            decoder_seed,
307                        })
308                        .await
309                        .map(|readouts| (dispatch_idx, readouts))
310                });
311                state.next_index += 1;
312            }
313
314            // Drain already-completed tasks so the final call has less to join
315            while let Some(res) = state.pending_decodes.try_join_next() {
316                let (idx, readouts) = res.map_err(|e| Status::internal(format!("join error: {}", e)))??;
317                state.pending_readouts[idx] = Some(readouts);
318            }
319        }
320
321        if !is_complete {
322            // Partial measurement batch: return empty readouts (tasks are running in background)
323            return Ok(Response::new(BatchReadouts::default()));
324        }
325
326        // All measurements received: wait for remaining pending decode tasks to complete
327        {
328            let mut state = self.state.lock().await;
329            // First, drain all already-completed tasks without blocking
330            while let Some(res) = state.pending_decodes.try_join_next() {
331                let (idx, readouts) = res.map_err(|e| Status::internal(format!("join error: {}", e)))??;
332                state.pending_readouts[idx] = Some(readouts);
333            }
334            // Then await any still-running tasks (typically just the last spawned one)
335            while let Some(res) = state.pending_decodes.join_next().await {
336                let (idx, readouts) = res.map_err(|e| Status::internal(format!("join error: {}", e)))??;
337                state.pending_readouts[idx] = Some(readouts);
338            }
339        }
340
341        // Gather all readouts in order
342        let state = self.state.lock().await;
343        let readouts = state
344            .pending_readouts
345            .iter()
346            .cloned()
347            .map(|readouts| readouts.ok_or_else(|| Status::internal("missing readouts")))
348            .collect::<Result<_, _>>()?;
349        Ok(Response::new(BatchReadouts { readouts }))
350    }
351
352    async fn reset(&self, _request: Request<()>) -> std::result::Result<Response<()>, Status> {
353        let mut coordinator = self.wait_until_library_loaded().await;
354        self.reset_and_instantiate_all(&mut coordinator).await;
355        Ok(Response::new(()))
356    }
357}