cuddl::reference_database_file Class Reference

Host-owned reference sketches and labels, ready for binary storage or GPU upload. More...

Public Member Functions
kmer_blacklist const &	blacklist () const noexcept
reference_database_metadata	metadata () const noexcept
	Compatibility metadata and reference count.
std::span< std::string const >	names () const noexcept
	Reference labels in reference-ID order.
std::span< uint16_t const >	rows () const noexcept
	Winner scores in reference-ID order, one bucket row per genome.
template<uint32_t K, size_t BucketCount, typename Layout = default_register_layout>
Result< reference_database< K, BucketCount, Layout > >	upload (cuda::stream_ref stream) const
	Uploads reference score rows and labels without constructing an index.
Result< void >	save (std::filesystem::path const &path) const
	Writes a versioned, little-endian, CRC32-checked binary file.

Static Public Member Functions
template<uint32_t K, size_t BucketCount, typename Layout = default_register_layout>
static Result< reference_database_file >	build (std::span< std::filesystem::path const > paths, cuda::stream_ref stream, path_build_options options={})
	Builds one sketch per plain or gzip/BGZF FASTA/FASTQ file on the GPU.
template<uint32_t K, size_t BucketCount, typename Layout = default_register_layout>
static Result< reference_database_file >	build_from_sequences (std::span< sequence_genome const > genomes, cuda::stream_ref stream, sequence_build_options options={})
	Builds one sketch per genome from bases the caller already holds.
template<uint32_t K, size_t BucketCount, typename Layout = default_register_layout>
static Result< reference_database_file >	from_store (device_span< uint32_t const > store, std::span< std::string const > names, cuda::stream_ref stream, kmer_blacklist const &blacklist)
	Adopts a device store as the host rows this form saves.
static Result< reference_database_file >	load (std::filesystem::path const &path)
	Reads and validates a binary database without requiring a GPU.

Friends
class	reference_index_file
struct	detail::reference_file_assembly

Detailed Description

Host-owned reference sketches and labels, ready for binary storage or GPU upload.

One input file is one genome, including all of its FASTA/FASTQ records. Input order defines stable reference IDs; labels preserve the supplied paths. Files store winner-score rows and compatibility metadata. Upload creates row storage, not an index. Build and upload are synchronous. The supplied stream must outlive the uploaded database.

Definition at line 267 of file reference_database_file.cuh.

Member Function Documentation

blacklist()

kmer_blacklist const & cuddl::reference_database_file::blacklist ( ) const

inlinenoexcept

Definition at line 272 of file reference_database_file.cuh.

                                                                   {
        return blacklist_;
    }

Here is the caller graph for this function:

build()

template<uint32_t K, size_t BucketCount, typename Layout = default_register_layout>

static Result< reference_database_file > cuddl::reference_database_file::build ( std::span< std::filesystem::path const >  paths, cuda::stream_ref  stream, path_build_options  options = {}  )

inlinestatic

Builds one sketch per plain or gzip/BGZF FASTA/FASTQ file on the GPU.

K-mers never cross record boundaries or ambiguous bases. FASTQ qualities are validated and ignored. Loader threads compact and stage records into a device arena, and one batch kernel encodes every record in it, so the device is fed in large batches rather than slice by slice. Register rows stay on the device for a group of genomes and return to the host once per group. Empty genomes retain their IDs and have zero rows.

