DOCSEARCHbyAlgolia
Submit Docs

cuCollections (cuco)

repository·dev·Indexed 20 days ago

https://github.com/nvidia/cucollections

An open-source, header-only, GPU-accelerated library providing concurrent data structures for CUDA development. Designed as an STL-like alternative for GPU workloads, it includes implementations such as static_set, static_map, static_multimap, static_multiset, dynamic_map, hyperloglog, bloom_filter, and an experimental roaring_bitmap. It requires NVCC 12.0+, C++17, and Volta architecture or newer, and depends on the CUDA C++ Core Libraries (CCCL).

Tokens
2.9K
Snippets
14
Records
22
Agent score
21%

What's inside cuCollections

  1. What is cuCollections?

    dev
    cuCollections (cuco) is an open-source, header-only library of GPU-accelerated, concurrent data structures. It provides STL-like concurrent data structures optimized for efficient use with GPUs, similar to how Thrust and CUB provide GPU-accelerated algorithms and primitives. Note that it is not a direct, drop-in replacement for standard STL structures like std::unordered_map, but rather functionally similar structures optimized for GPU workloads.

  2. Use the `static_set` data structure

    dev

    The cuco::static_set is a GPU-accelerated, fixed-size container designed to store unique elements in no particular order. It is one of the flagship concurrent data structures in cuCollections. For detailed API specifications and usage, refer to the Doxygen documentation provided in static_set.cuh.

    // Note: Detailed API usage is documented in static_set.cuh
// cuco::static_set is a fixed-size container for unique elements.

  5. Set up pre-commit hooks for code formatting

    dev

    To automatically run clang-format during git commits, install pre-commit via conda or pip and then initialize it within the repository root.

    # Using conda
conda install -c conda-forge pre_commit

# Or using pip
pip install pre-commit

# Initialize hooks
pre-commit install

  6. Add cuCollections to a CMake Project

    dev

    Since cuCollections is header-only, you can incorporate it manually by downloading the headers. However, it is designed to be easily included in CMake projects via a cuco target that handles include directories, dependencies, and compile flags.

    It is recommended to use the CMake Package Manager (CPM) to fetch the library.

    cmake_minimum_required(VERSION 3.23.1 FATAL_ERROR)

include(path/to/CPM.cmake)

CPMAddPackage(
  NAME cuco
  GITHUB_REPOSITORY NVIDIA/cuCollections
  GIT_TAG dev
  OPTIONS
     "BUILD_TESTS OFF"
     "BUILD_BENCHMARKS OFF"
     "BUILD_EXAMPLES OFF"
)

target_link_libraries(my_library cuco)

  7. Requirements for using cuCollections

    dev

    To use cuCollections, your environment must meet the following requirements:

    • NVCC: version 12.0 or newer.
    • C++ Standard: C++17.
    • GPU Architecture: Volta or newer.
      • Note: Pascal is partially supported, but data structures requiring blocking algorithms are not supported. Refer to libcu++ documentation for architecture details.

  8. Build tests, benchmarks, and examples

    dev

    While cuCollections is header-only and requires no build to use in your own project, you can build its internal tests, benchmarks, and examples using CMake.

    cd $CUCO_ROOT
mkdir -p build
cd build
cmake .. # configure
make # build
ctest --test-dir tests # run tests

  9. Build cuCollections using the build script

    dev

    You can use the provided build script ci/build.sh to configure and build the project. Running the script without arguments triggers a full build located in build/local.

    cd $CUCO_ROOT
ci/build.sh # configure and build
ctest --test-dir build/local/tests # run tests

  10. Use pre-allocated memory in static maps

    dev

    You can optimize performance by providing your own pre-allocated memory for static maps instead of relying on default allocation. This is useful for managing memory pools or ensuring specific memory alignment in high-performance CUDA applications.

    Refer to the preallocated_memory_example.cu for a concrete implementation.

    https://github.com/NVIDIA/cuCollections/blob/dev/examples/static_map/preallocated_memory_example.cu

  11. Perform heterogeneous lookups in static maps

    dev

    cuCollections supports heterogeneous lookups, allowing you to perform searches where the key types or value types may differ or involve complex structures. This capability is demonstrated in the heterogeneous_lookup_example.cu example.

    Refer to the heterogeneous_lookup_example.cu for a concrete implementation.

    https://github.com/NVIDIA/cuCollections/blob/dev/examples/static_map/heterogeneous_lookup_example.cu

  12. Explore cuCollections examples

    dev

    The repository contains several practical examples demonstrating different usage patterns for cuCollections. These include:

    • Host-bulk APIs: Demonstrates how to use bulk APIs from the host side.
    • Device-ref APIs: Shows how to perform individual operations using device-reference APIs.
    • One single storage for multiple sets: Demonstrates how to manage multiple sets within a single storage allocation.
    • Using shared memory as storage: Shows how to utilize shared memory as a storage backend.

    You can view the source code for these examples in the examples/ directory or interact with live, compilable versions via the provided Godbolt links.

    <!-- Examples are available in the repository under the examples/ directory -->
- Host-bulk APIs: examples/static_set/host_bulk_example.cu
- Device-ref APIs: examples/static_set/device_ref_example.cu
- One single storage for multiple sets: examples/static_set/device_subsets_example.cu
- Using shared memory as storage: examples/static_set/shared_memory_example.cu