cuda.core.Program#

class cuda.core.Program(
code: str | bytes | bytearray,
code_type: SourceCodeType | str,
options: ProgramOptions | None = None,
)#

Represent a compilation machinery to process programs into ObjectCode.

This object provides a unified interface to multiple underlying compiler libraries. Compilation support is enabled for a wide range of code types and compilation types.

Parameters:

  • code (str | bytes | bytearray) – The source code to compile. For C++ and PTX, must be a string. For NVVM IR, can be str, bytes, or bytearray.

  • code_type (SourceCodeType | str) – The type of source code. Must be one of "c++", "ptx", or "nvvm".

  • options (ProgramOptions, optional) – Options to customize the compilation process.

Methods

__init__(*args, **kwargs)#
close(self)#

Destroy this program.

compile(
self,
target_type: ObjectCodeFormatType | str,
name_expressions: tuple | list = (),
logs=None,
*,
cache: 'ProgramCacheResource | None' = None,
) → ObjectCode#

Compile the program to the specified target type.

Parameters:

  • target_type (ObjectCodeFormatType | str) – The compilation target. Must be one of "ptx", "cubin", or "ltoir".

  • name_expressions (tuple | list, optional) – Sequence of name expressions to make accessible in the compiled code. Used for template instantiation and similar cases.

  • logs (object, optional) – Object with a write method to receive compilation logs. On a cache hit no compilation runs and logs receives nothing – callers that rely on log output to confirm a compile happened should compile without cache=.

  • cache (ProgramCacheResource, optional) –

    If provided, the compiled binary is looked up in cache via a key derived from the program’s code, options, and target_type. On a hit the cached bytes are wrapped in a fresh ObjectCode (with the same target_type and ProgramOptions.name) and returned without re-compiling; on a miss the compile output is stored as raw bytes (the cache extracts bytes(object_code.code)). Passing a non-empty name_expressions together with cache= raises ValueError: NVRTC populates ObjectCode.symbol_mapping at compile time and that mapping is not carried in the binary the cache stores, so cache hits would silently miss get_kernel(name_expression) lookups. Options that require an extra_digest (include_path, pre_include, pch, use_pch, pch_dir, NVVM use_libdevice=True, or NVRTC options.name with a directory component) raise ValueError via make_program_cache_key(); for those compiles, use the manual make_program_cache_key(...) pattern directly.

    cache= is independent of ProgramOptions.no_cache: the former controls this program-level cache (compiled-output reuse across calls), while no_cache is forwarded to the Linker to disable its in-process JIT cache for cuLink/nvJitLink. Setting options.no_cache=True does not bypass cache=, and vice-versa.

Returns:

The compiled object code.

Return type:

ObjectCode

Attributes

backend#

Return this Program instance’s underlying CompilerBackendType.

handle#

Return the underlying handle object.

Note

The type of the returned object depends on the backend.

Caution

This handle is a Python object. To get the memory address of the underlying C handle, call int(Program.handle).

pch_status#

PCHStatusType | None

PCH creation outcome from the most recent compile() call.

Possible values:

  • "created" — PCH file was written successfully.

  • "not_attempted" — PCH creation was not attempted (e.g. the compiler decided not to, or automatic PCH processing skipped it).

  • "failed" — an error prevented PCH creation.

  • None — PCH was not requested, the program has not been compiled yet, the backend is not NVRTC (e.g. PTX or NVVM), or the NVRTC bindings are too old to report status.

When create_pch is set in ProgramOptions and the PCH heap is too small, compile() automatically resizes the heap and retries, so "created" should be the common outcome.

Note

PCH is only supported for code_type="c++" programs that use the NVRTC backend. For PTX and NVVM programs this property always returns None.