triblespace-gpu 0.47.0

Opt-in GPU acceleration backends for TribleSpace
Documentation
//! An execution choice for the existing canonical collection mapping.

use std::sync::OnceLock;

use triblespace_core::blob::encodings::simplearchive::SimpleArchive;
use triblespace_core::blob::encodings::succinctarchive::{
    SuccinctArchiveBlob, WaveletMatrixFreezeBackend,
};
use triblespace_core::blob::Blob;
use triblespace_core::collection::{
    CollectionAttachment, CollectionData, CollectionOperationError, MapMapping,
};
use triblespace_core::repo::StoreRead;
use triblespace_core::trible::Fragment;

/// Raw Succinct attachments built with one wavelet backend.
///
/// The descriptor is exactly the canonical SimpleArchive-to-Succinct attached
/// descriptor: a device is an execution choice, never part of a collection's
/// identity, so the attached collection is the same whichever builds it.
/// `map` uses the raw writer, without a native query arena. Returned
/// construction/backend failures retry the canonical CPU operation;
/// allocation failure, runtime panic and OOM are not caught. Callers must
/// reserve a device and sufficient shared memory before selecting this
/// mapping. Binding is device-free. The first actual `map` initializes the
/// backend; later operations on that binding reuse it. CubeCL retains its
/// client/shader/allocator caches through its existing runtime.
pub struct BackendSuccinctMapping<B> {
    backend: OnceLock<B>,
}

impl<B> BackendSuccinctMapping<B> {
    /// Select an already initialized backend for direct mapping operations.
    pub fn new(backend: B) -> Self {
        Self {
            backend: OnceLock::from(backend),
        }
    }
}

impl<B> MapMapping for BackendSuccinctMapping<B>
where
    B: WaveletMatrixFreezeBackend + Default,
    B::Error: std::fmt::Display,
{
    type Target = SuccinctArchiveBlob;

    fn fragment(&self) -> Fragment {
        <SuccinctArchiveBlob as CollectionAttachment>::fragment(&())
    }

    fn bind(parent: &Fragment, attached: &Fragment) -> Result<Self, CollectionOperationError> {
        <SuccinctArchiveBlob as CollectionAttachment>::bind(parent, attached)?;
        Ok(Self {
            backend: OnceLock::new(),
        })
    }

    fn map<R>(
        &self,
        node: &Blob<SimpleArchive>,
        siblings: &[CollectionData],
        reader: &R,
    ) -> Result<Blob<SuccinctArchiveBlob>, CollectionOperationError>
    where
        R: StoreRead,
    {
        match SuccinctArchiveBlob::build_from_simple_archive_with_backend(
            node,
            self.backend.get_or_init(B::default),
        ) {
            Ok(output) => Ok(output),
            Err(error) => {
                tracing::warn!(%error, "Succinct backend build failed; retrying canonical CPU build");
                <SuccinctArchiveBlob as CollectionAttachment>::map(&(), node, siblings, reader)
            }
        }
    }
}

/// Canonical raw Succinct maintenance on the default CUDA device.
#[cfg(feature = "cuda")]
pub type CudaSuccinctMapping = BackendSuccinctMapping<crate::CudaWaveletFreeze>;