Coverage for cuda/core/typing.py: 98.86%

1# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. 

2# 

3# SPDX-License-Identifier: Apache-2.0 

4 

5"""Public type aliases, protocols, and enumerations used in cuda.core API signatures.""" 

6 

7import sys (empty)

8from typing import TYPE_CHECKING (empty)

9from typing import Literal as _Literal (empty)

10from typing import TypeAlias as _TypeAlias (empty)

11 

12if TYPE_CHECKING: (empty)

13 # `backports.strenum` ships no type stubs and typeshed conditionally gates 

14 # `enum.StrEnum` behind `sys.version_info >= (3, 11)`. Declaring a minimal 

15 # local shape here (mirroring typeshed's 3.11 StrEnum) lets mypy at 

16 # `python_version = "3.10"` infer subclass members as `Literal[Foo.MEMBER]` 

17 # rather than bare `str`. 

18 from enum import Enum 

19 

20 class StrEnum(str, Enum): 

21 _value_: str 

22 

23 

24if not TYPE_CHECKING: (empty)

25 if sys.version_info >= (3, 11): (empty)

26 from enum import StrEnum (empty)

27 else: 

28 from backports.strenum import StrEnum 

29 

30from cuda.core._context import DeviceResourcesType (empty)

31from cuda.core._stream import IsStreamType (empty)

32from cuda.core._utils.cuda_utils import driver (empty)

33 

34__all__ = [ (empty)

35 "AddressModeType", 

36 "ArrayFormatType", 

37 "CompilerBackendType", 

38 "DevicePointerType", 

39 "DeviceResourcesType", 

40 "FilterModeType", 

41 "GraphConditionalType", 

42 "GraphMemoryType", 

43 "IsStreamType", 

44 "ManagedMemoryLocationType", 

45 "ObjectCodeFormatType", 

46 "PCHStatusType", 

47 "ProcessStateType", 

48 "ReadModeType", 

49 "SourceCodeType", 

50 "VirtualMemoryAccessType", 

51 "VirtualMemoryAllocationType", 

52 "VirtualMemoryGranularityType", 

53 "VirtualMemoryHandleType", 

54 "VirtualMemoryLocationType", 

55 "WorkqueueSharingScopeType", 

56] 

57 

58 

59# A type union of :obj:`~driver.CUdeviceptr`, `int` and `None` for hinting 

60# :attr:`Buffer.handle`. 

61DevicePointerType: _TypeAlias = driver.CUdeviceptr | int | None (empty)

62 

63 

64ProcessStateType = _Literal["running", "locked", "checkpointed", "failed"] (empty)

65 

66 

67class SourceCodeType(StrEnum): (empty)

68 """Source language passed to :class:`~cuda.core.Program`. 

69 

70 * ``CXX`` — CUDA C++ source. 

71 * ``PTX`` — PTX assembly text. 

72 * ``NVVM`` — NVVM IR (LLVM bitcode). 

73 """ 

74 

75 CXX = "c++" (empty)

76 PTX = "ptx" (empty)

77 NVVM = "nvvm" (empty)

78 

79 

80class ObjectCodeFormatType(StrEnum): (empty)

81 """Output format for :meth:`~cuda.core.Program.compile`, :meth:`~cuda.core.Linker.link`, and :meth:`~cuda.core.Program.as_bytes`. 

82 

83 * ``PTX`` — PTX assembly text. 

84 * ``CUBIN`` — device-native CUDA binary. 

85 * ``LTOIR`` — LTO (link-time optimization) IR for later linking. 

86 * ``FATBIN`` — fat binary bundling multiple device images. 

87 * ``OBJECT`` — relocatable device object. 

88 * ``LIBRARY`` — device code library. 

89 """ 

90 

91 PTX = "ptx" (empty)

92 CUBIN = "cubin" (empty)

93 LTOIR = "ltoir" (empty)

94 FATBIN = "fatbin" (empty)

95 OBJECT = "object" (empty)

96 LIBRARY = "library" (empty)

97 

98 

99class CompilerBackendType(StrEnum): (empty)

100 """Compiler backend inferred from the program's code type and exposed on :attr:`~cuda.core.Program.backend`. 

101 

102 * ``NVRTC`` — NVIDIA Runtime Compilation. 

103 * ``NVVM`` — NVVM LLVM backend. 

104 * ``NVJITLINK`` — nvJitLink device-side linker. 

105 * ``DRIVER`` — CUDA driver PTX JIT compiler. 

106 """ 

