1use 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 #[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
46struct 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 pub decoder_seed: Option<u64>,
84 pub reweights: &'a [(u64, f64)],
87 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 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 #[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 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 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 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 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 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 loop {
434 let mut loaded = self.loaded.lock().await;
435 if *self.decoding.borrow() == 0 {
436 loaded.clear();
437 break;
438 }
439 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}