feat(cccl): integrate missing CCCL directories — python/, ci/, .agent/, docs/, test/
Sparse-checkout from NVIDIA/cccl main branch to complete cccl_upstream: Added: - python/cuda_cccl/ (226 files) — Python bindings for device-level algorithms Critical for muh toolchain: cuda.compute.reduce_into, scan, radix_sort, etc. Includes 204 .py files with full test coverage for all 27 algorithms - ci/ (163 files) — Build/test infrastructure build_cub.sh, test_cub.sh, build_and_test_targets.sh, matrix.yaml Directly maps to our [INFRA-CI] and [INFRA-BUILD] items - .agent/skills/ (7 files) — NVIDIA's own agent skills for CCCL cccl-style/SKILL.md, cccl-test/SKILL.md, sass-diff/SKILL.md - docs/ (491 files) — Official CCCL documentation CI references, CMake guides, Python compute docs, libcudacxx PTX docs - test/ (12 files) — Top-level integration tests (cuda_smoke, stdpar) - Root configs: .clang-format, .clang-tidy, CONTRIBUTING.md, pyproject.toml - CLAUDE.md symlink → AGENTS.md (NVIDIA's standard) cccl_upstream now mirrors full NVIDIA/cccl structure: Before: 42M (cub + thrust + libcudacxx + cudax + c + examples + benchmarks) After: 53M (+python +ci +docs +.agent +test +configs) This completes the CCCL base needed for: - [muh-bench] items: ci/util/build_and_test_targets.sh for targeted builds - [CCCL-verify] items: python/cuda_cccl/tests/ as reference implementations - [CCCL-test] items: ci/test_cub.sh, ci/test_thrust.sh - Agent workflow: .agent/skills/ for consistent style and test patterns
This commit is contained in:
muh-bot
@@ -0,0 +1,98 @@
|
||||
.. _libcudacxx-standard-api-algorithms:
|
||||
|
||||
Algorithms Library
|
||||
===================
|
||||
|
||||
.. list-table::
|
||||
:widths: 25 45 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Header
|
||||
- Content
|
||||
- Availability
|
||||
* - `\<cuda/std/algorithm\> <https://en.cppreference.com/w/cpp/header/algorithm>`_
|
||||
- Fundamental library algorithms
|
||||
- CCCL 3.2.0 / CUDA 13.2
|
||||
* - `\<cuda/std/execution\> <https://en.cppreference.com/w/cpp/header/execution>`_
|
||||
- Standard parallel algorithms
|
||||
- CCCL 3.4.0 / CUDA 13.4
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- All supported algorithms are available from C++17 onwards.
|
||||
- All supported algorithms are constexpr, except the allocating ones.
|
||||
- Because `<cuda/std/algorithm>` is a huge header with a considerable compile-time cost, we provide each algorithm
|
||||
through a minimal subheader named e.g `<cuda/std/algorithm.find.h>`
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
- Algorithms in namespace `ranges` are not yet supported.
|
||||
- Some sorting algorithms are not yet supported:
|
||||
|
||||
* ``inplace_merge``
|
||||
* ``nth_element``
|
||||
* ``sort``
|
||||
* ``stable_partition``
|
||||
* ``stable_sort``
|
||||
|
||||
Parallel standard algorithms
|
||||
----------------------------
|
||||
|
||||
CCCL provides an implementation for the standard `parallel algorithms library <http://www.eel.is/c++draft/algorithms.parallel>`_
|
||||
|
||||
Currently the CUDA backend is the only supported backend. It can be selected by passing the `cuda::execution::gpu`
|
||||
execution policy to one of the supported algorithms. The CUDA backend requires the passed in sequences to reside in
|
||||
device accessible memory and the iterators into those sequences to be at least random access iterators. The CUDA backend
|
||||
is enabled if the program is compiled with a CUDA compiler in CUDA mode.
|
||||
|
||||
The use of any other execution policy is currently not supported and results in a compile time error.
|
||||
|
||||
The following algorithms are supported:
|
||||
|
||||
* ``adjacent_find``
|
||||
* ``all_of``
|
||||
* ``any_of``
|
||||
* ``copy``
|
||||
* ``copy_if``
|
||||
* ``copy_n``
|
||||
* ``count``
|
||||
* ``count_if``
|
||||
* ``equal``
|
||||
* ``fill``
|
||||
* ``fill_n``
|
||||
* ``find``
|
||||
* ``find_if``
|
||||
* ``find_if_not``
|
||||
* ``for_each``
|
||||
* ``for_each_n``
|
||||
* ``generate``
|
||||
* ``generate_n``
|
||||
* ``is_partitioned``
|
||||
* ``is_sorted``
|
||||
* ``is_sorted_until``
|
||||
* ``merge``
|
||||
* ``mismatch``
|
||||
* ``none_of``
|
||||
* ``remove``
|
||||
* ``remove_copy``
|
||||
* ``remove_copy_if``
|
||||
* ``remove_if``
|
||||
* ``replace``
|
||||
* ``replace_copy``
|
||||
* ``replace_copy_if``
|
||||
* ``replace_if``
|
||||
* ``reverse``
|
||||
* ``reverse_copy``
|
||||
* ``rotate``
|
||||
* ``rotate_copy``
|
||||
* ``shift_left``
|
||||
* ``shift_right``
|
||||
* ``stable_partition``
|
||||
* ``swap_ranges``
|
||||
* ``transform``
|
||||
* ``unique``
|
||||
* ``unique_copy``
|
||||
|
||||
The current implementation status is tracked in this `GitHub Issue <https://github.com/NVIDIA/cccl/issues/5592>`_
|
||||
95
cccl_upstream/docs/libcudacxx/standard_api/c_library.rst
Normal file
95
cccl_upstream/docs/libcudacxx/standard_api/c_library.rst
Normal file
@@ -0,0 +1,95 @@
|
||||
.. _libcudacxx-standard-api-c-compat:
|
||||
|
||||
C Library
|
||||
=========
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
|
||||
c_library/cstring
|
||||
|
||||
|
||||
Any Standard C++ header not listed below is omitted.
|
||||
|
||||
.. list-table::
|
||||
:widths: 25 45 30 30 20
|
||||
:header-rows: 1
|
||||
|
||||
* - **Header**
|
||||
- **Content**
|
||||
- **CCCL Availability**
|
||||
- **CUDA Toolkit Availability**
|
||||
- **C++ Reference**
|
||||
|
||||
* - ``<cuda/std/cassert>``
|
||||
- Lightweight assumption testing
|
||||
- CCCL 2.0.0
|
||||
- CUDA 10.2
|
||||
- `\<cassert\> <https://en.cppreference.com/w/cpp/header/cassert>`_
|
||||
|
||||
* - ``<cuda/std/ccomplex>``
|
||||
- C complex number arithmetic
|
||||
- CCCL 2.0.0
|
||||
- CUDA 11.4
|
||||
- `\<ccomplex\> <https://en.cppreference.com/w/cpp/header/ccomplex>`_
|
||||
|
||||
* - ``<cuda/std/cfloat>``
|
||||
- Type support library
|
||||
- CCCL 2.2.0
|
||||
- CUDA 12.3
|
||||
- `\<cfloat\> <https://en.cppreference.com/w/cpp/header/cfloat>`_
|
||||
|
||||
* - ``<cuda/std/cfloat>``
|
||||
- Limits of floating point types
|
||||
- CCCL 2.0.0
|
||||
- CUDA 10.2
|
||||
- `\<cfloat\> <https://en.cppreference.com/w/cpp/header/cfloat>`_
|
||||
|
||||
* - ``<cuda/std/climits>``
|
||||
- Limits of integral types
|
||||
- CCCL 2.0.0
|
||||
- CUDA 10.2
|
||||
- `\<climits\> <https://en.cppreference.com/w/cpp/header/climits>`_
|
||||
|
||||
* - ``<cuda/std/cmath>``
|
||||
- Common math functions
|
||||
- CCCL 2.2.0
|
||||
- CUDA 12.3
|
||||
- `\<cmath\> <https://en.cppreference.com/w/cpp/header/cmath>`_
|
||||
|
||||
* - ``<cuda/std/cstddef>``
|
||||
- Fundamental types
|
||||
- CCCL 2.0.0
|
||||
- CUDA 10.2
|
||||
- `\<cstddef\> <https://en.cppreference.com/w/cpp/header/cstddef>`_
|
||||
|
||||
* - ``<cuda/std/cstdint>``
|
||||
- Fundamental integer types
|
||||
- CCCL 2.2.0
|
||||
- CUDA 12.3
|
||||
- `\<cstdint\> <https://en.cppreference.com/w/cpp/header/cstdint>`_
|
||||
|
||||
* - ``<cuda/std/cstdint>``
|
||||
- Fixed-width integer types
|
||||
- CCCL 2.0.0
|
||||
- CUDA 10.2
|
||||
- `\<cstdint\> <https://en.cppreference.com/w/cpp/header/cstdint>`_
|
||||
|
||||
* - ``<cuda/std/cstdlib>``
|
||||
- Common utilities
|
||||
- CCCL 2.2.0
|
||||
- CUDA 12.3
|
||||
- `\<cstdlib\> <https://en.cppreference.com/w/cpp/header/cstdlib>`_
|
||||
|
||||
* - :ref:`\<cuda/std/cstring\> <libcudacxx-standard-api-cstring>`
|
||||
- Provides array manipulation functions such as ``memcpy``, ``memset`` and ``memcmp``
|
||||
- CCCL 3.0.0
|
||||
- CUDA 13.0
|
||||
- `\<cstring\> <https://en.cppreference.com/w/cpp/header/cstring>`_
|
||||
|
||||
* - ``<cuda/std/ctime>``
|
||||
- Provides ``clock``, ``difftime``, ``time`` and ``timespec_get`` functions
|
||||
- CCCL 3.1.0
|
||||
- CUDA 13.1
|
||||
- `\<ctime\> <https://en.cppreference.com/w/cpp/header/ctime>`_
|
||||
@@ -0,0 +1,47 @@
|
||||
.. _libcudacxx-standard-api-cstring:
|
||||
|
||||
``<cuda/std/cstring>``
|
||||
======================
|
||||
|
||||
``cuda::std::memset``
|
||||
---------------------
|
||||
|
||||
.. code:: cuda
|
||||
|
||||
__host__ __device__
|
||||
inline void* memset(void* dest, int ch, size_t count) noexcept;
|
||||
|
||||
See `std::memset <https://en.cppreference.com/w/cpp/string/byte/memset.html>`_ for the full documentation.
|
||||
|
||||
**Preconditions**
|
||||
|
||||
The following preconditions are only enabled with CCCL 3.2 or later:
|
||||
|
||||
- ``dest`` is a valid pointer.
|
||||
- ``dest + count`` is a valid pointer.
|
||||
|
||||
A valid pointer is one that is not NULL and within the correct range if it belongs to the shared memory address space.
|
||||
|
||||
----
|
||||
|
||||
``cuda::std::memcpy``
|
||||
---------------------
|
||||
|
||||
.. code:: cuda
|
||||
|
||||
__host__ __device__
|
||||
inline void* memcpy(void* dest, const void* src, size_t count) noexcept;
|
||||
|
||||
See `std::memcpy <https://en.cppreference.com/w/cpp/string/byte/memcpy.html>`_ for the full documentation.
|
||||
|
||||
**Preconditions**
|
||||
|
||||
The following preconditions are only enabled with CCCL 3.2 or later:
|
||||
|
||||
- ``src`` is a valid pointer.
|
||||
- ``src + count`` is a valid pointer.
|
||||
- ``dest`` is a valid pointer.
|
||||
- ``dest + count`` is a valid pointer.
|
||||
- ``src`` and ``dest`` don't overlap.
|
||||
|
||||
A valid pointer is one that is not NULL and within the correct range if it belongs to the shared memory address space.
|
||||
@@ -0,0 +1,49 @@
|
||||
.. _libcudacxx-standard-api-concepts:
|
||||
|
||||
Concepts Library
|
||||
=======================
|
||||
|
||||
.. list-table::
|
||||
:widths: 25 45 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Header
|
||||
- Content
|
||||
- Availability
|
||||
* - `\<cuda/std/concepts\> <https://en.cppreference.com/w/cpp/header/concepts>`_
|
||||
- Fundamental library concepts
|
||||
- CCCL 2.1.0 / CUDA 12.2
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- All library features are available from C++14 onwards. The concepts
|
||||
can be used like type traits prior to C++20.
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
template<cuda::std::integral Integer>
|
||||
void do_something_with_integers_in_cpp20(Integer&& i) {...}
|
||||
|
||||
template<class Integer, cuda::std::enable_if_t<cuda::std::integral<Integer>, int> = 0>
|
||||
void do_something_with_integers_in_cpp17(Integer&& i) {...}
|
||||
|
||||
template<class Integer, cuda::std::enable_if_t<cuda::std::integral<Integer>, int> = 0>
|
||||
void do_something_with_integers_in_cpp14(Integer&& i) {...}
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
- Subsumption does not work prior to C++20
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
template<class Integer, cuda::std::enable_if_t<subsuming_concept<Integer> && true, int> = 0>
|
||||
void would_be_preferred_overload_in_cpp20(Integer&& i) {...}
|
||||
|
||||
template<class Integer, cuda::std::enable_if_t<cuda::std::integral<Integer>, int> = 0>
|
||||
void is_always_ambiguous_in_cpp17(Integer&& i) {...}
|
||||
|
||||
- Subsumption is only partially implemented in the compiler until nvcc 12.4
|
||||
|
||||
nvcc has issues detecting subsumption of concepts that are composed of multiple concepts
|
||||
@@ -0,0 +1,49 @@
|
||||
.. _libcudacxx-standard-api-container:
|
||||
|
||||
Container Library
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
|
||||
container_library/array
|
||||
container_library/inplace_vector
|
||||
container_library/mdspan
|
||||
container_library/span
|
||||
|
||||
Any Standard C++ header not listed below is omitted.
|
||||
|
||||
.. list-table::
|
||||
:widths: 25 45 30 30 20
|
||||
:header-rows: 1
|
||||
|
||||
* - **Header**
|
||||
- **Content**
|
||||
- **CCCL Availability**
|
||||
- **CUDA Toolkit Availability**
|
||||
- **C++ Reference**
|
||||
|
||||
* - :ref:`\<cuda/std/array\> <libcudacxx-standard-api-container-array>`
|
||||
- Fixed size array
|
||||
- CCCL 2.0.0
|
||||
- CUDA 11.7
|
||||
- `\<array\> <https://en.cppreference.com/w/cpp/header/array>`_
|
||||
|
||||
* - :ref:`\<cuda/std/inplace_vector\> <libcudacxx-standard-api-container-inplace-vector>`
|
||||
- Flexible size container with fixed capacity
|
||||
- CCCL 2.6.0
|
||||
- CUDA 12.8
|
||||
- `\<inplace_vector\> <https://en.cppreference.com/w/cpp/header/inplace_vector>`_
|
||||
|
||||
* - :ref:`\<cuda/std/mdspan\> <libcudacxx-standard-api-container-mdspan>`
|
||||
- Non - owning view into a multidimensional contiguous sequence of objects
|
||||
- CCCL 2.1.0
|
||||
- CUDA 12.2
|
||||
- `\<mdspan\> <https://en.cppreference.com/w/cpp/header/mdspan>`_
|
||||
|
||||
* - :ref:`\<cuda/std/span\> <libcudacxx-standard-api-container-span>`
|
||||
- Non - owning view into a contiguous sequence of objects
|
||||
- CCCL 2.1.0
|
||||
- CUDA 12.2
|
||||
- `\<span\> <https://en.cppreference.com/w/cpp/header/span>`_
|
||||
@@ -0,0 +1,10 @@
|
||||
.. _libcudacxx-standard-api-container-array:
|
||||
|
||||
``<cuda/std/array>``
|
||||
======================
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- All features of ``<array>`` are made available in C++14 onwards
|
||||
- All features of ``<array>`` are made constexpr in C++14 onwards
|
||||
@@ -0,0 +1,14 @@
|
||||
.. _libcudacxx-standard-api-container-inplace-vector:
|
||||
|
||||
``<cuda/std/inplace_vector>``
|
||||
==============================
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- Most features of ``<inplace_vector>`` are made available in C++14 onwards
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
- The range based interface is only available with ranges support in C++17
|
||||
@@ -0,0 +1,22 @@
|
||||
.. _libcudacxx-standard-api-container-mdspan:
|
||||
|
||||
``<cuda/std/mdspan>``
|
||||
======================
|
||||
|
||||
Provided functionalities
|
||||
------------------------
|
||||
|
||||
- All features of ``<mdspan>`` are made available in C++17 onwards
|
||||
- C++26 ``std::dims`` is made available in C++17 onwards
|
||||
- C++26 ``std::aligned_accessor`` is made available in C++17 onwards
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- The C++23 multidimensional ``operator[]`` is replaced with ``operator()`` in previous C++ standards
|
||||
- Detection of out-of-bounds accesses is available in debug mode
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
- On device no exceptions are thrown in case of a bad access.
|
||||
@@ -0,0 +1,16 @@
|
||||
.. _libcudacxx-standard-api-container-span:
|
||||
|
||||
``<cuda/std/span>``
|
||||
======================
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- All features of ``<span>`` are made available in C++14 onwards
|
||||
- All features of ``<span>`` are made constexpr in C++14 onwards
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
- On device no exceptions are thrown in case of a bad access.
|
||||
- The range based constructors are emulated but not 100% equivalent.
|
||||
@@ -0,0 +1,25 @@
|
||||
.. _libcudacxx-standard-api-execution:
|
||||
|
||||
Execution Library
|
||||
=======================
|
||||
|
||||
.. list-table::
|
||||
:widths: 25 45 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Header
|
||||
- Content
|
||||
- Availability
|
||||
* - `\<cuda/std/execution\> <https://en.cppreference.com/w/cpp/header/execution>`_
|
||||
- Fundamental library concepts
|
||||
- CCCL 3.0.0 / CUDA 13
|
||||
|
||||
|
||||
Omissions
|
||||
---------
|
||||
|
||||
- At present, only the following features are implemented:
|
||||
|
||||
- `cuda::std::execution::prop <https://eel.is/c++draft/exec.prop>`_
|
||||
- `cuda::std::execution::env <https://eel.is/c++draft/exec.env>`_
|
||||
- `cuda::std::execution::get_env <https://eel.is/c++draft/exec.get.env>`_
|
||||
@@ -0,0 +1,69 @@
|
||||
.. _libcudacxx-standard-api-numerics:
|
||||
|
||||
Numerics Library
|
||||
================
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
|
||||
numerics_library/bit
|
||||
numerics_library/complex
|
||||
numerics_library/linalg
|
||||
numerics_library/numbers
|
||||
numerics_library/numeric
|
||||
numerics_library/random
|
||||
|
||||
Any Standard C++ header not listed below is omitted.
|
||||
|
||||
.. list-table::
|
||||
:widths: 25 45 30 30 20
|
||||
:header-rows: 1
|
||||
|
||||
* - **Header**
|
||||
- **Content**
|
||||
- **CCCL Availability**
|
||||
- **CUDA Toolkit Availability**
|
||||
- **C++ Reference**
|
||||
|
||||
* - ``<cuda/std/ratio>``
|
||||
- Compile-time rational arithmetic
|
||||
- CCCL 2.0.0
|
||||
- CUDA 11.0
|
||||
- `\<ratio\> <https://en.cppreference.com/w/cpp/header/ratio>`_
|
||||
|
||||
* - :ref:`\<cuda/std/bit\> <libcudacxx-standard-api-numerics-bit>`
|
||||
- Access, manipulate, and process individual bits and bit sequences.
|
||||
- CCCL 2.0.0
|
||||
- CUDA 11.7
|
||||
- `\<bit\> <https://en.cppreference.com/w/cpp/header/bit>`_
|
||||
|
||||
* - :ref:`\<cuda/std/complex\> <libcudacxx-standard-api-numerics-complex>`
|
||||
- Complex number type
|
||||
- CCCL 2.0.0
|
||||
- CUDA 11.4
|
||||
- `\<complex\> <https://en.cppreference.com/w/cpp/header/complex>`_
|
||||
|
||||
* - :ref:`\<cuda/std/linalg\> <libcudacxx-standard-api-numerics-linalg>`
|
||||
- Linear algebra layouts and accessors
|
||||
- CCCL 3.0.0
|
||||
- CUDA 13.0
|
||||
- `\<linalg\> <https://en.cppreference.com/w/cpp/header/linalg>`_
|
||||
|
||||
* - :ref:`\<cuda/std/numbers\> <libcudacxx-standard-api-numerics-numbers>`
|
||||
- Numeric constants
|
||||
- CCCL 3.0.0
|
||||
- CUDA 13.0
|
||||
- `\<numbers\> <https://en.cppreference.com/w/cpp/header/numbers>`_
|
||||
|
||||
* - :ref:`\<cuda/std/numeric\> <libcudacxx-standard-api-numerics-numeric>`
|
||||
- Numeric algorithms
|
||||
- CCCL 2.5.0
|
||||
- CUDA 12.6
|
||||
- `\<numeric\> <https://en.cppreference.com/w/cpp/header/numeric>`_
|
||||
|
||||
* - :ref:`\<cuda/std/random\> <libcudacxx-standard-api-numerics-random>`
|
||||
- Random number generation
|
||||
- CCCL 3.3.0
|
||||
- CUDA 13.3
|
||||
- `\<random\> <https://en.cppreference.com/w/cpp/header/random>`_
|
||||
@@ -0,0 +1,47 @@
|
||||
.. _libcudacxx-standard-api-numerics-bit:
|
||||
|
||||
``<cuda/std/bit>``
|
||||
==================
|
||||
|
||||
``cuda::std::bit_cast``
|
||||
-----------------------
|
||||
|
||||
``cuda::std::bit_cast`` extended the standard ``std::bit_cast`` to also recognize CUDA extended floating-point scalar and vector types as trivially copyable.
|
||||
|
||||
**Limitations**
|
||||
|
||||
- The function can be used in ``constexpr`` contexts only when the source and destination types are trivially copyable.
|
||||
- The function cannot be used in ``constexpr`` contexts with MSVC <= 19.25 and GCC <= 10.
|
||||
|
||||
CUDA Performance Considerations
|
||||
-------------------------------
|
||||
|
||||
Given an unsigned integer with ``N`` bits and ``N <= 32``, the ``<bit>`` functions translate into the following SASS instructions. For some functions, the results is decorated with a compile-time assumption to restrict its range and allowing further optimizations.
|
||||
|
||||
- ``bit_width()`` translates into a single ``FLO`` SASS instruction. The result is assumed to be in the range ``[0, N]``.
|
||||
- ``bit_ceil()`` translates into ``ADD, FLO, SHL, IMINMAX`` SASS instructions. The result is assumed to be greater than or equal to the input.
|
||||
- ``bit_floor()`` translates into ``FLO, SHL`` SASS instructions. The result is assumed to be less than or equal to the input.
|
||||
- ``byteswap()`` translates into a single ``PRMT`` SASS instruction.
|
||||
- ``popcount()`` translates into a single ``POPC`` SASS instruction. The result is assumed to be in the range ``[0, N]``.
|
||||
- ``has_single_bit()`` translates into ``POPC + ISETP`` SASS instructions.
|
||||
- ``rotl()/rotr()`` translate into a single ``SHF`` (funned shift) SASS instruction.
|
||||
- ``countl_zero()`` translates into ``FLO, IMINMAX`` SASS instructions. The result is assumed to be in the range ``[0, N]``.
|
||||
- ``countl_one()`` translates into ``LOP3, FLO, IMINMAX`` SASS instructions. The result is assumed to be in the range ``[0, N]``.
|
||||
- ``countr_zero()`` translates into ``BREV, FLO, IMINMAX`` SASS instructions. The result is assumed to be in the range ``[0, N]``.
|
||||
- ``countr_one()`` translates into ``LOP3, BREV, FLO, IMINMAX`` SASS instructions. The result is assumed to be in the range ``[0, N]``.
|
||||
|
||||
Additional Notes
|
||||
----------------
|
||||
|
||||
- All functions are marked ``[[nodiscard]]`` and ``noexcept``
|
||||
- All functions support 128-bit integer types
|
||||
- ``bit_ceil()`` checks for overflow in debug mode
|
||||
- ``rotl()/rotr()`` checks for invalid count value (``INT_MIN``) in debug mode
|
||||
|
||||
.. note::
|
||||
|
||||
When the input values are run-time values that the compiler can resolve at compile-time, e.g. an index of a loop with a fixed number of iterations, using the functions could not be optimal.
|
||||
|
||||
.. note::
|
||||
|
||||
GCC <= 8 uses a slow path with more instructions even in CUDA
|
||||
@@ -0,0 +1,41 @@
|
||||
.. _libcudacxx-standard-api-numerics-complex:
|
||||
|
||||
``<cuda/std/complex>``
|
||||
======================
|
||||
|
||||
Omissions
|
||||
---------
|
||||
|
||||
When using libcu++ with NVCC, ``complex`` does not support ``long double`` or ``complex`` literals (``_i``, ``_if``, and ``_il``).
|
||||
NVCC warns on any usage of ``long double`` in device code, because ``long double`` will be demoted to ``double`` in device code.
|
||||
This warning can be suppressed silenced with ``#pragma``\ s, but only globally, not just when using ``complex``.
|
||||
User-defined floating-point literals must be specified in terms of ``long double``, so they lead to warnings
|
||||
that are unable to be suppressed.
|
||||
|
||||
Extensions
|
||||
--------------
|
||||
|
||||
- Handling of infinities
|
||||
|
||||
Our implementation by default recovers infinite values during multiplication and division. This adds a significant runtime overhead,
|
||||
so we allow disabling that canonicalization if it is not desired.
|
||||
|
||||
Definition of ``LIBCUDACXX_ENABLE_SIMPLIFIED_COMPLEX_OPERATIONS`` disables canonicalization for both multiplication *and* division.
|
||||
|
||||
Definition of ``LIBCUDACXX_ENABLE_SIMPLIFIED_COMPLEX_MULTIPLICATION`` or ``LIBCUDACXX_ENABLE_SIMPLIFIED_COMPLEX_DIVISION`` disables
|
||||
canonicalization for multiplication or division individually.
|
||||
|
||||
- Support for half and bfloat16 (since libcu++ 2.4.0)
|
||||
|
||||
Our implementation includes support for the ``__half`` type from ``<cuda_fp16.h>``, when the CUDA toolkit version is at
|
||||
least 12.2, and when ``CCCL_DISABLE_FP16_SUPPORT`` is **not** defined.
|
||||
|
||||
This is detected automatically when compiling through NVCC. If you are compiling a host-only translation unit directly
|
||||
with the host compiler, you must define the macro ``LIBCUDACXX_ENABLE_HOST_NVFP16`` prior to including any libcu++ headers,
|
||||
and you must ensure that the ``<cuda_fp16.h>`` header that's found by the compiler comes from a CUDA toolkit version
|
||||
12.2 or higher.
|
||||
|
||||
Our implementation includes support for the ``__nv_bfloat16`` type from ``<cuda_bf16.h>``, when the conditions for the
|
||||
support of ``__half`` are fulfilled, and when ``CCCL_DISABLE_BF16_SUPPORT`` and ``CCCL_DISABLE_FP16_SUPPORT`` are **not** defined.
|
||||
|
||||
- C++20 constexpr ``<complex>`` is available in C++14.
|
||||
@@ -0,0 +1,31 @@
|
||||
.. _libcudacxx-standard-api-numerics-linalg:
|
||||
|
||||
``<cuda/std/linalg>``
|
||||
============================================
|
||||
|
||||
Provided functionalities
|
||||
------------------------
|
||||
|
||||
- ``scaled()`` `std::linalg::scaled <https://en.cppreference.com/w/cpp/numeric/linalg/scaled>`_
|
||||
- ``scaled_accessor`` `std::linalg::scaled_accessor <https://en.cppreference.com/w/cpp/numeric/linalg/scaled_accessor>`_
|
||||
- ``conjugated()`` `std::linalg::conjugated <https://en.cppreference.com/w/cpp/numeric/linalg/conjugated>`_
|
||||
- ``conjugated_accessor`` `std::linalg::conjugated_accessor <https://en.cppreference.com/w/cpp/numeric/linalg/conjugated_accessor>`_
|
||||
- ``transposed()`` `std::linalg::transposed <https://en.cppreference.com/w/cpp/numeric/linalg/transposed>`_
|
||||
- ``layout_transpose`` `std::linalg::layout_transpose <https://en.cppreference.com/w/cpp/numeric/linalg/layout_transpose>`_
|
||||
- ``conjugate_transposed()`` `std::linalg::conjugate_transposed <https://en.cppreference.com/w/cpp/numeric/linalg/conjugate_transposed>`_
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- C++26 ``std::linalg`` accessors, transposed layout, and related functions are available in C++17
|
||||
|
||||
Omissions
|
||||
---------
|
||||
|
||||
- Currently we do not expose any BLAS functions and layouts.
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
- On device no exceptions are thrown in case of a bad access.
|
||||
- MSVC is only supported with C++20
|
||||
@@ -0,0 +1,10 @@
|
||||
.. _libcudacxx-standard-api-numerics-numbers:
|
||||
|
||||
``<cuda/std/numbers>``
|
||||
======================
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- All features of ``<numbers>`` are made available in C++14 onwards
|
||||
- Implementation is provided only on Linux systems due to NVCC's lack of template ``const __device__`` variables support
|
||||
@@ -0,0 +1,41 @@
|
||||
.. _libcudacxx-standard-api-numerics-numeric:
|
||||
|
||||
``<cuda/std/numeric>``
|
||||
======================
|
||||
|
||||
Omissions
|
||||
---------
|
||||
|
||||
- Currently we do not expose any parallel algorithms.
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- All features of ``<numeric>`` are made available in C++11 onwards
|
||||
- All features of ``<numeric>`` are made constexpr in C++14 onwards
|
||||
- Algorithms that return a value and not an iterator have been marked ``[[nodiscard]]``
|
||||
|
||||
|
||||
Parallel standard algorithms
|
||||
----------------------------
|
||||
|
||||
CCCL provides an implementation for the standard `parallel algorithms library <http://www.eel.is/c++draft/algorithms.parallel>`_
|
||||
|
||||
Currently the CUDA backend is the only supported backend. It can be selected by passing the `cuda::execution::gpu`
|
||||
execution policy to one of the supported algorithms. The CUDA backend requires the passed in sequences to reside in
|
||||
device accessible memory and the iterators into those sequences to be at least random access iterators. The CUDA backend
|
||||
is enabled if the program is compiled with a CUDA compiler in CUDA mode.
|
||||
|
||||
The use of any other execution policy is currently not supported and results in a compile time error.
|
||||
|
||||
The following algorithms are supported:
|
||||
|
||||
* ``adjacent_difference``
|
||||
* ``exclusive_scan``
|
||||
* ``inclusive_scan``
|
||||
* ``transform_exclusive_scan``
|
||||
* ``transform_inclusive_scan``
|
||||
* ``reduce``
|
||||
* ``transform_reduce``
|
||||
|
||||
The current implementation status is tracked in this `GitHub Issue <https://github.com/NVIDIA/cccl/issues/5592>`_
|
||||
@@ -0,0 +1,72 @@
|
||||
.. _libcudacxx-standard-api-numerics-random:
|
||||
|
||||
``<cuda/std/random>``
|
||||
=====================
|
||||
|
||||
Provided functionalities
|
||||
------------------------
|
||||
|
||||
Random number engines:
|
||||
|
||||
- `cuda::std::minstd_rand0 <https://en.cppreference.com/w/cpp/numeric/random/minstd_rand0>`_
|
||||
- `cuda::std::minstd_rand <https://en.cppreference.com/w/cpp/numeric/random/minstd_rand>`_
|
||||
- C++26 `cuda::std::philox4x32 <https://en.cppreference.com/w/cpp/numeric/random/philox_engine.html>`_ - available from C++17 onwards
|
||||
- C++26 `cuda::std::philox4x64 <https://en.cppreference.com/w/cpp/numeric/random/philox_engine.html>`_ - available from C++17 onwards
|
||||
|
||||
.. note::
|
||||
|
||||
``cuda::pcg64`` is provided in the non-standard ``<cuda/random>`` header. See
|
||||
:ref:`cuda::pcg64 <libcudacxx-extended-api-random-pcg64>`.
|
||||
|
||||
Random number distributions:
|
||||
|
||||
- `cuda::std::bernoulli_distribution <https://en.cppreference.com/w/cpp/numeric/random/bernoulli_distribution>`_
|
||||
- `cuda::std::binomial_distribution <https://en.cppreference.com/w/cpp/numeric/random/binomial_distribution>`_
|
||||
- `cuda::std::cauchy_distribution <https://en.cppreference.com/w/cpp/numeric/random/cauchy_distribution>`_
|
||||
- `cuda::std::chi_squared_distribution <https://en.cppreference.com/w/cpp/numeric/random/chi_squared_distribution>`_
|
||||
- `cuda::std::exponential_distribution <https://en.cppreference.com/w/cpp/numeric/random/exponential_distribution>`_
|
||||
- `cuda::std::extreme_value_distribution <https://en.cppreference.com/w/cpp/numeric/random/extreme_value_distribution>`_
|
||||
- `cuda::std::fisher_f_distribution <https://en.cppreference.com/w/cpp/numeric/random/fisher_f_distribution>`_
|
||||
- `cuda::std::gamma_distribution <https://en.cppreference.com/w/cpp/numeric/random/gamma_distribution>`_
|
||||
- `cuda::std::geometric_distribution <https://en.cppreference.com/w/cpp/numeric/random/geometric_distribution>`_
|
||||
- `cuda::std::lognormal_distribution <https://en.cppreference.com/w/cpp/numeric/random/lognormal_distribution>`_
|
||||
- `cuda::std::negative_binomial_distribution <https://en.cppreference.com/w/cpp/numeric/random/negative_binomial_distribution>`_
|
||||
- `cuda::std::normal_distribution <https://en.cppreference.com/w/cpp/numeric/random/normal_distribution>`_
|
||||
- `cuda::std::poisson_distribution <https://en.cppreference.com/w/cpp/numeric/random/poisson_distribution>`_
|
||||
- `cuda::std::student_t_distribution <https://en.cppreference.com/w/cpp/numeric/random/student_t_distribution>`_
|
||||
- `cuda::std::uniform_int_distribution <https://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution>`_
|
||||
- `cuda::std::uniform_real_distribution <https://en.cppreference.com/w/cpp/numeric/random/uniform_real_distribution>`_
|
||||
- `cuda::std::weibull_distribution <https://en.cppreference.com/w/cpp/numeric/random/weibull_distribution>`_
|
||||
|
||||
Utilities:
|
||||
|
||||
- `cuda::std::seed_seq <https://en.cppreference.com/w/cpp/numeric/random/seed_seq>`_
|
||||
- `cuda::std::generate_canonical <https://en.cppreference.com/w/cpp/numeric/random/generate_canonical>`_
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
``cuda::std::seed_seq`` should be used exclusively on host or exclusively on device. Do not share the same
|
||||
``seed_seq`` instance between host and device code.
|
||||
|
||||
|
||||
The following engines or distributions are not implemented as they are not convenient or practical to implement in CUDA device code, either due to dynamic memory allocations or large state sizes.
|
||||
|
||||
Not supported
|
||||
-------------
|
||||
- `std::random_device <https://en.cppreference.com/w/cpp/numeric/random/random_device>`_
|
||||
- `std::mersenne_twister_engine <https://en.cppreference.com/w/cpp/numeric/random/mersenne_twister_engine>`_
|
||||
(`std::mt19937 <https://en.cppreference.com/w/cpp/numeric/random/mersenne_twister_engine>`_,
|
||||
`std::mt19937_64 <https://en.cppreference.com/w/cpp/numeric/random/mersenne_twister_engine>`_)
|
||||
- `std::subtract_with_carry_engine <https://en.cppreference.com/w/cpp/numeric/random/subtract_with_carry_engine.html>`_
|
||||
(`std::ranlux24_base <https://en.cppreference.com/w/cpp/numeric/random/subtract_with_carry_engine.html>`_,
|
||||
`std::ranlux48_base <https://en.cppreference.com/w/cpp/numeric/random/subtract_with_carry_engine.html>`_,
|
||||
`std::ranlux24 <https://en.cppreference.com/w/cpp/numeric/random/subtract_with_carry_engine.html>`_,
|
||||
`std::ranlux48 <https://en.cppreference.com/w/cpp/numeric/random/subtract_with_carry_engine.html>`_)
|
||||
- `std::discard_block_engine <https://en.cppreference.com/w/cpp/numeric/random/discard_block_engine.html>`_
|
||||
- `std::independent_bits_engine <https://en.cppreference.com/w/cpp/numeric/random/independent_bits_engine.html>`_
|
||||
- `std::shuffle_order_engine <https://en.cppreference.com/w/cpp/numeric/random/shuffle_order_engine>`_
|
||||
(`std::knuth_b <https://en.cppreference.com/w/cpp/numeric/random/shuffle_order_engine>`_)
|
||||
- `std::discrete_distribution <https://en.cppreference.com/w/cpp/numeric/random/discrete_distribution.html>`_
|
||||
- `std::piecewise_constant_distribution <https://en.cppreference.com/w/cpp/numeric/random/piecewise_constant_distribution.html>`_
|
||||
- `std::piecewise_linear_distribution <https://en.cppreference.com/w/cpp/numeric/random/piecewise_linear_distribution.html>`_
|
||||
@@ -0,0 +1,46 @@
|
||||
.. _libcudacxx-standard-api-ranges:
|
||||
|
||||
Ranges Library
|
||||
=======================
|
||||
|
||||
See the documentation of the standard headers `\<iterator\> <https://en.cppreference.com/w/cpp/header/iterator>`_ and
|
||||
`\<ranges\> <https://en.cppreference.com/w/cpp/header/ranges>`_
|
||||
|
||||
.. list-table::
|
||||
:widths: 25 45 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Header
|
||||
- Content
|
||||
- Availability
|
||||
* - `\<cuda/std/iterator\> <https://en.cppreference.com/w/cpp/header/iterator>`_
|
||||
- Iterator related concepts and machinery such as ``cuda::std::forward_iterator``
|
||||
- CCCL 2.3.0 / CUDA 12.4
|
||||
* - `\<cuda/std/ranges\> <https://en.cppreference.com/w/cpp/header/ranges>`_
|
||||
- Range related concepts and machinery such as ``cuda::std::ranges::forward_range`` and ``cuda::std::ranges::subrange``
|
||||
- CCCL 2.4.0 / CUDA 12.5
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- All library features are available from C++17 onwards. The concepts can be used like type traits prior to C++20.
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
template<cuda::std::contiguous_range Range>
|
||||
void do_something_with_ranges_in_cpp20(Range&& range) {...}
|
||||
|
||||
template<class Range, cuda::std::enable_if_t<cuda::std::contiguous_range<Range>, int> = 0>
|
||||
void do_something_with_ranges_in_cpp17(Range&& range) {...}
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
- Subsumption does not work prior to C++20
|
||||
- Subsumption is only partially implemented in the compiler until nvcc 12.4
|
||||
|
||||
Omissions
|
||||
---------
|
||||
|
||||
- Range based algorithms have *not* been implemented
|
||||
- Views have *not* been implemented
|
||||
@@ -0,0 +1,26 @@
|
||||
.. _libcudacxx-standard-api-synchronization:
|
||||
|
||||
Synchronization Library
|
||||
=======================
|
||||
|
||||
Any Standard C++ header not listed below is omitted.
|
||||
|
||||
.. list-table::
|
||||
:widths: 25 45 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Header
|
||||
- Content
|
||||
- Availability
|
||||
* - `\<cuda/std/atomic\> <https://en.cppreference.com/w/cpp/header/atomic>`_
|
||||
- Atomic objects and operations. See also :ref:`Extended API <libcudacxx-extended-api-synchronization-atomic>`
|
||||
- libcu++ 1.0.0 / CCCL 2.0.0 / CUDA 10.2
|
||||
* - `\<cuda/std/latch\> <https://en.cppreference.com/w/cpp/header/latch>`_
|
||||
- Single-phase asynchronous thread-coordination mechanism. See also :ref:`Extended API <libcudacxx-extended-api-synchronization-latch>`
|
||||
- libcu++ 1.1.0 / CCCL 2.0.0 / CUDA 11.0
|
||||
* - `\<cuda/std/barrier\> <https://en.cppreference.com/w/cpp/header/barrier>`_
|
||||
- Multi-phase asynchronous thread-coordination mechanism. See also :ref:`Extended API <libcudacxx-extended-api-synchronization-barrier>`
|
||||
- libcu++ 1.1.0 / CCCL 2.0.0 / CUDA 11.0
|
||||
* - `\<cuda/std/semaphore\> <https://en.cppreference.com/w/cpp/header/semaphore>`_
|
||||
- Primitives for constraining concurrent access. See also :ref:`Extended API <libcudacxx-extended-api-synchronization-counting-semaphore>`
|
||||
- libcu++ 1.1.0 / CCCL 2.0.0 / CUDA 11.0
|
||||
119
cccl_upstream/docs/libcudacxx/standard_api/time_library.rst
Normal file
119
cccl_upstream/docs/libcudacxx/standard_api/time_library.rst
Normal file
@@ -0,0 +1,119 @@
|
||||
.. _libcudacxx-standard-api-time:
|
||||
|
||||
Time Library
|
||||
=======================
|
||||
|
||||
See the documentation of the standard header `\<chrono\> <https://en.cppreference.com/w/cpp/header/chrono>`_
|
||||
|
||||
.. list-table::
|
||||
:widths: 25 45 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Header
|
||||
- Content
|
||||
- Availability
|
||||
* - ``<cuda/std/chrono>``
|
||||
- Times, dates, and clocks
|
||||
- libcu++ 1.1.0 / CCCL 2.0.0 / CUDA 12.3
|
||||
|
||||
Implementation-Defined Behavior
|
||||
-------------------------------
|
||||
|
||||
`std::chrono::system_clock <https://en.cppreference.com/w/cpp/chrono/system_clock>`_
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`std::chrono::system_clock <https://en.cppreference.com/w/cpp/chrono/system_clock>`_
|
||||
is a clock that track real-world time. In the C++ Standard, it is
|
||||
unspecified whether or not this clock is monotonically increasing. In
|
||||
our implementation, it is not.
|
||||
|
||||
To implement
|
||||
`std::chrono::system_clock <https://en.cppreference.com/w/cpp/chrono/system_clock>`_,
|
||||
we use:
|
||||
|
||||
- `GetSystemTimePreciseAsFileTime <https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimepreciseasfiletime>`_ and
|
||||
`GetSystemTimeAsFileTime <https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimeasfiletime>`_
|
||||
for host code on Windows.
|
||||
- `clock_gettime(CLOCK_REALTIME, ...) <https://man7.org/linux/man-pages/man3/clock_gettime.3.html>`_ and `gettimeofday <https://man7.org/linux/man-pages/man2/gettimeofday.2.html>`_
|
||||
for host code on Linux, Android, and QNX.
|
||||
- `PTX's %globaltimer <https://docs.nvidia.com/cuda/parallel-thread-execution/index.html#special-registers-globaltimer>`_ for device code.
|
||||
|
||||
`PTX's %globaltimer <https://docs.nvidia.com/cuda/parallel-thread-execution/index.html#special-registers-globaltimer>`_
|
||||
is a system clock which also happens to be monotonically increasing on today's NVIDIA GPUs
|
||||
(e.g. it cannot be updated and is not changed when the host system clock changes).
|
||||
However, this is not necessarily the case with respect to host threads, where updates of the system clock may occur during the execution of the program.
|
||||
|
||||
`PTX's %globaltimer <https://docs.nvidia.com/cuda/parallel-thread-execution/index.html#special-registers-globaltimer>`_
|
||||
is initialized from the host system clock upon device attach; that may be at program start, but it could be earlier (for example, due to CUDA persistence mode).
|
||||
Since `PTX's %globaltimer <https://docs.nvidia.com/cuda/parallel-thread-execution/index.html#special-registers-globaltimer>`_ is a system clock,
|
||||
it counts real-world time, and thus it has the same tick rate as the host system clock.
|
||||
|
||||
There is potential for logical inconsistencies between the time that host threads and device threads observe from our
|
||||
`std::chrono::system_clock <https://en.cppreference.com/w/cpp/chrono/system_clock>`_.
|
||||
However, this is perfectly fine; it is an inherent property of system clocks. In fact, it is not even guaranteed that a system clock remain
|
||||
consistent between different host threads, or even within the same host thread. This can occur, for example, due to Daylights Savings Time or a
|
||||
time zone change.
|
||||
|
||||
The requirements for `Clock <https://eel.is/c++draft/time.clock.req>`_ state:
|
||||
|
||||
``C1`` denotes a clock type. ``t1`` and ``t2`` are values returned by
|
||||
``C1::now()`` where the call returning ``t1`` `happens before <http://eel.is/c++draft/intro.multithread#def:happens_before>`_
|
||||
the call returning ``t2`` and both of these calls occur before
|
||||
``C1::time_point::max()``.
|
||||
|
||||
``C1::is_steady`` is ``true`` if ``t1 <= t2`` is always true and the
|
||||
time between clock ticks is constant, otherwise ``false``.
|
||||
|
||||
The property is true for our `std::chrono::system_clock <https://en.cppreference.com/w/cpp/chrono/system_clock>`_
|
||||
within device code, but it is not true for all threads. Therefore, in the NVIDIA C++ Standard Library today,
|
||||
the value of the ``is_steady`` member of
|
||||
`std::chrono::system_clock <https://en.cppreference.com/w/cpp/chrono/system_clock>`_
|
||||
is ``false``.
|
||||
|
||||
`std::chrono::high_resolution_clock <https://en.cppreference.com/w/cpp/chrono/high_resolution_clock>`_
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The `std::chrono::high_resolution_clock specification <http://eel.is/c++draft/time.clock.hires>`_ states:
|
||||
|
||||
Objects of ``class high_resolution_clock`` represent clocks with the shortest tick period.
|
||||
``high_resolution_clock`` may be a synonym for ``system_clock`` or ``steady_clock``.
|
||||
|
||||
In the NVIDIA C++ Standard Library, `std::chrono::high_resolution_clock <https://en.cppreference.com/w/cpp/chrono/high_resolution_clock>`_
|
||||
is an alias for `std::chrono::system_clock <https://en.cppreference.com/w/cpp/chrono/system_clock>`_.
|
||||
This means that it counts real-world time and that ``is_steady`` is false for our
|
||||
`std::chrono::high_resolution_clock <https://en.cppreference.com/w/cpp/chrono/high_resolution_clock>`_.
|
||||
|
||||
While our `std::chrono::high_resolution_clock <https://en.cppreference.com/w/cpp/chrono/high_resolution_clock>`_
|
||||
is not heterogeneously steady, it is steady within device code, so it is suitable for performance measurement within device code.
|
||||
|
||||
Omissions
|
||||
---------
|
||||
|
||||
The following facilities in section `time.syn <https://eel.is/c++draft/time.syn>`_ of ISO/IEC IS 14882 (the C++ Standard)
|
||||
are not available in the NVIDIA C++ Standard Library today:
|
||||
|
||||
- `std::chrono::steady_clock <https://en.cppreference.com/w/cpp/chrono/steady_clock>`_
|
||||
- a monotonically increasing clock.
|
||||
- `std::chrono::duration I/O operators <https://eel.is/c++draft/time.duration.io>`_.
|
||||
|
||||
`std::chrono::steady_clock <https://en.cppreference.com/w/cpp/chrono/steady_clock>`_
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`std::chrono::steady_clock <https://en.cppreference.com/w/cpp/chrono/steady_clock>`_
|
||||
is, by definition, a monotonically increasing clock (e.g. ``is_steady`` is ``true``). We do not currently have a heterogeneous steady clock.
|
||||
While we have a monotonically increasing clock in host code, and our system clock
|
||||
(`PTX's %globaltimer <https://docs.nvidia.com/cuda/parallel-thread-execution/index.html#special-registers-globaltimer>`_)
|
||||
is monotonically increasing in device code, it is not guaranteed that the host clocks and the device clocks are monotonically increasing with
|
||||
respect to each other, due to how `PTX's %globaltimer <https://docs.nvidia.com/cuda/parallel-thread-execution/index.html#special-registers-globaltimer>`_
|
||||
is initialized. Additionally, ``%globaltime`` and the host steady clock may tick at different rates.
|
||||
|
||||
It may be technically possible to synchronize the clocks and to compute and adjust for the difference in tick rates. However, it would be
|
||||
challenging to do so, and may introduce substantial overhead in the initialization and access of the heterogeneous clock.
|
||||
|
||||
As such, today we do not provide `std::chrono::steady_clock <https://en.cppreference.com/w/cpp/chrono/steady_clock>`_,
|
||||
as we cannot easily provide an efficient implementation that is truly heterogeneous and conforms to the specification.
|
||||
|
||||
`std::chrono::duration I/O Operators <https://eel.is/c++draft/time.duration.io>`_
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Implementing a heterogeneous C++ I/O streams library involves many challenges that we cannot overcome today.
|
||||
24
cccl_upstream/docs/libcudacxx/standard_api/type_support.rst
Normal file
24
cccl_upstream/docs/libcudacxx/standard_api/type_support.rst
Normal file
@@ -0,0 +1,24 @@
|
||||
.. _libcudacxx-standard-api-type-support:
|
||||
|
||||
Type Support Library
|
||||
=======================
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
|
||||
Any Standard C++ header not listed below is omitted.
|
||||
|
||||
.. list-table::
|
||||
:widths: 25 45 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Header
|
||||
- Content
|
||||
- Availability
|
||||
* - `\<cuda/std/climits\> <https://en.cppreference.com/w/cpp/header/climits>`_
|
||||
- Limits of integral types
|
||||
- libcu++ 1.0.0 / CCCL 2.0.0 / CUDA 10.2
|
||||
* - `\<cuda/std/limits\> <https://en.cppreference.com/w/cpp/header/limits>`_
|
||||
- Interface to query properties of all fundamental numeric types
|
||||
- libcu++ 1.0.0 / CCCL 2.0.0 / CUDA 10.2
|
||||
@@ -0,0 +1,56 @@
|
||||
.. _libcudacxx-standard-api-utility:
|
||||
|
||||
Utility Library
|
||||
=======================
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
|
||||
utility_library/bitset
|
||||
utility_library/expected
|
||||
utility_library/functional
|
||||
utility_library/memory
|
||||
utility_library/optional
|
||||
utility_library/tuple
|
||||
utility_library/type_traits
|
||||
utility_library/utility
|
||||
utility_library/variant
|
||||
|
||||
Any Standard C++ header not listed below is omitted. Some of the Standard C++ facilities in this header are omitted, see
|
||||
the information about the individual features for details.
|
||||
|
||||
.. list-table::
|
||||
:widths: 25 45 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Header
|
||||
- Content
|
||||
- Availability
|
||||
* - :ref:`libcudacxx-standard-api-utility-bitset`
|
||||
- Fixed-size sequence of bits
|
||||
- CCCL 2.8.0
|
||||
* - :ref:`libcudacxx-standard-api-utility-expected`
|
||||
- Optional value with error channel
|
||||
- CCCL 2.3.0 / CUDA 12.4
|
||||
* - :ref:`libcudacxx-standard-api-utility-functional`
|
||||
- General-purpose polymorphic function wrapper
|
||||
- CCCL 2.9.0 / CUDA 12.9
|
||||
* - :ref:`libcudacxx-standard-api-utility-memory`
|
||||
- Function objects and function wrappers
|
||||
- libcu++ 1.1.0 / CCCL 2.0.0 / CUDA 11.2
|
||||
* - :ref:`libcudacxx-standard-api-utility-optional`
|
||||
- Optional value
|
||||
- CCCL 2.3.0 / CUDA 12.4
|
||||
* - :ref:`libcudacxx-standard-api-utility-tuple`
|
||||
- Fixed-sized heterogeneous container
|
||||
- libcu++ 1.3.0 / CCCL 2.0.0 / CUDA 11.2
|
||||
* - :ref:`libcudacxx-standard-api-utility-type-traits`
|
||||
- Compile-time type introspection
|
||||
- libcu++ 1.0.0 / CCCL 2.0.0 / CUDA 10.2
|
||||
* - :ref:`libcudacxx-standard-api-utility-utility`
|
||||
- Various utility components
|
||||
- libcu++ 1.3.0 / CCCL 2.0.0 / CUDA 11.2
|
||||
* - :ref:`libcudacxx-standard-api-utility-variant`
|
||||
- Type safe union type
|
||||
- CCCL 2.4.0 / CUDA 12.5
|
||||
@@ -0,0 +1,14 @@
|
||||
.. _libcudacxx-standard-api-utility-bitset:
|
||||
|
||||
``<cuda/std/bitset>``
|
||||
======================
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- All features of ``<bitset>`` are made constexpr in C++14 onwards
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
- On device no exceptions are thrown in case of a bad access.
|
||||
@@ -0,0 +1,16 @@
|
||||
.. _libcudacxx-standard-api-utility-expected:
|
||||
|
||||
<cuda/std/expected>
|
||||
=======================
|
||||
|
||||
See the documentation of the standard header `\<expected\> <https://en.cppreference.com/w/cpp/header/expected>`_
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- All features are available from C++14 onwards.
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
- On device no exceptions are thrown in case of a bad access.
|
||||
@@ -0,0 +1,52 @@
|
||||
.. _libcudacxx-standard-api-utility-functional:
|
||||
|
||||
<cuda/std/functional>
|
||||
=========================
|
||||
|
||||
See the documentation of the standard header `\<functional\> <https://en.cppreference.com/w/cpp/header/functional>`_
|
||||
|
||||
Omissions
|
||||
---------
|
||||
|
||||
The following facilities in section
|
||||
`functional.syn <https://eel.is/c++draft/functional.syn>`_ of ISO/IEC
|
||||
IS 14882 (the C++ Standard) are not available in the NVIDIA C++ Standard
|
||||
Library today:
|
||||
|
||||
- `std::function <https://en.cppreference.com/w/cpp/utility/functional/function>`_
|
||||
- Polymorphic function object wrapper.
|
||||
- `std::bind <https://en.cppreference.com/w/cpp/utility/functional/bind>`_
|
||||
- Generic function object binder / lambda facility.
|
||||
- `std::hash <https://en.cppreference.com/w/cpp/utility/hash>`_
|
||||
- Hash function object.
|
||||
|
||||
std::function
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
`std::function <https://en.cppreference.com/w/cpp/utility/functional/function>`_
|
||||
is a polymorphic function object wrapper. Implementing it requires both
|
||||
polymorphism (either hand built dispatch tables or the use of C++
|
||||
virtual functions) and memory allocation. This means that it is
|
||||
non-trivial to implement a heterogeneous version of this facility today.
|
||||
As such, we have deferred it.
|
||||
|
||||
std::bind
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
`std::bind <https://en.cppreference.com/w/cpp/utility/functional/bind>`_
|
||||
is a general-purpose function object binder / lambda facility. It relies
|
||||
on constexpr global variables for placeholders, which presents
|
||||
heterogeneous implementation challenges today due to how global
|
||||
variables work in NVCC. E.g. We cannot easily ensure the placeholders
|
||||
are the same object with the same address in host and device code.
|
||||
Therefore, we've decided to hold off on providing this feature for now.
|
||||
|
||||
std::hash
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
`std::hash <https://en.cppreference.com/w/cpp/utility/hash>`_ is a
|
||||
function object which hashes entities. While this is an important
|
||||
feature, it is also important that we pick a hash implementation that
|
||||
makes sense for GPUs. That implementation might be different from the
|
||||
default that the upstream libc++ uses. Further research and
|
||||
investigation is required before we can provide this feature.
|
||||
@@ -0,0 +1,25 @@
|
||||
.. _libcudacxx-standard-api-utility-memory:
|
||||
|
||||
<cuda/std/memory>
|
||||
===================
|
||||
|
||||
Provided functionalities
|
||||
------------------------
|
||||
|
||||
- ``cuda::std::addressof``. See the C++ documentation of `std::addressof <https://en.cppreference.com/w/cpp/memory/addressof>`_
|
||||
- ``cuda::std::align``. See the C++ documentation of `std::align <https://en.cppreference.com/w/cpp/memory/align>`_
|
||||
- ``cuda::std::assume_aligned``. See the C++ documentation of `std::assume_aligned <https://en.cppreference.com/w/cpp/memory/assume_aligned>`_
|
||||
- Uninitialized memory algorithms. See the C++ documentation `<https://en.cppreference.com/w/cpp/memory>`_
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- Most features are available from C++11 onwards.
|
||||
- ``cuda::std::addressof`` is constexpr from C++11 on if compiler support is available
|
||||
- ``cuda::std::assume_aligned`` is constexpr from C++14 on
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
- `construct_at` and is only available in C++20 as that is explicitly mentioned in the standard
|
||||
- The specialized memory algorithms are not parallel
|
||||
@@ -0,0 +1,17 @@
|
||||
.. _libcudacxx-standard-api-utility-optional:
|
||||
|
||||
<cuda/std/optional>
|
||||
=======================
|
||||
|
||||
See the documentation of the standard header `\<optional\> <https://en.cppreference.com/w/cpp/header/optional>`_
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- All features are available from C++14 onwards.
|
||||
- All features are available at compile time if the value type supports it.
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
- On device no exceptions are thrown in case of a bad access.
|
||||
@@ -0,0 +1,17 @@
|
||||
.. _libcudacxx-standard-api-utility-tuple:
|
||||
|
||||
<cuda/std/tuple>
|
||||
====================
|
||||
|
||||
See the documentation of the standard header `\<tuple\> <https://en.cppreference.com/w/cpp/header/tuple>`_
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
Before version 1.4.0, ``tuple`` is not available when using NVCC with
|
||||
MSVC as a host compiler, due to compiler bugs.
|
||||
|
||||
Before version 2.3.0 internal compiler errors may be encountered when
|
||||
using ``tuple`` with older updates of MSVC 2017 and MSVC 2019. For MSVC
|
||||
2017, please use version 15.8 or later (``_MSC_VER >= 1915``). For MSVC
|
||||
2019, please use version 16.6 or later (``_MSC_VER >= 1926``).
|
||||
@@ -0,0 +1,11 @@
|
||||
.. _libcudacxx-standard-api-utility-type-traits:
|
||||
|
||||
<cuda/std/type_traits>
|
||||
=======================
|
||||
|
||||
See the documentation of the standard header `\<type_traits\> <https://en.cppreference.com/w/cpp/header/type_traits>`_
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- Most type traits are made available in C++11.
|
||||
@@ -0,0 +1,21 @@
|
||||
.. _libcudacxx-standard-api-utility-utility:
|
||||
|
||||
<cuda/std/utility>
|
||||
======================
|
||||
|
||||
See the documentation of the standard header `\<utility\> <https://en.cppreference.com/w/cpp/header/utility>`_
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- ``pair`` has been made ``trivially_copyable`` in 2.3.0
|
||||
|
||||
Omissions
|
||||
---------
|
||||
|
||||
Prior to version 2.3.0 only ``pair`` is available.
|
||||
|
||||
Since 2.3.0 we have implemented almost all functionality of
|
||||
``<utility>``. Notably support for operator spaceship is missing due to
|
||||
the specification relying on ``std`` types that are not accessible on
|
||||
device.
|
||||
@@ -0,0 +1,24 @@
|
||||
.. _libcudacxx-standard-api-utility-variant:
|
||||
|
||||
<cuda/std/variant>
|
||||
======================
|
||||
|
||||
See the documentation of the standard header `\<variant\> <https://en.cppreference.com/w/cpp/header/variant>`_
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
- All features are available from C++14 onwards.
|
||||
- All features are available at compile time if the different value types support it.
|
||||
|
||||
Restrictions
|
||||
------------
|
||||
|
||||
- On device no exceptions are thrown in case of a bad access.
|
||||
|
||||
Cuda specific changes
|
||||
---------------------
|
||||
|
||||
- ``cuda::std::visit`` utilizes recursion instead of the usual function
|
||||
pointer array. This greatly improves runtime behavior, but comes at
|
||||
the cost of increased compile times.
|
||||
Reference in New Issue
Block a user