From f3e746976978a30781b28259132e439ced00dff2 Mon Sep 17 00:00:00 2001 From: Vladislav Zhurba Date: Mon, 4 Nov 2024 12:54:49 -0800 Subject: [PATCH] Move init doc to class with a cleanup --- cuda_core/cuda/core/experimental/_device.py | 31 +++++----- cuda_core/cuda/core/experimental/_event.py | 10 ++- cuda_core/cuda/core/experimental/_launcher.py | 2 + cuda_core/cuda/core/experimental/_memory.py | 23 +++---- cuda_core/cuda/core/experimental/_module.py | 62 +++++++++---------- cuda_core/cuda/core/experimental/_program.py | 24 +++---- cuda_core/cuda/core/experimental/_stream.py | 14 ++--- 7 files changed, 72 insertions(+), 94 deletions(-) diff --git a/cuda_core/cuda/core/experimental/_device.py b/cuda_core/cuda/core/experimental/_device.py index 7890ae53..2899282c 100644 --- a/cuda_core/cuda/core/experimental/_device.py +++ b/cuda_core/cuda/core/experimental/_device.py @@ -19,7 +19,7 @@ class Device: - """Represents a GPU and acts as an entry point for cuda.core features. + """Represent a GPU and act as an entry point for cuda.core features. This is a singleton object that helps ensure interoperability across multiple libraries imported in the process to both see @@ -30,26 +30,23 @@ class Device: resource created through this device, will continue to refer to this device's context. - """ - __slots__ = ("_id", "_mr", "_has_inited") - - def __new__(cls, device_id=None): - """Create and return a singleton :obj:`Device` object. + Newly returend :obj:`Device` object are is a thread-local singleton + for a specified device. - Creates and returns a thread-local singleton :obj:`Device` object - corresponding to a specific device. + Note + ---- + Will not initialize the GPU. - Note - ---- - Will not initialize the GPU. + Parameters + ---------- + device_id : int, optional + Device ordinal to return a :obj:`Device` object for. + Default value of `None` return the currently used device. - Parameters - ---------- - device_id : int, optional - Device ordinal to return a :obj:`Device` object for. - Default value of `None` return the currently used device. + """ + __slots__ = ("_id", "_mr", "_has_inited") - """ + def __new__(cls, device_id=None): # important: creating a Device instance does not initialize the GPU! if device_id is None: device_id = handle_return(cudart.cudaGetDevice()) diff --git a/cuda_core/cuda/core/experimental/_event.py b/cuda_core/cuda/core/experimental/_event.py index a1b03974..a6d5da28 100644 --- a/cuda_core/cuda/core/experimental/_event.py +++ b/cuda_core/cuda/core/experimental/_event.py @@ -36,7 +36,7 @@ class EventOptions: class Event: - """Represents a record of a specific point of execution within a CUDA stream. + """Represent a record at a specific point of execution within a CUDA stream. Applications can asynchronously record events at any point in the program. An event keeps a record of all previous work within @@ -46,15 +46,13 @@ class Event: of work up to event's record, and help establish dependencies between GPU work submissions. + Directly creating an :obj:`Event` is not supported due to ambiguity, + and they should instead be created through a :obj:`Stream` object. + """ __slots__ = ("_handle", "_timing_disabled", "_busy_waited") def __init__(self): - """Unsupported function due to ambiguity. - - New events should instead be created through a :obj:`Stream` object. - - """ self._handle = None raise NotImplementedError( "directly creating an Event object can be ambiguous. Please call " diff --git a/cuda_core/cuda/core/experimental/_launcher.py b/cuda_core/cuda/core/experimental/_launcher.py index a3250227..2787a718 100644 --- a/cuda_core/cuda/core/experimental/_launcher.py +++ b/cuda_core/cuda/core/experimental/_launcher.py @@ -110,6 +110,8 @@ def launch(kernel, config, *kernel_args): Parameters ---------- + kernel : :obj:`Kernel` + Kernel to launch. config : Any Launch configurations inline with options provided by :obj:`LaunchConfig` dataclass. diff --git a/cuda_core/cuda/core/experimental/_memory.py b/cuda_core/cuda/core/experimental/_memory.py index 3eeea660..678f26ee 100644 --- a/cuda_core/cuda/core/experimental/_memory.py +++ b/cuda_core/cuda/core/experimental/_memory.py @@ -22,7 +22,7 @@ class Buffer: - """Represents a handle to allocated memory. + """Represent a handle to allocated memory. This generic object provides a unified representation for how different memory resources are to give access to their memory @@ -32,24 +32,21 @@ class Buffer: establishing both the DLPack and the Python-level buffer protocols. + Parameters + ---------- + ptr : Any + Allocated buffer handle object + size : Any + Memory size of the buffer + mr : :obj:`MemoryResource`, optional + Memory resource associated with the buffer + """ # TODO: handle ownership? (_mr could be None) __slots__ = ("_ptr", "_size", "_mr",) def __init__(self, ptr, size, mr: MemoryResource=None): - """Initialize a new buffer object. - - Parameters - ---------- - ptr : Any - Allocated buffer handle object - size : Any - Memory size of the buffer - mr : :obj:`MemoryResource`, optional - Memory resource associated with the buffer - - """ self._ptr = ptr self._size = size self._mr = mr diff --git a/cuda_core/cuda/core/experimental/_module.py b/cuda_core/cuda/core/experimental/_module.py index b7802633..b587d813 100644 --- a/cuda_core/cuda/core/experimental/_module.py +++ b/cuda_core/cuda/core/experimental/_module.py @@ -46,17 +46,19 @@ def _lazy_init(): class Kernel: - """Represents a compiled kernel that had been loaded onto the device. + """Represent a compiled kernel that had been loaded onto the device. Kernel instances can execution when passed directly into a launch function. + Directly creating a :obj:`Kernel` is not supported, and they + should instead be created through a :obj:`ObjectCode` object. + """ __slots__ = ("_handle", "_module",) def __init__(self): - """Unsupported function whose creation is intended through an :obj:`ObjectCode` object.""" raise NotImplementedError("directly constructing a Kernel instance is not supported") @staticmethod @@ -72,11 +74,34 @@ def _from_obj(obj, mod): class ObjectCode: - """Represents the compiled program loaded onto the device. + """Represent a compiled program that was loaded onto the device. This object provides a unified interface for different types of compiled programs that are loaded onto the device. + Loads the module library with specified module code and JIT options. + + Note + ---- + Usage under CUDA 11.x will only load to the current device + context. + + Parameters + ---------- + module : Union[bytes, str] + Either a bytes object containing the module to load, or + a file path string containing that module for loading. + code_type : Any + String of the compiled type. + Supported options are "ptx", "cubin" and "fatbin". + jit_options : Optional + Mapping of JIT options to use during module loading. + (Default to no options) + symbol_mapping : Optional + Keyword argument dictionary specifying how symbol names + should be mapped before trying to retrieve them. + (Default to no mappings) + """ __slots__ = ("_handle", "_code_type", "_module", "_loader", "_sym_map") @@ -84,37 +109,6 @@ class ObjectCode: def __init__(self, module, code_type, jit_options=None, *, symbol_mapping=None): - """Create and return a compiled program as an instance of an :obj:`ObjectCode`. - - Loads the module library with specified module code and JIT options. - - Note - ---- - Usage under CUDA 11.x will only load to the current device - context. - - Parameters - ---------- - module : Union[bytes, str] - Either a bytes object containing the module to load, or - a file path string containing that module for loading. - code_type : Any - String of the compiled type. - Supported options are "ptx", "cubin" and "fatbin". - jit_options : Optional - Mapping of JIT options to use during module loading. - (Default to no options) - symbol_mapping : Optional - Keyword argument dictionary specifying how symbol names - should be mapped before trying to retrieve them. - (Default to no mappings) - - Returns - ------- - :obj:`ObjectCode` - Newly created :obj:`ObjectCode`. - - """ if code_type not in self._supported_code_type: raise ValueError _lazy_init() diff --git a/cuda_core/cuda/core/experimental/_program.py b/cuda_core/cuda/core/experimental/_program.py index 9123fdee..a59324f8 100644 --- a/cuda_core/cuda/core/experimental/_program.py +++ b/cuda_core/cuda/core/experimental/_program.py @@ -8,12 +8,19 @@ class Program: - """Represents the compilation machinery for processing programs into :obj:`ObjectCode`. + """Represent a compilation machinery to process programs into :obj:`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 : Any + String of the CUDA Runtime Compilation program. + code_type : Any + String of the code type. Only "c++" is currently supported. + """ __slots__ = ("_handle", "_backend", ) @@ -21,21 +28,6 @@ class Program: _supported_target_type = ("ptx", "cubin", "ltoir", ) def __init__(self, code, code_type): - """Create an instance of a :obj:`Program` object. - - Parameters - ---------- - code : Any - String of the CUDA Runtime Compilation program. - code_type : Any - String of the code type. Only "c++" is currently supported. - - Returns - ------- - :obj:`Program` - Newly created program object. - - """ self._handle = None if code_type not in self._supported_code_type: raise NotImplementedError diff --git a/cuda_core/cuda/core/experimental/_stream.py b/cuda_core/cuda/core/experimental/_stream.py index 01f4fd1f..7f50dafd 100644 --- a/cuda_core/cuda/core/experimental/_stream.py +++ b/cuda_core/cuda/core/experimental/_stream.py @@ -36,7 +36,7 @@ class StreamOptions: class Stream: - """Represents a queue of GPU operations that are executed in a specific order. + """Represent a queue of GPU operations that are executed in a specific order. Applications use streams to control the order of execution for GPU work. Work within a single stream are executed sequentially. @@ -46,19 +46,17 @@ class Stream: Advanced users can utilize default streams for enforce complex implicit synchronization behaviors. + Directly creating a :obj:`Stream` is not supported due to ambiguity. + New streams should instead be created through a :obj:`Device` + object, or created directly through using an existing handle + using Stream.from_handle(). + """ __slots__ = ("_handle", "_nonblocking", "_priority", "_owner", "_builtin", "_device_id", "_ctx_handle") def __init__(self): - """Unsupported function due to ambiguity. - - New streams should instead be created through a :obj:`Device` - object, or created directly through using an existing handle - using Stream.from_handle() - - """ # minimal requirements for the destructor self._handle = None self._owner = None