107 

108 NVRTC = "NVRTC" (empty)

109 NVVM = "NVVM" (empty)

110 NVJITLINK = "nvJitLink" (empty)

111 DRIVER = "driver" (empty)

112 

113 

114class PCHStatusType(StrEnum): (empty)

115 """Precompiled-header (PCH) outcome reported by :meth:`~cuda.core.Program.compile`. 

116 

117 * ``CREATED`` — PCH was successfully written. 

118 * ``NOT_ATTEMPTED`` — PCH creation was skipped (backend does not support it or the option was not requested). 

119 * ``FAILED`` — PCH creation was attempted but failed. 

120 """ 

121 

122 CREATED = "created" (empty)

123 NOT_ATTEMPTED = "not_attempted" (empty)

124 FAILED = "failed" (empty)

125 

126 

127class GraphConditionalType(StrEnum): (empty)

128 """Conditional node flavor for :class:`~cuda.core.graph.GraphBuilder`. 

129 

130 * ``IF`` — body graph executes at most once based on a condition. 

131 * ``WHILE`` — body graph loops while the condition is true. 

132 * ``SWITCH`` — selects one child graph by an integer index. 

133 """ 

134 

135 IF = "if" (empty)

136 WHILE = "while" (empty)

137 SWITCH = "switch" (empty)

138 

139 

140class GraphMemoryType(StrEnum): (empty)

141 """Memory space for a graph memory-allocation or free node. 

142 

143 * ``DEVICE`` — GPU device memory. 

144 * ``HOST`` — pinned host memory. 

145 * ``MANAGED`` — CUDA managed (unified) memory. 

146 """ 

147 

148 DEVICE = "device" (empty)

149 HOST = "host" (empty)

150 MANAGED = "managed" (empty)

151 

152 

153class ManagedMemoryLocationType(StrEnum): (empty)

154 """Destination type for managed-memory prefetch and advise operations. 

155 

156 * ``DEVICE`` — target a GPU device. 

157 * ``HOST`` — target the CPU host (any NUMA node). 

158 * ``HOST_NUMA`` — target a specific host NUMA node. 

159 """ 

160 

161 DEVICE = "device" (empty)

162 HOST = "host" (empty)

163 HOST_NUMA = "host_numa" (empty)

164 

165 

166class VirtualMemoryHandleType(StrEnum): (empty)

167 """OS handle type for exporting virtual memory allocations across processes. 

168 

169 * ``POSIX_FD`` — POSIX file descriptor (Linux). 

170 * ``WIN32_KMT`` — Win32 kernel-mode handle (Windows). 

171 * ``FABRIC`` — NVLink/NVSwitch fabric handle for multi-node topologies. 

172 """ 

173 

174 POSIX_FD = "posix_fd" (empty)

175 WIN32_KMT = "win32_kmt" (empty)

176 FABRIC = "fabric" (empty)

177 

178 

179class VirtualMemoryLocationType(StrEnum): (empty)

180 """Physical backing location for a virtual memory allocation. 

181 

182 * ``DEVICE`` — GPU device memory. 

183 * ``HOST`` — pinned host memory. 

184 * ``HOST_NUMA`` — host memory pinned to a specific NUMA node. 

185 * ``HOST_NUMA_CURRENT`` — host memory on the calling thread's NUMA node. 

186 """ 

187 

188 DEVICE = "device" (empty)

189 HOST = "host" (empty)

190 HOST_NUMA = "host_numa" (empty)

191 HOST_NUMA_CURRENT = "host_numa_current" (empty)

192 

193 

194class VirtualMemoryGranularityType(StrEnum): (empty)

195 """Granularity query type for virtual memory allocations. 

196 

197 * ``MINIMUM`` — smallest allocation size supported by the device. 

198 * ``RECOMMENDED`` — granularity that yields best performance on the device. 

199 """ 

200 

201 MINIMUM = "minimum" (empty)

202 RECOMMENDED = "recommended" (empty)

203 

204 

205class VirtualMemoryAccessType(StrEnum): (empty)

206 """Access permissions for a virtual memory mapping. 

207 

208 * ``READ_WRITE`` — both read and write access. 

209 * ``READ`` — read-only access. 

210 """ 