Definition at line 299 of file reference_database_file.cuh.

                                     {}
    ) try {
        // NVCC 13.3 crashes on CUDDL_TRY directly inside a try block. Keep its GNU statement
        // expressions in a separate lambda scope, outside the exception-catching function.
        return [&]() -> Result<reference_database_file> {
            using database_type = reference_database<K, BucketCount, Layout>;
            if (paths.size() > std::numeric_limits<uint32_t>::max() ||
                paths.size() >
                    std::numeric_limits<size_t>::max() / (BucketCount * sizeof(uint32_t))) {
                return Err(Error::resource("reference collection exceeds database capacity"));
            }
            reference_database_file result;
            result.metadata_ = {
                score_compatibility::current<K, BucketCount, Layout>(),
                static_cast<uint32_t>(paths.size())
            };
            CUDDL_TRY((result.set_blacklist<K, BucketCount>(options.blacklist, stream)));
            result.rows_.resize(paths.size() * BucketCount);
            result.names_.reserve(paths.size());
            // No inputs means no staging budget to resolve and nothing to encode.
            if (paths.empty()) return result;
            CUDDL_TRY((detail::stage_paths<K, BucketCount, Layout>(
                paths,
                stream,
                options.staging_bytes,
                options.parser_workers,
                options.transfer,
                options.decompression,
                options.direct_reads,
                options.statistics,
                result.download_rows<BucketCount>(stream),
                options.blacklist ? options.blacklist->get().view() : cuda::std::nullopt
            )));
            for (auto const& path : paths) result.names_.push_back(path.string());
            // Instantiate the same constraints as the destination GPU database.
            static_assert(sizeof(database_type) > 0);
            return result;
        }();
    } catch (cuda::cuda_error const& error) {
        return Err(Error::cuda(static_cast<cudaError_t>(error.status())));
    } catch (std::system_error const& error) {
        return Err(Error::resource(error.what()));
    } catch (std::bad_alloc const& error) {
        return Err(Error::resource(error.what()));
    }

build_from_sequences()

template<uint32_t K, size_t BucketCount, typename Layout = default_register_layout>

static Result< reference_database_file > cuddl::reference_database_file::build_from_sequences ( std::span< sequence_genome const >  genomes, cuda::stream_ref  stream, sequence_build_options  options = {}  )

inlinestatic

Builds one sketch per genome from bases the caller already holds.

Each genome supplies its records as spans of consecutive bases with the line breaks already removed, the shape a parsed FASTX record has. The caller keeps every byte alive until this returns, and the build is synchronous like build. Labels come from the genomes' names, and reference IDs follow the order of genomes.

Definition at line 357 of file reference_database_file.cuh.

                                         {}
    ) try {
        return [&]() -> Result<reference_database_file> {
            using database_type = reference_database<K, BucketCount, Layout>;
            if (genomes.size() > std::numeric_limits<uint32_t>::max() ||
                genomes.size() >
                    std::numeric_limits<size_t>::max() / (BucketCount * sizeof(uint32_t))) {
                return Err(Error::resource("reference collection exceeds database capacity"));
            }
            reference_database_file result;
            result.metadata_ = {
                score_compatibility::current<K, BucketCount, Layout>(),
                static_cast<uint32_t>(genomes.size())
            };
            CUDDL_TRY((result.set_blacklist<K, BucketCount>(options.blacklist, stream)));
            result.rows_.resize(genomes.size() * BucketCount);
            result.names_.reserve(genomes.size());
            if (genomes.empty()) return result;
            CUDDL_TRY((detail::stage_sequences<K, BucketCount, Layout>(
                genomes,
                stream,
                options.staging_bytes,
                options.statistics,
                result.download_rows<BucketCount>(stream),
                options.blacklist ? options.blacklist->get().view() : cuda::std::nullopt
            )));
            for (auto const& genome : genomes) result.names_.emplace_back(genome.name);
            static_assert(sizeof(database_type) > 0);
            return result;
        }();
    } catch (cuda::cuda_error const& error) {
        return Err(Error::cuda(static_cast<cudaError_t>(error.status())));
    } catch (std::system_error const& error) {
        return Err(Error::resource(error.what()));
    } catch (std::bad_alloc const& error) {
        return Err(Error::resource(error.what()));
    }

from_store()

template<uint32_t K, size_t BucketCount, typename Layout = default_register_layout>

static Result< reference_database_file > cuddl::reference_database_file::from_store ( device_span< uint32_t const >  store, std::span< std::string const >  names, cuda::stream_ref  stream, kmer_blacklist const &  blacklist  )

inlinestatic

Adopts a device store as the host rows this form saves.

A store holds BucketCount registers per reference, the layout a single sketch allocation has. A staged build and the streamed tile builder both write that layout.

names labels one reference each in store order, or is empty for a database without labels. The caller must supply the blacklist used to construct these registers, or an empty blacklist for unfiltered registers.

