Add byte-oriented sizing and validation for Bloom filters

[yuweih205]

Callers with a byte budget currently have to convert it to block counts and repeat the policy's sizing constraints. Add bloom_filter_size_bytes construction, aligned_size(bytes) to round down and cap a budget, and max_size() to expose the byte limit.

The byte constructor checks positive, block-aligned sizes, capacity limits, and static extent compatibility before delegating to the block-count constructor. Capacity calculations account for the policy, extent value type, and std::size_t range. The new Catch2 cases join the existing BLOOM_FILTER_TEST target and cover byte sizing and construction.

using filter = cuco::bloom_filter<int>;
auto const bytes = filter::aligned_size(1024 * 1024);
filter bf{cuco::bloom_filter_size_bytes{bytes}};

Fixes #829.

Validation of the current revision

Environment / check	Experiment	Result
CUDA 12.0.140, GCC 11.5.0, C++17, SM70/80 compilation	Build the complete BLOOM_FILTER_TEST target; run [sizing][host]	Build passed; 3 cases / 21 assertions passed
CUDA 13.0.88, GCC 13.3, C++17, SM90 compilation	Build the complete BLOOM_FILTER_TEST target; run [sizing][host]	Build passed; 3 cases / 21 assertions passed
Repository formatting and documentation	clang-format 20.1.4, the existing Doxygen check with 1.9.1, and git diff --check	Passed
NVIDIA H200, driver 595.58.03	Complete target; Compute Sanitizer 2025.3.1 memcheck on [sizing][gpu]	52 cases / 155 assertions passed; focused 2 cases / 4 assertions passed with 0 errors and 0 bytes leaked

The compiler checks used an x86_64 Ubuntu 24.04 environment. They cover the two toolchains above, not the complete repository CI matrix. The host tests were rerun before submission with source hashes matching this commit.

The host cases exercise rounding down, policy capping, budgets smaller than one block, zero/misaligned/oversized construction, a narrow extent's capacity limit, and static extent mismatch. The GPU cases compare byte and block construction for dynamic extents and extent<uint8_t, 2>.

Static extent boundary experiment

A separate allocator probe stopped at the allocation boundary without allocating device memory. In the pre-fix candidate, extent<uint8_t, 257> truncated to one block and incorrectly reached the allocator for a one-block request when warnings were not treated as errors. The probe failed as expected, exposing the missing validation.

With the final guard, that instantiation fails to compile with Static extent must be representable by its size type. Valid static extents of 2 and 255 blocks still reach the allocator, while a one-block request for a two-block extent throws cuco::logic_error before allocation. All three valid/mismatch probe checks passed. These diagnostic probes were run separately from the repository test suite.

GPU validation status

The current revision passed on one NVIDIA H200 from an 8×H200 node (driver 595.58.03). The job verified the test binary and all four changed source files by SHA-256 before execution:

• Complete BLOOM_FILTER_TEST: 52 cases / 155 assertions passed.
• Compute Sanitizer 2025.3.1 memcheck on [sizing][gpu]: 2 cases / 4 assertions passed, with 0 errors and 0 bytes leaked.

The completed host checks can be repeated with ./build/tests/BLOOM_FILTER_TEST '[sizing][host]'. Full repository CI remains to be run.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[sleeepyjack]

Hi @yuweih205,

Thanks for contributing to cuco!
@PointKernel and I discussed the topic offline and settled on a simpler approach:
Instead of allowing the user to go both ways aka provide a lower-bound or upper-bound size in bytes, we only really need the upper-bound case which can be handled through the new ctor overload.

In short, 'bloom_filter(bloom_filter_bytes size)' allocates a filter that is always smaller or equal to 'size'; never exceeding it.
This means we can also remove the 'aligned_size' helper and the extent factory, making the API much simpler.

One small nit: I would suggest to rename the strong type for the filter size to `bloom_filter_bytes' as it is a bit shorter.

Do you agree with these changes? Happy to discuss and thanks again for your work on this!