211 

212 READ_WRITE = "rw" (empty)

213 READ = "r" (empty)

214 

215 

216class VirtualMemoryAllocationType(StrEnum): (empty)

217 """Physical memory type for a virtual memory backing allocation. 

218 

219 * ``PINNED`` — pinned/non-migratable physical allocation (placement via :class:`VirtualMemoryLocationType`). 

220 * ``MANAGED`` — CUDA managed (unified) memory (CUDA 13+ only). 

221 """ 

222 

223 PINNED = "pinned" (empty)

224 MANAGED = "managed" (empty)

225 

226 

227class ArrayFormatType(StrEnum): (empty)

228 """Element format for an :class:`~cuda.core.texture.OpaqueArray` allocation. 

229 

230 Corresponds to ``CUarray_format`` from the CUDA driver API. Each value maps 

231 1:1 to a NumPy dtype; the enum is retained as an explicit escape hatch. 

232 

233 * ``UINT8`` / ``UINT16`` / ``UINT32`` — unsigned integer elements. 

234 * ``INT8`` / ``INT16`` / ``INT32`` — signed integer elements. 

235 * ``FLOAT16`` / ``FLOAT32`` — half- and single-precision float elements. 

236 

237 .. versionadded:: 1.1.0 

238 """ 

239 

240 UINT8 = "uint8" (empty)

241 UINT16 = "uint16" (empty)

242 UINT32 = "uint32" (empty)

243 INT8 = "int8" (empty)

244 INT16 = "int16" (empty)

245 INT32 = "int32" (empty)

246 FLOAT16 = "float16" (empty)

247 FLOAT32 = "float32" (empty)

248 

249 

250class AddressModeType(StrEnum): (empty)

251 """Boundary behavior for out-of-range texture coordinates. 

252 

253 Corresponds to ``CUaddress_mode`` from the CUDA driver API. 

254 

255 * ``WRAP`` — wrap coordinates around (tiling). 

256 * ``CLAMP`` — clamp to the edge texel. 

257 * ``MIRROR`` — reflect coordinates at the boundary. 

258 * ``BORDER`` — return the configured border color. 

259 

260 .. versionadded:: 1.1.0 

261 """ 

262 

263 WRAP = "wrap" (empty)

264 CLAMP = "clamp" (empty)

265 MIRROR = "mirror" (empty)

266 BORDER = "border" (empty)

267 

268 

269class FilterModeType(StrEnum): (empty)

270 """Texel sampling mode for a :class:`~cuda.core.texture.TextureObject`. 

271 

272 Corresponds to ``CUfilter_mode`` from the CUDA driver API. 

273 

274 * ``POINT`` — nearest-texel sampling. 

275 * ``LINEAR`` — (bi/tri)linear interpolation. 

276 

277 .. versionadded:: 1.1.0 

278 """ 

279 

280 POINT = "point" (empty)

281 LINEAR = "linear" (empty)

282 

283 

284class ReadModeType(StrEnum): (empty)

285 """How sampled values are returned to the kernel. 

286 

287 * ``ELEMENT_TYPE`` — return the raw element value (integer formats stay 

288 integer, float stays float). 

289 * ``NORMALIZED_FLOAT`` — integer formats are promoted to a normalized 

290 ``float`` in ``[0, 1]`` (unsigned) or ``[-1, 1]`` (signed). Float 

291 formats are unaffected. 

292 

293 .. versionadded:: 1.1.0 

294 """ 

295 

296 ELEMENT_TYPE = "element_type" (empty)

297 NORMALIZED_FLOAT = "normalized_float" (empty)

298 

299 

300class WorkqueueSharingScopeType(StrEnum): (empty)

301 """Sharing scope for :class:`~cuda.core.WorkqueueResource`. 

302 

303 * ``DEVICE_CTX`` — use all shared workqueue resources across all 

304 contexts (default driver behavior). 

305 * ``GREEN_CTX_BALANCED`` — when possible, use non-overlapping 

306 workqueue resources with other balanced green contexts. 

307 

308 .. versionadded:: 1.1.0 

309 """ 

310 

311 DEVICE_CTX = "device_ctx" (empty)

312 GREEN_CTX_BALANCED = "green_ctx_balanced" (empty)

313 

314 

315del StrEnum (empty)