Definition at line 409 of file reference_database_file.cuh.

          {
        return [&]() -> Result<reference_database_file> {
            if (store.size() % BucketCount != 0) {
                return Err(Error::invalid_argument("a store must contain whole sketches"));
            }
            size_t const count = store.size() / BucketCount;
            if (!names.empty() && names.size() != count) {
                return Err(Error::invalid_argument("labels must be empty or name every reference"));
            }
            if (count != 0 && store.data() == nullptr) {
                return Err(Error::invalid_argument("a nonempty store must not be null"));
            }
            reference_database_file result;
            result.metadata_ = {
                score_compatibility::current<K, BucketCount, Layout>(), static_cast<uint32_t>(count)
            };
            if (!blacklist.keys().empty() && blacklist.kmer_length() != K) {
                return Err(Error::invalid_argument("store blacklist k mismatch"));
            }
            result.blacklist_ = blacklist;
            result.metadata_.compatibility.blacklist_identity = blacklist.identity();
            result.metadata_.compatibility.blacklist_version = blacklist.version();
            result.rows_.resize(count * BucketCount);
            if (count == 0) return result;
            CUDDL_TRY(detail::download_store<BucketCount>(store, result.rows_, stream));
            CUDDL_CUDA_TRY(stream.sync());
            result.names_.assign(names.begin(), names.end());
            return result;
        }();
    } catch (cuda::cuda_error const& error) {
        return Err(Error::cuda(static_cast<cudaError_t>(error.status())));
    } catch (std::bad_alloc const& error) {
        return Err(Error::resource(error.what()));
    }

Here is the call graph for this function:

load()

static Result< reference_database_file > cuddl::reference_database_file::load ( std::filesystem::path const &  path )

inlinestatic

Reads and validates a binary database without requiring a GPU.

Definition at line 550 of file reference_database_file.cuh.

          {
        return [&]() -> Result<reference_database_file> {
            detail::database_file_reader reader{
                std::ifstream(path, std::ios::binary | std::ios::ate)
            };
            auto size = reader.input.tellg();
            if (size < 0) {
                return Err(Error::resource("cannot open database file: " + path.string()));
            }
            reader.remaining = static_cast<uint64_t>(size);
            reader.input.seekg(0);
            char magic[8];
            CUDDL_TRY(reader.bytes(magic, sizeof(magic)));
            if (std::string_view(magic, sizeof(magic)) != std::string_view("CUDDLDB\0", 8)) {
                return Err(Error::invalid_argument("not a cuDDL reference database file"));
            }
            uint16_t version{};
            CUDDL_TRY(reader.value(version));
            if (version != database_file_version) {
                return Err(Error::invalid_argument("unsupported database file version"));
            }
            reference_database_file result;
            uint32_t blacklist_count = 0;
            CUDDL_TRY(detail::database_file_metadata(reader, result.metadata_, blacklist_count));
            auto& c = result.metadata_.compatibility;
            if (c.kmer_length < 1 || c.kmer_length > 31 || c.bucket_count < 2048 ||
                c.bucket_count > 8192 || !std::has_single_bit(c.bucket_count) ||
                (c.key_mask != 0xffffU && c.key_mask != 0x7fffU) || c.exponent_bits == 0 ||
                c.exponent_bits >= 16) {
                return Err(Error::invalid_argument("unsupported database construction metadata"));
            }
            c.indexed_bucket_count = c.bucket_count;
            c.mantissa_bits = 16U - c.exponent_bits;
            c.score_encoder_identity = 1U;
            c.hash_identity = 1U;
            c.hash_seed = detail::seed;
            c.canonicalisation_policy = 1U;
            c.blacklist_version = blacklist_count == 0 ? 0U : 1U;
            if (blacklist_count > reader.remaining / sizeof(uint64_t)) {
                return Err(Error::invalid_argument("invalid blacklist extent"));
            }
            std::vector<uint64_t> keys(blacklist_count);
            CUDDL_TRY(reader.words(keys));
            if (!std::is_sorted(keys.begin(), keys.end()) ||
                std::adjacent_find(keys.begin(), keys.end()) != keys.end()) {
                return Err(Error::invalid_argument("blacklist payload is not sorted and unique"));
            }
            result.blacklist_ = kmer_blacklist(c.kmer_length, std::move(keys));
            if (result.blacklist_.identity() != c.blacklist_identity ||
                result.blacklist_.version() != c.blacklist_version) {
                return Err(Error::invalid_argument("blacklist identity mismatch"));
            }
            uint64_t const count = result.metadata_.reference_count;
            uint64_t const words = count * c.bucket_count;
            uint64_t const payload_bytes = words * sizeof(uint16_t);
            if (words > std::numeric_limits<size_t>::max() / sizeof(uint16_t) ||
                payload_bytes + count * sizeof(uint32_t) + sizeof(uint32_t) > reader.remaining) {
                return Err(Error::invalid_argument("invalid reference database extents"));
            }
            result.names_.reserve(count);
            for (uint64_t id = 0; id < count; ++id) {
                uint32_t length{};
                CUDDL_TRY(reader.value(length));
                auto const required =
                    payload_bytes + (count - id - 1) * sizeof(uint32_t) + sizeof(uint32_t);
                if (required > reader.remaining || length > reader.remaining - required) {
                    return Err(Error::invalid_argument("invalid reference label extent"));
                }
                std::string name(length, '\0');
                CUDDL_TRY(reader.bytes(name.data(), name.size()));
                result.names_.push_back(std::move(name));
            }
            if (reader.remaining != payload_bytes + sizeof(uint32_t)) {
                return Err(Error::invalid_argument("unexpected reference database payload size"));
            }
            result.rows_.resize(words);
            CUDDL_TRY(reader.words(result.rows_));
            auto const expected_checksum = static_cast<uint32_t>(reader.checksum);
            uint32_t checksum{};
            CUDDL_TRY(reader.value(checksum));
            if (checksum != expected_checksum) {
                return Err(Error::invalid_argument("database checksum mismatch"));
            }
            return result;
        }();
    } catch (std::invalid_argument const& error) {
        return Err(Error::invalid_argument(error.what()));
    } catch (std::bad_alloc const& error) {
        return Err(Error::resource(error.what()));
    }

