cuda.core.Program#

class cuda.core.Program(
code: str | bytes | bytearray,
str code_type: 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 (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,
str target_type: str,
name_expressions: tuple | list = (),
logs=None,
) → ObjectCode#

Compile the program to the specified target type.

Parameters:

  • target_type (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.

Returns:

The compiled object code.

Return type:

ObjectCode

Attributes

backend#

str

Return this Program instance’s underlying backend.

Type:

Program.backend

handle#

ProgramHandleT

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).

Type:

Program.handle

pch_status#

str | 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.

Type:

Program.pch_status