Skip to main content

triblespace_gpu/
succinct_mapping.rs

1//! An execution choice for the existing canonical collection mapping.
2
3use std::sync::OnceLock;
4
5use triblespace_core::blob::encodings::simplearchive::SimpleArchive;
6use triblespace_core::blob::encodings::succinctarchive::{
7    SuccinctArchiveBlob, WaveletMatrixFreezeBackend,
8};
9use triblespace_core::blob::Blob;
10use triblespace_core::collection::{
11    CollectionAttachment, CollectionData, CollectionOperationError, MapMapping,
12};
13use triblespace_core::repo::StoreRead;
14use triblespace_core::trible::Fragment;
15
16/// Raw Succinct attachments built with one wavelet backend.
17///
18/// The descriptor is exactly the canonical SimpleArchive-to-Succinct attached
19/// descriptor: a device is an execution choice, never part of a collection's
20/// identity, so the attached collection is the same whichever builds it.
21/// `map` uses the raw writer, without a native query arena. Returned
22/// construction/backend failures retry the canonical CPU operation;
23/// allocation failure, runtime panic and OOM are not caught. Callers must
24/// reserve a device and sufficient shared memory before selecting this
25/// mapping. Binding is device-free. The first actual `map` initializes the
26/// backend; later operations on that binding reuse it. CubeCL retains its
27/// client/shader/allocator caches through its existing runtime.
28pub struct BackendSuccinctMapping<B> {
29    backend: OnceLock<B>,
30}
31
32impl<B> BackendSuccinctMapping<B> {
33    /// Select an already initialized backend for direct mapping operations.
34    pub fn new(backend: B) -> Self {
35        Self {
36            backend: OnceLock::from(backend),
37        }
38    }
39}
40
41impl<B> MapMapping for BackendSuccinctMapping<B>
42where
43    B: WaveletMatrixFreezeBackend + Default,
44    B::Error: std::fmt::Display,
45{
46    type Target = SuccinctArchiveBlob;
47
48    fn fragment(&self) -> Fragment {
49        <SuccinctArchiveBlob as CollectionAttachment>::fragment(&())
50    }
51
52    fn bind(parent: &Fragment, attached: &Fragment) -> Result<Self, CollectionOperationError> {
53        <SuccinctArchiveBlob as CollectionAttachment>::bind(parent, attached)?;
54        Ok(Self {
55            backend: OnceLock::new(),
56        })
57    }
58
59    fn map<R>(
60        &self,
61        node: &Blob<SimpleArchive>,
62        siblings: &[CollectionData],
63        reader: &R,
64    ) -> Result<Blob<SuccinctArchiveBlob>, CollectionOperationError>
65    where
66        R: StoreRead,
67    {
68        match SuccinctArchiveBlob::build_from_simple_archive_with_backend(
69            node,
70            self.backend.get_or_init(B::default),
71        ) {
72            Ok(output) => Ok(output),
73            Err(error) => {
74                tracing::warn!(%error, "Succinct backend build failed; retrying canonical CPU build");
75                <SuccinctArchiveBlob as CollectionAttachment>::map(&(), node, siblings, reader)
76            }
77        }
78    }
79}
80
81/// Canonical raw Succinct maintenance on the default CUDA device.
82#[cfg(feature = "cuda")]
83pub type CudaSuccinctMapping = BackendSuccinctMapping<crate::CudaWaveletFreeze>;