Here is the call graph for this function:

metadata()

reference_database_metadata cuddl::reference_database_file::metadata ( ) const

inlinenoexcept

Compatibility metadata and reference count.

Definition at line 277 of file reference_database_file.cuh.

                                                                        {
        return metadata_;
    }

Here is the caller graph for this function:

names()

std::span< std::string const > cuddl::reference_database_file::names ( ) const

inlinenoexcept

Reference labels in reference-ID order.

Definition at line 281 of file reference_database_file.cuh.

                                                                  {
        return names_;
    }

Here is the caller graph for this function:

rows()

std::span< uint16_t const > cuddl::reference_database_file::rows ( ) const

inlinenoexcept

Winner scores in reference-ID order, one bucket row per genome.

Definition at line 285 of file reference_database_file.cuh.

                                                                {
        return rows_;
    }

Here is the caller graph for this function:

save()

Result< void > cuddl::reference_database_file::save ( std::filesystem::path const &  path ) const

inline

Writes a versioned, little-endian, CRC32-checked binary file.

Writes to an exclusive temporary file in the destination directory, closes it, then atomically replaces the destination. Failure leaves an existing destination intact. This guarantees atomic publication, not durability across power loss.

Definition at line 474 of file reference_database_file.cuh.

                                                                             {
        return [&]() -> Result<void> {
            detail::database_file_writer writer;
            writer.temporary = path.string() + ".tmp.XXXXXX";
            auto fd = ::mkstemp(writer.temporary.data());
            if (fd < 0) {
                writer.temporary.clear();
                return Err(Error::resource("cannot create database file beside: " + path.string()));
            }
            writer.output = ::fdopen(fd, "wb");
            if (!writer.output) {
                ::close(fd);
                return Err(Error::resource("cannot open temporary database file"));
            }
            CUDDL_TRY(writer.bytes("CUDDLDB\0", 8));
            CUDDL_TRY(writer.value(database_file_version));
            auto metadata = metadata_;
            if (blacklist_.identity() != metadata.compatibility.blacklist_identity ||
                blacklist_.version() != metadata.compatibility.blacklist_version) {
                return Err(
                    Error::invalid_argument("database is missing its construction blacklist")
                );
            }
            auto blacklist_count = static_cast<uint32_t>(blacklist_.keys().size());
            CUDDL_TRY(detail::database_file_metadata(writer, metadata, blacklist_count));
            CUDDL_TRY(writer.words(blacklist_.keys()));
            auto const prefix = ::ftello(writer.output);
            auto const limit = static_cast<uint64_t>(std::numeric_limits<off_t>::max());
            if (prefix < 0 || static_cast<uint64_t>(prefix) > limit - sizeof(uint32_t)) {
                return Err(Error::resource("cannot size temporary database file"));
            }
            uint64_t bytes = static_cast<uint64_t>(prefix) + sizeof(uint32_t);
            if (rows_.size() > (limit - bytes) / sizeof(uint16_t)) {
                return Err(Error::resource("database exceeds file size capacity"));
            }
            bytes += rows_.size() * sizeof(uint16_t);
            for (auto const& name : names_) {
                if (name.size() > std::numeric_limits<uint32_t>::max()) {
                    return Err(Error::resource("reference label exceeds binary format capacity"));
                }
                if (bytes > limit - sizeof(uint32_t) ||
                    name.size() > limit - bytes - sizeof(uint32_t)) {
                    return Err(Error::resource("database exceeds file size capacity"));
                }
                bytes += sizeof(uint32_t) + name.size();
            }
            // Allocate before names spill from stdio, avoiding delayed extent allocation when
            // the completed temporary file atomically replaces an existing database.
            auto const allocation = ::posix_fallocate(fd, 0, static_cast<off_t>(bytes));
            if (allocation != 0 && allocation != EOPNOTSUPP && allocation != ENOSYS) {
                return Err(
                    Error::resource(
                        "cannot allocate database file: " +
                        std::generic_category().message(allocation)
                    )
                );
            }
            for (auto const& name : names_) {
                CUDDL_TRY(writer.value(static_cast<uint32_t>(name.size())));
                CUDDL_TRY(writer.bytes(name.data(), name.size()));
            }
            CUDDL_TRY(writer.words(rows_));
            CUDDL_TRY(writer.value(static_cast<uint32_t>(writer.checksum)));
            auto closed = std::fclose(std::exchange(writer.output, nullptr));
            if (closed != 0) return Err(Error::resource("cannot close database file"));
            std::filesystem::rename(writer.temporary, path);
            writer.temporary.clear();
            return Ok();
        }();
    } catch (std::filesystem::filesystem_error const& error) {
        return Err(Error::resource(error.what()));
    } catch (std::bad_alloc const& error) {
        return Err(Error::resource(error.what()));
    }

