NVIDIA/cuCollections

NVIDIA/cuCollections

Language: Cuda

License: Apache-2.0

Stars: 648

Forks: 113

Open issues: 68

Created: 2019-12-09T21:45:02Z

Pushed: 2026-06-10T18:59:33Z

Default branch: dev

Fork: no

Archived: no

README:

cuCollections

cuCollections (cuco) is an open-source, header-only library of GPU-accelerated, concurrent data structures.

Similar to how Thrust and CUB provide STL-like, GPU-accelerated algorithms and primitives, cuCollections provides STL-like concurrent data structures. cuCollections is not a one-to-one, drop-in replacement for STL data structures like std::unordered_map. Instead, it provides functionally similar data structures optimized for efficient use with GPUs.

Development Status

cuCollections is still under active development. Users should expect breaking changes and refactoring to be common.

Major Updates

__02/19/2026__ Removed legacy static_map implementation from cuco::legacy namespace

__02/03/2026__ Modernized dynamic_map: promoted cuco::experimental::dynamic_map to cuco::dynamic_map and removed the legacy implementation

__01/30/2026__ Removed legacy static_multimap implementation and promoted cuco::experimental::static_multimap to cuco::static_multimap

__10/08/2025__ Changed cuda_allocator to stream-ordered, requiring cuda::stream_ref parameter in allocate/deallocate.

__06/04/2025__ Removed CUDA 11 support

__11/01/2024__ Refined the term window as bucket

Getting cuCollections

cuCollections is header-only and can be incorporated manually into your project by downloading the headers and placing them into your source tree.

Adding cuCollections to a CMake Project

cuCollections is designed to make it easy to include within another CMake project. The CMakeLists.txt exports a cuco target that can be linked[1](#link-footnote) into a target to set up include directories, dependencies, and compile flags necessary to use cuCollections in your project.

We recommend using CMake Package Manager (CPM) to fetch cuCollections into your project. With CPM, getting cuCollections is easy:

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)

This will take care of downloading cuCollections from GitHub and making the headers available in a location that can be found by CMake. Linking against the cuco target will provide everything needed for cuco to be used by the my_library target.

1: cuCollections is header-only and therefore there is no binary component to "link" against. The linking terminology comes from CMake's target_link_libraries which is still used even for header-only library targets.

Requirements

• NVCC 12.0 or newer
• C++17
• GPU Architecture: Volta or newer
• Pascal is partially supported. Any data structures that require blocking algorithms are not supported. See libcu++ documentation for more details.

Dependencies

cuCollections depends on the following libraries:

• CUDA C++ Core Libraries (CCCL)

No action is required from the user to satisfy these dependencies. cuCollections's CMake script is configured to first search the system for these libraries, and if they are not found, to automatically fetch them from GitHub.

Building cuCollections

Since cuCollections is header-only, there is nothing to build to use it.

To build the tests, benchmarks, and examples:

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

Binaries will be built into:

• build/tests/
• build/benchmarks/
• build/examples/

Build Script:

Alternatively, you can use the build script located at ci/build.sh. Calling this script with no arguments will trigger a full build which will be located at build/local.

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

For a comprehensive list of all available options along with descriptions and examples, you can use the option ci/build.sh -h.

Code Formatting

By default, cuCollections uses `pre-commit.ci` along with `mirrors-clang-format` to automatically format the C++/CUDA files in a pull request. Users should enable the Allow edits by maintainers option to get auto-formatting to work.

Pre-commit hook

Optionally, you may wish to setup a `pre-commit` hook to automatically run clang-format when you make a git commit. This can be done by installing pre-commit via conda or pip:

conda install -c conda-forge pre_commit

pip install pre-commit

and then running:

pre-commit install

from the root of the cuCollections repository. Now code formatting will be run each time you commit changes.

You may also wish to manually format the code:

pre-commit run clang-format --all-files

Caveats

mirrors-clang-format guarantees the correct version of clang-format and avoids version mismatches. Users should _NOT_ use clang-format directly on the command line to format the code.

Documentation

`Doxygen` is used to generate HTML pages from the C++/CUDA comments in the source code.

The example

The following example covers most of the Doxygen block comment and tag styles for documenting C++/CUDA code in cuCollections.

/**
* @file source_file.cpp
* @brief Description of source file contents
*
* Longer description of the source file contents.
*/

/**
* @brief Short, one sentence description of the class.
*
* Longer, more detailed description of the class.
*
* A detailed description must start after a blank line.
*
* @tparam T Short description of each template parameter
* @tparam U Short description of each template parameter
*/
template
class example_class {

void get_my_int(); ///< Simple members can be documented like this
void set_my_int( int value ); ///< Try to use descriptive member names

/**
* @brief Short, one sentence…