Skip to main content

deq_runtime/decoder/
thread_pooling.rs

1//! Decoder with thread pooling
2//!
3
4use crate::decoder::blackbox_decoder::{self, ParityFactor, black_box_decoder_server};
5pub use crate::decoder::decoder_features::DecoderFeatures;
6use crate::misc::bit_vector;
7use crate::misc::validation;
8use crate::util::BitVector;
9use blackbox_decoder::DecodingHypergraph;
10use hashbrown::HashMap;
11use serde::{Deserialize, Serialize};
12use std::collections::LinkedList;
13use std::fmt;
14use std::sync::Arc;
15use std::sync::atomic::{AtomicU64, Ordering};
16#[cfg(feature = "cli")]
17use structdoc::StructDoc;
18use tokio::sync::{Mutex, oneshot, watch};
19#[cfg(feature = "cli")]
20use tonic::transport::server::Router;
21use tonic::{Request, Response, Status};
22
23#[derive(Debug, Clone, Serialize, Deserialize)]
24#[cfg_attr(feature = "cli", derive(StructDoc))]
25pub struct ThreadPoolingConfig {
26    /// number of parallel threads in the pool, default to number of logical cores
27    #[serde(default)]
28    pub parallel: usize,
29}
30
31pub struct ThreadPoolingDecoder<T: DecoderInstance> {
32    pub config: ThreadPoolingConfig,
33    pub original_config: Arc<serde_json::Value>,
34    pub thread_pool: Arc<rayon::ThreadPool>,
35    loaded: Arc<Mutex<HashMap<u64, Loaded<T>>>>,
36    next_hid: AtomicU64,
37    decoding: watch::Sender<usize>,
38    features: DecoderFeatures,
39}
40
41pub struct Loaded<T: DecoderInstance> {
42    hypergraph: Arc<DecodingHypergraph>,
43    instances: LinkedList<T>,
44}
45
46// Cancellation-safe guard for the `decoding` counter.
47// Decrements on drop unless `defuse()` is called (happy path).
48struct DecodingGuard {
49    tx: Option<watch::Sender<usize>>,
50}
51
52impl DecodingGuard {
53    fn new(tx: watch::Sender<usize>) -> Self {
54        Self { tx: Some(tx) }
55    }
56
57    fn defuse(&mut self) {
58        self.tx.take();
59    }
60}
61
62impl Drop for DecodingGuard {
63    fn drop(&mut self) {
64        if let Some(tx) = self.tx.take() {
65            tx.send_modify(|v| {
66                *v -= 1;
67            });
68        }
69    }
70}
71
72impl<T: DecoderInstance> std::fmt::Debug for Loaded<T> {
73    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
74        f.debug_struct("Loaded")
75            .field("hypergraph", &self.hypergraph)
76            .finish_non_exhaustive()
77    }
78}
79
80pub struct DecodeRequest<'a> {
81    pub syndrome: &'a BitVector,
82    /// Optional deterministic seed for decoder randomness. Zero is valid.
83    pub decoder_seed: Option<u64>,
84    /// Shot-scoped prior assignments. Implementations must not let these values
85    /// affect a later request served by the same pooled instance.
86    pub reweights: &'a [(u64, f64)],
87    /// Structured loss observation for this shot. Independent of `reweights`;
88    /// a decoder advertising both features must accept both together.
89    pub loss: Option<&'a blackbox_decoder::LossInfo>,
90}
91
92impl DecodeRequest<'_> {
93    fn required_features(&self) -> DecoderFeatures {
94        DecoderFeatures::required(self.decoder_seed.is_some(), !self.reweights.is_empty(), self.loss.is_some())
95    }
96
97    fn require_supported(&self, supported: DecoderFeatures) -> Result<(), DecodeError> {
98        self.required_features()
99            .require_supported_by(supported)
100            .map_err(DecodeError::Unsupported)
101    }
102}
103
104#[derive(Debug, Clone, PartialEq, Eq)]
105pub enum DecodeError {
106    Unsupported(DecoderFeatures),
107    InvalidInput(String),
108    Backend(String),
109}
110
111impl fmt::Display for DecodeError {
112    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
113        match self {
114            Self::Unsupported(features) => write!(formatter, "unsupported decoder features: {features}"),
115            Self::InvalidInput(message) => write!(formatter, "invalid decode request: {message}"),
116            Self::Backend(message) => write!(formatter, "decoder backend failed: {message}"),
117        }
118    }
119}
120
121impl std::error::Error for DecodeError {}
122
123pub trait DecoderInstance {
124    #[must_use]
125    fn supported_features(_config: &serde_json::Value) -> DecoderFeatures {
126        DecoderFeatures::empty()
127    }
128
129    /// Validates constraints imposed by a specific decoder backend.
130    /// Runs before common validation and must handle structurally invalid input.
131    ///
132    /// # Errors
133    ///
134    /// Returns an error when the hypergraph cannot be represented by the backend.
135    fn validate_hypergraph(_hypergraph: &DecodingHypergraph, _config: &serde_json::Value) -> Result<(), String> {
136        Ok(())
137    }
138
139    fn new(hypergraph: &DecodingHypergraph, config: &serde_json::Value) -> Self;
140
141    fn decode(&mut self, request: DecodeRequest<'_>) -> Result<ParityFactor, DecodeError>;
142
143    fn reset(&mut self);
144}
145
146impl<T: DecoderInstance + Send + 'static> ThreadPoolingDecoder<T> {
147    #[must_use]
148    pub fn features(&self) -> DecoderFeatures {
149        self.features
150    }
151
152    /// # Panics
153    ///
154    /// Panics when `original_config` is invalid for thread pooling or the Rayon
155    /// pool cannot be created.
156    #[must_use]
157    pub fn new(original_config: serde_json::Value) -> Self {
158        Self::with_thread_pool(original_config, None)
159    }
160
161    pub(crate) fn with_thread_pool(original_config: serde_json::Value, thread_pool: Option<Arc<rayon::ThreadPool>>) -> Self {
162        let mut config: ThreadPoolingConfig = serde_json::from_value(original_config.clone()).unwrap();
163        let features = T::supported_features(&original_config);
164        let thread_pool = if let Some(thread_pool) = thread_pool {
165            config.parallel = thread_pool.current_num_threads();
166            thread_pool
167        } else {
168            let mut thread_pool_builder = rayon::ThreadPoolBuilder::new();
169            if config.parallel != 0 {
170                thread_pool_builder = thread_pool_builder.num_threads(config.parallel);
171            }
172            Arc::new(
173                thread_pool_builder
174                    .panic_handler(|error| {
175                        eprintln!("rayon pool thread panicked: {error:?}");
176                    })
177                    .build()
178                    .expect("creating thread pool failed"),
179            )
180        };
181        Self {
182            config,
183            original_config: Arc::new(original_config),
184            thread_pool,
185            loaded: Default::default(),
186            next_hid: AtomicU64::new(1),
187            decoding: watch::channel(0).0,
188            features,
189        }
190    }
191
192    #[cfg(feature = "cli")]
193    #[must_use]
194    pub fn add_service(self: &Arc<Self>, router: Router) -> Router {
195        let service =
196            black_box_decoder_server::BlackBoxDecoderServer::from_arc(self.clone()).max_decoding_message_size(usize::MAX);
197        router.add_service(service)
198    }
199}
200
201#[tonic::async_trait]
202impl<T: DecoderInstance + Send + 'static> black_box_decoder_server::BlackBoxDecoder for ThreadPoolingDecoder<T> {
203    async fn get_capabilities(
204        &self,
205        _request: Request<()>,
206    ) -> Result<Response<blackbox_decoder::DecoderCapabilities>, Status> {
207        Ok(Response::new(self.features.to_proto()))
208    }
209
210    async fn decode(
211        &self,
212        request: Request<blackbox_decoder::DecodingProblem>,
213    ) -> Result<Response<blackbox_decoder::ParityFactor>, Status> {
214        let problem = request.into_inner();
215        let syndrome = problem
216            .syndrome
217            .as_ref()
218            .ok_or_else(|| Status::invalid_argument("missing syndrome"))?;
219        if problem.hypergraph.is_none() {
220            return Err(Status::invalid_argument("missing hypergraph"));
221        }
222        {
223            let hypergraph = problem.hypergraph.as_ref().unwrap();
224            T::validate_hypergraph(hypergraph, &self.original_config).map_err(Status::invalid_argument)?;
225            validation::validate_hypergraph(hypergraph).map_err(Status::invalid_argument)?;
226            validation::validate_syndrome(syndrome, hypergraph.vertex_num).map_err(Status::invalid_argument)?;
227            validation::validate_loss(problem.loss.as_ref(), hypergraph.hyperedges.len())
228                .map_err(Status::invalid_argument)?;
229        }
230        let request = DecodeRequest {
231            syndrome,
232            decoder_seed: problem.decoder_seed,
233            reweights: &[],
234            loss: problem.loss.as_ref(),
235        };
236        request.require_supported(self.features).map_err(decode_error_status)?;
237        // Observable metadata and optional request fields can affect a
238        // zero-syndrome correction.
239        if bit_vector::is_zero(syndrome)
240            && request.required_features().is_empty()
241            && !self.features.contains(DecoderFeatures::OBSERVABLES)
242        {
243            return Ok(Response::new(ParityFactor { subgraph: vec![] }));
244        }
245        let (tx, rx) = oneshot::channel::<Result<ParityFactor, DecodeError>>();
246        let original_config = self.original_config.clone();
247        self.decoding.send_modify(|v| {
248            *v += 1;
249        });
250        // Use a drop guard so the counter is decremented even if this future
251        // is cancelled (e.g. by tokio::select! picking a cancellation branch).
252        // Without this, a cancelled decode leaks a +1 in the counter, causing
253        // black_box_decoder.reset() to wait forever.
254        let mut decoding_guard = DecodingGuard::new(self.decoding.clone());
255        let decoding_tx = self.decoding.clone();
256        self.thread_pool.spawn(move || {
257            let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
258                let hypergraph = problem.hypergraph.as_ref().unwrap();
259                let mut instance = T::new(hypergraph, &original_config);
260                instance
261                    .decode(DecodeRequest {
262                        syndrome: problem.syndrome.as_ref().unwrap(),
263                        decoder_seed: problem.decoder_seed,
264                        reweights: &[],
265                        loss: problem.loss.as_ref(),
266                    })
267                    .and_then(|parity_factor| {
268                        validation::validate_parity_factor(parity_factor, hypergraph.hyperedges.len())
269                            .map_err(DecodeError::Backend)
270                    })
271            }));
272            match result {
273                Ok(decode_result) => {
274                    let _ = tx.send(decode_result);
275                }
276                Err(_) => {
277                    eprintln!("decoder panicked during decode");
278                }
279            }
280            decoding_tx.send_modify(|v| {
281                *v -= 1;
282            });
283        });
284        // The worker owns the decrement from here. A cancelled RPC drops its
285        // receiver, but reset must still wait for the backend work to finish.
286        decoding_guard.defuse();
287        let parity_factor = rx
288            .await
289            .map_err(|_| Status::internal("decode panicked or was cancelled"))?
290            .map_err(decode_error_status)?;
291        Ok(parity_factor.into())
292    }
293
294    async fn load_hypergraph(
295        &self,
296        request: Request<blackbox_decoder::DecodingHypergraph>,
297    ) -> Result<Response<blackbox_decoder::LoadHypergraphResponse>, Status> {
298        let hypergraph = Arc::new(request.into_inner());
299        T::validate_hypergraph(&hypergraph, &self.original_config).map_err(Status::invalid_argument)?;
300        validation::validate_hypergraph(&hypergraph).map_err(Status::invalid_argument)?;
301        let hid = self.next_hid.fetch_add(1, Ordering::Relaxed);
302        let (tx, rx) = oneshot::channel::<Result<(T, Arc<DecodingHypergraph>, DecodingGuard), Status>>();
303        let original_config = self.original_config.clone();
304        self.decoding.send_modify(|count| *count += 1);
305        let decoding_guard = DecodingGuard::new(self.decoding.clone());
306        self.thread_pool.spawn(move || {
307            let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| T::new(&hypergraph, &original_config)));
308            let result = match result {
309                Ok(instance) => Ok((instance, hypergraph, decoding_guard)),
310                Err(_) => {
311                    eprintln!("decoder panicked during load_hypergraph (hid={hid})");
312                    Err(Status::internal(format!("hid={hid} load panicked")))
313                }
314            };
315            let _ = tx.send(result);
316        });
317        let (instance, hypergraph, decoding_guard) = rx
318            .await
319            .map_err(|_| Status::internal(format!("hid={hid} load was cancelled")))??;
320        let mut instances = LinkedList::new();
321        instances.push_back(instance);
322        self.loaded.lock().await.insert(hid, Loaded { hypergraph, instances });
323        drop(decoding_guard);
324        Ok(Response::new(blackbox_decoder::LoadHypergraphResponse { hid }))
325    }
326
327    async fn decode_loaded(
328        &self,
329        request: Request<blackbox_decoder::LoadedDecodingProblem>,
330    ) -> Result<Response<blackbox_decoder::ParityFactor>, Status> {
331        let problem = request.into_inner();
332        let syndrome = problem
333            .syndrome
334            .as_ref()
335            .ok_or_else(|| Status::invalid_argument("missing syndrome"))?;
336        let reweights: Vec<(u64, f64)> = problem
337            .reweights
338            .iter()
339            .map(|value| (value.edge, value.probability))
340            .collect();
341        let request = DecodeRequest {
342            syndrome,
343            decoder_seed: problem.decoder_seed,
344            reweights: &reweights,
345            loss: problem.loss.as_ref(),
346        };
347        request.require_supported(self.features).map_err(decode_error_status)?;
348        // Increment counter BEFORE accessing the loaded map, so that
349        // reset() always sees counter > 0 while we're processing.
350        self.decoding.send_modify(|v| {
351            *v += 1;
352        });
353        let decoding_guard = DecodingGuard::new(self.decoding.clone());
354        let (instance, hypergraph, edge_count) = {
355            let mut guard = self.loaded.lock().await;
356            let Some(loaded) = guard.get_mut(&problem.hid) else {
357                return Err(Status::not_found(format!("hid={}", problem.hid)));
358            };
359            let edge_count = loaded.hypergraph.hyperedges.len();
360            validation::validate_syndrome(syndrome, loaded.hypergraph.vertex_num).map_err(Status::invalid_argument)?;
361            validation::validate_reweights(&reweights, edge_count).map_err(Status::invalid_argument)?;
362            validation::validate_loss(problem.loss.as_ref(), edge_count).map_err(Status::invalid_argument)?;
363            // Validate the handle and side information before applying the
364            // plain-request zero-syndrome shortcut.
365            if bit_vector::is_zero(syndrome)
366                && request.required_features().is_empty()
367                && !self.features.contains(DecoderFeatures::OBSERVABLES)
368            {
369                return Ok(Response::new(ParityFactor { subgraph: vec![] }));
370            }
371            let instance = loaded.instances.pop_back();
372            let hypergraph = instance.is_none().then(|| Arc::clone(&loaded.hypergraph));
373            (instance, hypergraph, edge_count)
374        };
375        let (tx, rx) = oneshot::channel::<Result<(ParityFactor, Option<T>, DecodingGuard), DecodeError>>();
376        let original_config = instance.is_none().then(|| Arc::clone(&self.original_config));
377        let hid = problem.hid;
378        self.thread_pool.spawn(move || {
379            let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
380                let mut instance =
381                    instance.unwrap_or_else(|| T::new(hypergraph.as_deref().unwrap(), original_config.as_deref().unwrap()));
382                let decode_result = instance
383                    .decode(DecodeRequest {
384                        syndrome: problem.syndrome.as_ref().unwrap(),
385                        decoder_seed: problem.decoder_seed,
386                        reweights: &reweights,
387                        loss: problem.loss.as_ref(),
388                    })
389                    .and_then(|parity_factor| {
390                        validation::validate_parity_factor(parity_factor, edge_count).map_err(DecodeError::Backend)
391                    });
392                (instance, decode_result)
393            }));
394            match result {
395                Ok((mut instance, Ok(parity_factor))) => {
396                    let reset_succeeded =
397                        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| instance.reset())).is_ok();
398                    if !reset_succeeded {
399                        eprintln!("decoder panicked during reset after decode_loaded (hid={hid})");
400                    }
401                    let instance = reset_succeeded.then_some(instance);
402                    let _ = tx.send(Ok((parity_factor, instance, decoding_guard)));
403                }
404                Ok((_instance, Err(error))) => {
405                    let _ = tx.send(Err(error));
406                }
407                Err(_) => {
408                    eprintln!("decoder panicked during decode_loaded (hid={hid})");
409                }
410            }
411        });
412        let (parity_factor, instance, decoding_guard) = rx
413            .await
414            .map_err(|_| Status::internal("decode panicked or was cancelled"))?
415            .map_err(decode_error_status)?;
416        if let Some(instance) = instance {
417            let mut guard = self.loaded.lock().await;
418            if let Some(loaded) = guard.get_mut(&hid) {
419                loaded.instances.push_back(instance);
420            }
421        }
422        drop(decoding_guard);
423        Ok(parity_factor.into())
424    }
425
426    async fn reset(&self, request: Request<blackbox_decoder::ResetRequest>) -> Result<Response<()>, Status> {
427        let flags = request.into_inner();
428        if flags.reset_hypergraphs {
429            // Acquire the loaded lock and check the counter atomically.
430            // Since decode_loaded increments the counter BEFORE acquiring
431            // this lock, seeing counter==0 while holding the lock guarantees
432            // no decode_loaded is active or about to start.
433            loop {
434                let mut loaded = self.loaded.lock().await;
435                if *self.decoding.borrow() == 0 {
436                    loaded.clear();
437                    break;
438                }
439                // In-flight decodes need the lock to return instances,
440                // so drop it and wait for them to finish.
441                drop(loaded);
442                let mut rx = self.decoding.subscribe();
443                rx.wait_for(|v| *v == 0).await.unwrap();
444            }
445        } else if *self.decoding.borrow() > 0 {
446            let mut rx = self.decoding.subscribe();
447            rx.wait_for(|v| *v == 0).await.unwrap();
448        }
449        Ok(().into())
450    }
451}
452
453fn decode_error_status(error: DecodeError) -> Status {
454    match error {
455        DecodeError::Unsupported(_) => Status::failed_precondition(error.to_string()),
456        DecodeError::InvalidInput(_) => Status::invalid_argument(error.to_string()),
457        DecodeError::Backend(_) => Status::internal(error.to_string()),
458    }
459}