CUDA Host API (Deprecated)

Warning

The host API functions are not recommended for use in new code, and are provided for backwards compatibility with code written for Numba-CUDA. It is recommended that the cuda.core equivalents are used for new code.

Device Management

Note

See Devices and execution in the cuda.core documentation for recommended replacement APIs.

Device detection and enquiry

The following functions are available for querying the available hardware:

Context management

CUDA Python functions execute within a CUDA context. Each CUDA device in a system has an associated CUDA context, and Numba presently allows only one context per thread. For further details on CUDA Contexts, refer to the CUDA Driver API Documentation on Context Management and the CUDA C Programming Guide Context Documentation. CUDA Contexts are instances of the Context class:

The following functions can be used to get or select the context:

The following functions affect the current context:

Device management

Numba maintains a list of supported CUDA-capable devices:

numba.cuda.gpus

An indexable list of supported CUDA devices. This list is indexed by integer device ID.

Alternatively, the current device can be obtained:

numba.cuda.gpus.current

The currently-selected device.

Getting a device through numba.cuda.gpus always provides an instance of numba.cuda.cudadrv.devices._DeviceContextManager, which acts as a context manager for the selected device:

One may also select a context and device or get the current device using the following three functions:

The numba.cuda.cudadrv.driver.Device class can be used to enquire about the functionality of the selected device:

class numba.cuda.cudadrv.driver.Device

The device associated with a particular context.

compute_capability

A tuple, (major, minor) indicating the supported compute capability.

id

The integer ID of the device.

name

The name of the device (e.g. “GeForce GTX 970”).

uuid

The UUID of the device (e.g. “GPU-e6489c45-5b68-3b03-bab7-0e7c8e809643”).

reset()

Delete the context for the device. This will destroy all memory allocations, events, and streams created within the context.

supports_float16

Return True if the device supports float16 operations, False otherwise.

Events

Note

See the Event class in the cuda.core documentation for recommended replacement APIs.

Events can be used to monitor the progress of execution and to record the timestamps of specific points being reached. Event creation returns immediately, and the created event can be queried to determine if it has been reached. For further information, see the CUDA C Programming Guide Events section.

The following functions are used for creating and measuring the time between events:

Events are instances of the numba.cuda.cudadrv.driver.Event class:

Stream Management

Note

See the Stream class in the cuda.core documentation for recommended replacement APIs.

Streams allow concurrency of execution on a single device within a given context. Queued work items in the same stream execute sequentially, but work items in different streams may execute concurrently. Most operations involving a CUDA device can be performed asynchronously using streams, including data transfers and kernel execution. For further details on streams, see the CUDA C Programming Guide Streams section.

Numba defaults to using the legacy default stream as the default stream. The per-thread default stream can be made the default stream by setting the environment variable NUMBA_CUDA_PER_THREAD_DEFAULT_STREAM to 1 (see the CUDA Environment Variables section). Regardless of this setting, the objects representing the legacy and per-thread default streams can be constructed using the functions below.

Streams are instances of numba.cuda.cudadrv.driver.Stream:

To create a new stream:

To get the default stream:

To get the default stream with an explicit choice of whether it is the legacy or per-thread default stream:

To construct a Numba Stream object using a stream allocated elsewhere, the external_stream function is provided. Note that the lifetime of external streams must be managed by the user - Numba will not deallocate an external stream, and the stream must remain valid whilst the Numba Stream object is in use.