rocm-systems/projects/hip/docs/reference/cpp_language_support.rst

.. meta::
  :description: This chapter describes the C++ support of the HIP ecosystem
                ROCm software.
  :keywords: AMD, ROCm, HIP, C++

*******************************************************************************
C++ language support
*******************************************************************************

The ROCm platform enables the power of combined C++ and HIP (Heterogeneous-computing
Interface for Portability) code. This code is compiled with a ``clang`` or ``clang++``
compiler. The official compilers support the HIP platform, or you can use the
``amdclang`` or ``amdclang++`` included in the ROCm installation, which are a wrapper for
the official versions.

The source code is compiled according to the ``C++03``, ``C++11``, ``C++14``, ``C++17``,
and ``C++20`` standards, along with HIP-specific extensions, but is subject to
restrictions. The key restriction is the reduced support of standard library in device
code. This is due to the fact that by default a function is considered to run on host,
except for ``constexpr`` functions, which can run on host and device as well.

.. _language_modern_cpp_support:

Modern C++ support
===============================================================================

C++ is considered a modern programming language as of C++11. This section describes how
HIP supports these new C++ features.

C++11 support
-------------------------------------------------------------------------------

The C++11 standard introduced many new features. These features are supported in HIP host
code, with some notable omissions on the device side. The rule of thumb here is that
``constexpr`` functions work on device, the rest doesn't. This means that some important
functionality like ``std::function`` is missing on the device, but unfortunately the
standard library wasn't designed with HIP in mind, which means that the support is in a
state of "works as-is".

Certain features have restrictions and clarifications. For example, any functions using
the ``constexpr`` qualifier or the new ``initializer lists``, ``std::move`` or
``std::forward`` features are implicitly considered to have the ``__host__`` and
``__device__`` execution space specifier. Also, ``constexpr`` variables that are static
members or namespace scoped can be used from both host and device, but only for read
access. Dereferencing a static ``constexpr`` outside its specified execution space causes
an error.

Lambdas are supported, but there are some extensions and restrictions on their usage. For
more information, see the `Extended lambdas`_ section below.

C++14 support
-------------------------------------------------------------------------------

The C++14 language features are supported.

C++17 support
-------------------------------------------------------------------------------

All C++17 language features are supported.

C++20 support
-------------------------------------------------------------------------------

All C++20 language features are supported, but extensions and restrictions apply. C++20
introduced coroutines and modules, which fundamentally changed how programs are written.
HIP doesn't support these features. However, ``consteval`` functions can be called from
host and device, even if specified for host use only.

The three-way comparison operator (spaceship operator ``<=>``) works with host and device
code.

.. _language_restrictions:

Extensions and restrictions
===============================================================================

In addition to the deviations from the standard, there are some general extensions and
restrictions to consider.

Global functions
-------------------------------------------------------------------------------

Functions that serve as an entry point for device execution are called kernels and are
specified with the ``__global__`` qualifier. To call a kernel function, use the triple
chevron operator: ``<<< >>>``. Kernel functions must have a ``void`` return type. These
functions can't:

* have a ``constexpr`` specifier
* have a parameter of type ``std::initializer_list`` or ``va_list``
* use an rvalue reference as a parameter.
* use parameters having different sizes in host and device code, e.g. long double arguments, or structs containing long double members.
* use struct-type arguments which have different layout in host and device code.

Kernels can have variadic template parameters, but only one parameter pack, which must be
the last item in the template parameter list.

Device space memory specifiers
-------------------------------------------------------------------------------

HIP includes device space memory specifiers to indicate whether a variable is allocated
in host or device memory and how its memory should be allocated. HIP supports the
``__device__``, ``__shared__``, ``__managed__``, and ``__constant__`` specifiers.

The ``__device__`` and ``__constant__`` specifiers define global variables, which are
allocated within global memory on the HIP devices. The only difference is that
``__constant__`` variables can't be changed after allocation. The ``__shared__``
specifier allocates the variable within shared memory, which is available for all threads
in a block.

The ``__managed__`` variable specifier creates global variables that are initially
undefined and unaddressed within the global symbol table. The HIP runtime allocates
managed memory and defines the symbol when it loads the device binary. A managed variable
can be accessed in both device and host code.

It's important to know where a variable is stored because it is only available from
certain locations. Generally, variables allocated in the host memory are not accessible
from the device code, while variables allocated in the device memory are not directly
accessible from the host code. Dereferencing a pointer to device memory on the host
results in a segmentation fault. Accessing device variables in host code should be done
through kernel execution or HIP functions like ``hipMemCpyToSymbol``.

Exception handling
-------------------------------------------------------------------------------

An important difference between the host and device code is exception handling. In device
code, this control flow isn't available due to the hardware architecture. The device
code must use return codes to handle errors.

Kernel parameters
-------------------------------------------------------------------------------

There are some restrictions on kernel function parameters. They cannot be passed by
reference, because these functions are called from the host but run on the device. Also,
a variable number of arguments is not allowed.

Classes
-------------------------------------------------------------------------------

Classes work on both the host and device side, but there are some constraints. The
``static`` member functions can't be ``__global__``. ``Virtual`` member functions work,
but a ``virtual`` function must not be called from the host if the parent object was
created on the device, or the other way around, because this behavior is undefined.
Another minor restriction is that ``__device__`` variables, that are global scoped must
have trivial constructors.

Polymorphic function wrappers
-------------------------------------------------------------------------------

HIP doesn't support the polymorphic function wrapper ``std::function``, which was
introduced in C++11.

Extended lambdas
-------------------------------------------------------------------------------

HIP supports Lambdas, which by default work as expected.

Lambdas have implicit host device attributes. This means that they can be executed by
both host and device code, and works the way you would expect. To make a lambda callable
only by host or device code, users can add ``__host__`` or ``__device__`` attribute. The
only restriction is that host variables can only be accessed through copy on the device.
Accessing through reference will cause undefined behavior.

Inline namespaces
-------------------------------------------------------------------------------

Inline namespaces are supported, but with a few exceptions. The following entities can't
be declared in namespace scope within an inline unnamed namespace:

* ``__managed__``, ``__device__``, ``__shared__`` and ``__constant__`` variables
* ``__global__`` function and function templates
* variables with surface or texture type