CUDA Driver API (PDF) - v10.1.168 (older) - Last updated April 24, 2019 - Send Feedback

## 5.7. Primary Context Management

This section describes the primary context management functions of the low-level CUDA driver application programming interface.

The primary context is unique per device and shared with the CUDA runtime API. These functions allow integration with other libraries using CUDA.

### Functions

CUresult cuDevicePrimaryCtxGetState ( CUdevice dev, unsigned int* flags, int* active )
  Get the state of the primary context.
CUresult cuDevicePrimaryCtxRelease ( CUdevice dev )
  Release the primary context on the GPU.
CUresult cuDevicePrimaryCtxReset ( CUdevice dev )
  Destroy all allocations and reset all state on the primary context.
CUresult cuDevicePrimaryCtxRetain ( CUcontext* pctx, CUdevice dev )
  Retain the primary context on the GPU.
CUresult cuDevicePrimaryCtxSetFlags ( CUdevice dev, unsigned int flags )
  Set flags for the primary context.

### Functions

CUresult cuDevicePrimaryCtxGetState ( CUdevice dev, unsigned int* flags, int* active )
  Get the state of the primary context.

  ###### Parameters

  `dev`
    - Device to get primary context flags for
  `flags`
    - Pointer to store flags
  `active`
    - Pointer to store context state; 0 = inactive, 1 = active

  ###### Returns

  CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_INVALID_VALUE,

  ###### Description

  Returns in `*flags` the flags for the primary context of `dev`, and in `*active` whether it is active. See cuDevicePrimaryCtxSetFlags for flag values.

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cuDevicePrimaryCtxSetFlags, cuCtxGetFlags, cudaGetDeviceFlags

CUresult cuDevicePrimaryCtxRelease ( CUdevice dev )
  Release the primary context on the GPU.

  ###### Parameters

  `dev`
    - Device which primary context is released

  ###### Returns

  CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_DEVICE

  ###### Description

  Releases the primary context interop on the device by decreasing the usage count by 1. If the usage drops to 0 the primary context of device `dev` will be destroyed regardless of how many threads it is current to.

  Please note that unlike cuCtxDestroy() this method does not pop the context from stack in any circumstances.

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cuDevicePrimaryCtxRetain, cuCtxDestroy, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice, cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit, cuCtxSynchronize

CUresult cuDevicePrimaryCtxReset ( CUdevice dev )
  Destroy all allocations and reset all state on the primary context.

  ###### Parameters

  `dev`
    - Device for which primary context is destroyed

  ###### Returns

  CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_PRIMARY_CONTEXT_ACTIVE

  ###### Description

  Explicitly destroys and cleans up all resources associated with the current device in the current process.

  Note that it is responsibility of the calling function to ensure that no other module in the process is using the device any more. For that reason it is recommended to use cuDevicePrimaryCtxRelease() in most cases. However it is safe for other modules to call cuDevicePrimaryCtxRelease() even after resetting the device.

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cuDevicePrimaryCtxRetain, cuDevicePrimaryCtxRelease, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice, cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit, cuCtxSynchronize, cudaDeviceReset

CUresult cuDevicePrimaryCtxRetain ( CUcontext* pctx, CUdevice dev )
  Retain the primary context on the GPU.

  ###### Parameters

  `pctx`
    - Returned context handle of the new context
  `dev`
    - Device for which primary context is requested

  ###### Returns

  CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_UNKNOWN

  ###### Description

  Retains the primary context on the device, creating it if necessary, increasing its usage count. The caller must call cuDevicePrimaryCtxRelease() when done using the context. Unlike cuCtxCreate() the newly created context is not pushed onto the stack.

  Context creation will fail with CUDA_ERROR_UNKNOWN if the compute mode of the device is CU_COMPUTEMODE_PROHIBITED. The function cuDeviceGetAttribute() can be used with CU_DEVICE_ATTRIBUTE_COMPUTE_MODE to determine the compute mode of the device. The nvidia-smi tool can be used to set the compute mode for devices. Documentation for nvidia-smi can be obtained by passing a -h option to it.

  Please note that the primary context always supports pinned allocations. Other flags can be specified by cuDevicePrimaryCtxSetFlags().

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cuDevicePrimaryCtxRelease, cuDevicePrimaryCtxSetFlags, cuCtxCreate, cuCtxGetApiVersion, cuCtxGetCacheConfig, cuCtxGetDevice, cuCtxGetFlags, cuCtxGetLimit, cuCtxPopCurrent, cuCtxPushCurrent, cuCtxSetCacheConfig, cuCtxSetLimit, cuCtxSynchronize

CUresult cuDevicePrimaryCtxSetFlags ( CUdevice dev, unsigned int flags )
  Set flags for the primary context.

  ###### Parameters

  `dev`
    - Device for which the primary context flags are set
  `flags`
    - New flags for the device

  ###### Returns

  CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_PRIMARY_CONTEXT_ACTIVE

  ###### Description

  Sets the flags for the primary context on the device overwriting perviously set ones. If the primary context is already created CUDA_ERROR_PRIMARY_CONTEXT_ACTIVE is returned.

  The three LSBs of the `flags` parameter can be used to control how the OS thread, which owns the CUDA context at the time of an API call, interacts with the OS scheduler when waiting for results from the GPU. Only one of the scheduling flags can be set when creating a context.

  - CU_CTX_SCHED_SPIN: Instruct CUDA to actively spin when waiting for results from the GPU. This can decrease latency when waiting for the GPU, but may lower the performance of CPU threads if they are performing work in parallel with the CUDA thread.

  - CU_CTX_SCHED_YIELD: Instruct CUDA to yield its thread when waiting for results from the GPU. This can increase latency when waiting for the GPU, but can increase the performance of CPU threads performing work in parallel with the GPU.

  - CU_CTX_SCHED_BLOCKING_SYNC: Instruct CUDA to block the CPU thread on a synchronization primitive when waiting for the GPU to finish work.

  - CU_CTX_BLOCKING_SYNC: Instruct CUDA to block the CPU thread on a synchronization primitive when waiting for the GPU to finish work.

    Deprecated: This flag was deprecated as of CUDA 4.0 and was replaced with CU_CTX_SCHED_BLOCKING_SYNC.

  - CU_CTX_SCHED_AUTO: The default value if the `flags` parameter is zero, uses a heuristic based on the number of active CUDA contexts in the process C and the number of logical processors in the system P. If C > P, then CUDA will yield to other OS threads when waiting for the GPU (CU_CTX_SCHED_YIELD), otherwise CUDA will not yield while waiting for results and actively spin on the processor (CU_CTX_SCHED_SPIN). Additionally, on Tegra devices, CU_CTX_SCHED_AUTO uses a heuristic based on the power profile of the platform and may choose CU_CTX_SCHED_BLOCKING_SYNC for low-powered devices.

  - CU_CTX_LMEM_RESIZE_TO_MAX: Instruct CUDA to not reduce local memory after resizing local memory for a kernel. This can prevent thrashing by local memory allocations when launching many kernels with high local memory usage at the cost of potentially increased memory usage.

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cuDevicePrimaryCtxRetain, cuDevicePrimaryCtxGetState, cuCtxCreate, cuCtxGetFlags, cudaSetDeviceFlags