Here is the call graph for this function:

upload()

template<uint32_t K, size_t BucketCount, typename Layout = default_register_layout>

Result< reference_database< K, BucketCount, Layout > > cuddl::reference_database_file::upload ( cuda::stream_ref  stream ) const

inline

Uploads reference score rows and labels without constructing an index.

Definition at line 451 of file reference_database_file.cuh.

            {
        CUDDL_TRY((detail::validate_indexed_score_compatibility<K, BucketCount, Layout>(
            metadata_.compatibility
        )));
        auto rows =
            CUDDL_CUDA_TRY(cuda::make_device_buffer<uint16_t>(stream, stream.device(), rows_));
        auto database = CUDDL_TRY((reference_database<K, BucketCount, Layout>::build_async(
            {rows.data(), rows.size()}, metadata_.compatibility, stream
        )));
        database.names_ = names_;
        CUDDL_CUDA_TRY(stream.sync());
        return std::move(database);
    }

Here is the call graph for this function:

Friends And Related Symbol Documentation

detail::reference_file_assembly

friend struct detail::reference_file_assembly

friend

Definition at line 645 of file reference_database_file.cuh.

reference_index_file

friend class reference_index_file

friend

Definition at line 644 of file reference_database_file.cuh.

---

The documentation for this class was generated from the following file:

• reference_database_file.cuh