nvmath-python 1.0.0__cp314-cp314t-win_amd64.whl

nvmath/__init__.py

@@ -0,0 +1,45 @@
+# Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. ALL RIGHTS RESERVED.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import importlib.metadata
+
+
+# Attempt to preload libraries.  Fail silently if preload fails.
+def _force_lib_load():
+    from nvmath._utils import module_init_force_cupy_lib_load
+
+    module_init_force_cupy_lib_load()
+
+
+_force_lib_load()
+
+from nvmath import (  # noqa: E402
+    bindings,  # noqa: E402
+    fft,
+    linalg,
+    sparse,
+    tensor,
+)
+from nvmath._utils import (  # noqa: E402
+    ComputeType,
+    CudaDataType,
+    LibraryPropertyType,
+)
+from nvmath.memory import BaseCUDAMemoryManager, BaseCUDAMemoryManagerAsync, MemoryPointer  # noqa: E402
+
+__all__ = [
+    "BaseCUDAMemoryManager",
+    "BaseCUDAMemoryManagerAsync",
+    "bindings",
+    "ComputeType",
+    "CudaDataType",
+    "fft",
+    "LibraryPropertyType",
+    "linalg",
+    "MemoryPointer",
+    "sparse",
+    "tensor",
+]
+
+__version__ = importlib.metadata.version("nvmath-python")

nvmath/_internal/attribute_ifc_factory.py

@@ -0,0 +1,330 @@
+# Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. ALL RIGHTS RESERVED.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Generic factory that builds a Python class with one ``property`` per
+enum member, plus optional ``set_<attr>_unchecked`` methods, from
+caller-supplied closures.
+
+The low-level :func:`_make_attribute_interface_impl` is generic:
+it receives *make_getter* / *make_setter* / *make_setter_unchecked*
+callables that produce the per-attribute closures, then attaches them
+as properties.
+
+Library-specific wrappers (e.g. :func:`make_cublas_attribute_interface`)
+supply the closure factories that encode a particular C API convention
+(argument order, ``size_written`` type, logging, etc.).
+"""
+
+__all__ = ["make_cublas_attribute_interface"]
+
+import ctypes
+import enum
+import logging
+import sys
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+logger = logging.getLogger()
+
+# A closure factory accepted by _impl.  Called once per attribute name;
+# returns the bound method to attach as a getter, setter, etc.
+_ClosureFactory = Callable[[str], Callable]
+
+
+def _make_attribute_interface_impl(
+    *,
+    class_module: str,
+    class_name: str,
+    attribute_names: list[str],
+    make_getter: _ClosureFactory,
+    make_setter: _ClosureFactory | None = None,
+    make_setter_unchecked: _ClosureFactory | None = None,
+) -> type:
+    """Build and return an attribute interface class.
+
+    This is the low-level implementation behind library-specific wrappers
+    such as :func:`make_cublas_attribute_interface`.  It performs no
+    caller-site validation and is completely agnostic to the underlying
+    C API convention -- all library-specific logic lives in the closure
+    factories passed by the caller.
+
+    Args:
+        class_module: ``__module__`` for the generated class.
+        class_name: ``__name__`` and ``__qualname__`` for the generated
+            class.
+        attribute_names: Uppercase attribute names (e.g.
+            ``["POINTER_MODE", "EPILOGUE"]``).
+        make_getter: ``(name) -> getter`` factory that returns a
+            property getter closure.
+        make_setter: ``(name) -> setter`` factory that returns a
+            property setter closure, or ``None`` for read-only
+            interfaces.
+        make_setter_unchecked: ``(name) -> setter`` factory for
+            hot-path setters without logging, or ``None`` to skip.
+    """
+
+    class AttributeInterface:  # noqa: D101
+        if TYPE_CHECKING:
+
+            def __getattr__(self, name: str) -> Any: ...
+            def __setattr__(self, name: str, value: Any) -> None: ...
+
+        def __init__(self, obj: Any) -> None:
+            self._handle = obj
+
+    AttributeInterface.__name__ = class_name
+    AttributeInterface.__qualname__ = class_name
+    AttributeInterface.__module__ = class_module
+
+    for _name in attribute_names:
+        _lower = _name.lower()
+
+        getter = make_getter(_name)
+
+        if make_setter is not None:
+            setter = make_setter(_name)
+            if make_setter_unchecked is not None:
+                setattr(
+                    AttributeInterface,
+                    f"set_{_lower}_unchecked",
+                    make_setter_unchecked(_name),
+                )
+        else:
+            setter = None
+        setattr(AttributeInterface, _lower, property(getter, setter))
+
+    return AttributeInterface
+
+
+# ---------------------------------------------------------------------------
+# cuBLAS-specific wrapper
+# ---------------------------------------------------------------------------
+
+
+def _build_enum_to_ctype_map(
+    attribute_enum: type[enum.IntEnum],
+    get_attribute_dtype_fn: Callable[[enum.IntEnum], np.dtype],
+    exclude: set[str] | None = None,
+) -> dict[str, tuple[int, type, int]]:
+    """
+    Return ``{NAME: (enum_int_value, ctypes_type, sizeof)}`` for every
+    non-deprecated enum member whose name is not in *exclude*.
+    """
+    result: dict[str, tuple[int, type, int]] = {}
+    for member in attribute_enum:
+        name: str = member.name
+
+        if exclude and name in exclude:
+            continue
+
+        try:
+            dtype: np.dtype = get_attribute_dtype_fn(member)
+        except ValueError:
+            continue
+
+        try:
+            ctype = np.ctypeslib.as_ctypes_type(dtype)
+        except NotImplementedError as exc:
+            raise TypeError(
+                f"get_attribute_dtype_fn returned a dtype for {name!r} that cannot be converted to a ctypes type"
+            ) from exc
+
+        result[name] = (member.value, ctype, ctypes.sizeof(ctype))
+
+    return result
+
+
+def _cublas_interface_class_doc(
+    *,
+    attribute_enum: type[enum.IntEnum],
+    get_attribute_fn: Callable[..., None],
+    set_attribute_fn: Callable[..., None] | None,
+    with_unchecked: bool,
+    attribute_names: list[str],
+) -> str:
+    enum_qualname = f"{attribute_enum.__module__}.{attribute_enum.__qualname__}"
+    getter_qualname = f"{get_attribute_fn.__module__}.{get_attribute_fn.__qualname__}"
+
+    names_sorted = sorted(attribute_names)
+    if names_sorted:
+        example_upper = names_sorted[0]
+        example_lower = example_upper.lower()
+    else:
+        example_upper = "UPPER_CASE"
+        example_lower = "lower_case"
+
+    properties_extra = (
+        " (and their ``set_<attr>_unchecked`` variants)" if set_attribute_fn is not None and with_unchecked else ""
+    )
+
+    lines = [
+        f"Property-based access to attributes enumerated in\n``{enum_qualname}``.",
+        "",
+        f"Properties{properties_extra} are generated \ndynamically at import time by ``make_cublas_attribute_interface``.",
+        "",
+        "This avoids hand-writing a property for every entry in "
+        f"``{enum_qualname}``, \nkeeps the interface in sync automatically when new\n"
+        "attributes are added to the binding, and normalises the UPPER_CASE enum\n"
+        "names to lowercase property names "
+        f"(e.g. ``{example_upper}`` becomes ``{example_lower}``).",
+        "",
+    ]
+
+    if set_attribute_fn is not None:
+        set_qualname = f"{set_attribute_fn.__module__}.{set_attribute_fn.__qualname__}"
+        delegates = f"``{getter_qualname}`` / ``{set_qualname}``"
+    else:
+        delegates = f"``{getter_qualname}``"
+    lines.append(
+        "Each generated property delegates to the corresponding\n"
+        f"{delegates} \n"
+        "call with the correct enum value and ctypes type\n"
+        "already baked in via closure."
+    )
+
+    if set_attribute_fn is not None and with_unchecked:
+        lines.extend(
+            [
+                "",
+                "The ``set_<attr>_unchecked`` methods are identical to the property\n"
+                "setters but skip debug logging. They are useful in low-overhead code paths \n"
+                "where the attribute type has already been validated during initialization.",
+            ]
+        )
+
+    return "\n".join(lines)
+
+
+def make_cublas_attribute_interface(
+    *,
+    class_module: str,
+    class_name: str,
+    attribute_enum: type[enum.IntEnum],
+    get_attribute_dtype_fn: Callable[[enum.IntEnum], np.dtype],
+    get_attribute_fn: Callable[..., None],
+    set_attribute_fn: Callable[..., None] | None = None,
+    with_unchecked: bool = False,
+    exclude: set[str] | None = None,
+) -> type:
+    """
+    Build and return an attribute interface class for a cuBLAS-style
+    descriptor whose attributes are accessed through a uniform
+    ``*_get_attribute`` / ``*_set_attribute`` C API pattern.
+
+    The returned class's docstring is generated automatically from the
+    enum and the getter/setter callables (see *Returns*).
+
+    This is the public entry point for all cublasLt and cublasMp
+    descriptor / algorithm interface modules.
+    For example, the entire ``MatmulDescInterface`` for
+    ``nvmath.linalg`` is reduced to::
+
+        from nvmath.bindings import cublasLt as cublaslt
+
+        MatmulDescInterface = make_cublas_attribute_interface(
+            class_module=__name__,
+            class_name="MatmulDescInterface",
+            attribute_enum=cublaslt.MatmulDescAttribute,
+            get_attribute_dtype_fn=cublaslt.get_matmul_desc_attribute_dtype,
+            get_attribute_fn=cublaslt.matmul_desc_get_attribute,
+            set_attribute_fn=cublaslt.matmul_desc_set_attribute,
+        )
+
+    The opaque library handle passed to ``__init__`` is stored as
+    ``self._handle``. Subclasses that need direct access to it (e.g.
+    for variable-length attribute queries) should use ``self._handle``.
+
+    Args:
+        class_module: The ``__module__`` to assign to the generated
+            class.  Callers should pass ``__name__``.
+        class_name: The ``__name__`` and ``__qualname__`` to assign to
+            the generated class.  Must match the module-level variable
+            name the caller assigns the result to.
+        attribute_enum: The binding's enum type whose members enumerate
+            all gettable/settable attributes.
+        get_attribute_dtype_fn: Callable that maps an enum member to its
+            numpy dtype.
+        get_attribute_fn: Callable invoked as
+            ``(handle, enum_value, buf_addr, buf_size, size_written_addr)``
+            that must store the attribute's value into *buf_addr*.
+        set_attribute_fn: Callable invoked as
+            ``(handle, enum_value, buf_addr, buf_size)`` that must apply
+            the new value from *buf_addr*.  ``None`` for read-only
+            interfaces.
+        with_unchecked: If ``True``, generate ``set_<attr>_unchecked``
+            methods (no debug logging).  Requires *set_attribute_fn*.
+        exclude: Enum member names to skip.
+
+    Returns:
+        A class with one *lowercase* property per enum member.
+        Its ``__doc__`` is built automatically from the enum
+        and the getter/setter callables.
+
+    .. note::
+        This function **must** be called at module scope (i.e. as a
+        top-level statement in the module body). A ``RuntimeError`` is
+        raised otherwise. This constraint ensures that the generated
+        class receives a correct ``__qualname__``.
+    """
+
+    if with_unchecked and set_attribute_fn is None:
+        raise ValueError("with_unchecked=True requires set_attribute_fn")
+
+    caller_frame = sys._getframe(1)
+    if caller_frame.f_code.co_name != "<module>":
+        raise RuntimeError("make_cublas_attribute_interface must be called at module level")
+
+    attr_info = _build_enum_to_ctype_map(attribute_enum, get_attribute_dtype_fn, exclude)
+
+    def _cublas_make_getter(name):
+        enum_value, ctype, sizeof = attr_info[name]
+
+        def getter(self):
+            logger.debug("Getting attribute %s.", name)
+            buf = ctype()
+            sw = ctypes.c_uint64()
+            get_attribute_fn(self._handle, enum_value, ctypes.addressof(buf), sizeof, ctypes.addressof(sw))
+            return buf.value
+
+        return getter
+
+    def _cublas_make_setter(name):
+        enum_value, ctype, sizeof = attr_info[name]
+
+        def setter(self, value):
+            logger.debug("Setting attribute %s to %s.", name, value)
+            v = ctype(value)
+            set_attribute_fn(self._handle, enum_value, ctypes.addressof(v), sizeof)
+
+        return setter
+
+    def _cublas_make_setter_unchecked(name):
+        enum_value, ctype, sizeof = attr_info[name]
+
+        def setter_unc(self, value):
+            v = ctype(value)
+            set_attribute_fn(self._handle, enum_value, ctypes.addressof(v), sizeof)
+
+        return setter_unc
+
+    attr_names = list(attr_info)
+    iface_cls = _make_attribute_interface_impl(
+        class_module=class_module,
+        class_name=class_name,
+        attribute_names=attr_names,
+        make_getter=_cublas_make_getter,
+        make_setter=_cublas_make_setter if set_attribute_fn is not None else None,
+        make_setter_unchecked=(_cublas_make_setter_unchecked if (set_attribute_fn is not None and with_unchecked) else None),
+    )
+    iface_cls.__doc__ = _cublas_interface_class_doc(
+        attribute_enum=attribute_enum,
+        get_attribute_fn=get_attribute_fn,
+        set_attribute_fn=set_attribute_fn,
+        with_unchecked=with_unchecked,
+        attribute_names=attr_names,
+    )
+    return iface_cls

nvmath/_internal/layout.py

@@ -0,0 +1,70 @@
+# Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. ALL RIGHTS RESERVED.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+A collection of (internal use) helper functions for shape/stride
+validation and manipulation.
+"""
+
+from collections.abc import Sequence
+
+
+def is_contiguous_layout(sorted_shape: Sequence[int], sorted_strides: Sequence[int]) -> bool:
+    return all(sorted_shape[s - 1] * sorted_strides[s - 1] == sorted_strides[s] for s in range(1, len(sorted_strides)))
+
+
+def is_contiguous_in_memory(shape: Sequence[int], strides: Sequence[int]) -> bool:
+    """
+    Check if the provided (shape, strides) result in a contiguous memory layout.
+    """
+    sorted_strides, sorted_shape = zip(*sorted(zip(strides, shape, strict=True)), strict=True)
+    return is_contiguous_layout(sorted_shape, sorted_strides)
+
+
+def is_contiguous_and_dense(shape: Sequence[int], strides: Sequence[int]) -> bool:
+    """
+    Check if the provided (shape, strides) result in a contiguous memory layout
+    with no extra stride in least strided dimension.
+    """
+    if not shape and not strides:
+        return True
+    sorted_strides, sorted_shape = zip(*sorted(zip(strides, shape, strict=True)), strict=True)
+    if len(sorted_strides) > 0 and sorted_strides[0] != 1:
+        return False
+    return is_contiguous_layout(sorted_shape, sorted_strides)
+
+
+def is_overlapping_layout(shape: Sequence[int], strides: Sequence[int]) -> bool:
+    """
+    For a tensor `t`, if `not is_overlapping_layout(t.shape, t.strides)`,
+    there are no two different valid nd-indices `idxs` such that
+    `t[idxs_0]` and `t[idxs_1]` map to the same offset in the memory.
+    Checks that the strides:
+        1. are positive
+        2. any n - 1 extents maximal offset is smaller than the stride
+           of the n-th extent.
+    The check should return False for contiguous
+    or contiguous and sliced tensors.
+    """
+    if not shape and not strides:
+        return False
+    sorted_strides, sorted_shape = zip(*sorted(zip(strides, shape, strict=True)), strict=True)
+    cur_max_offset = 0
+    for s in range(1, len(sorted_strides)):
+        stride = sorted_strides[s - 1]
+        extent = sorted_shape[s - 1]
+        if stride <= 0:
+            return True
+        cur_max_offset += stride * (extent - 1)
+        if cur_max_offset >= sorted_strides[s]:
+            return True
+    return False
+
+
+def check_monotonic_strides(strides, reverse: bool):
+    """
+    Check if the strides are monotonically increasing (reverse=False) or
+    decreasing (reverse=True).
+    """
+    return sorted(strides, reverse=reverse) == list(strides)

nvmath/_internal/templates.py

@@ -0,0 +1,130 @@
+# Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. ALL RIGHTS RESERVED.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import dataclasses
+import logging
+from logging import Logger
+from typing import ClassVar, Literal
+
+from nvmath import memory
+from nvmath.internal import utils
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class ExecutionCUDA:
+    """
+    A data class for providing GPU execution options.
+
+    Attributes:
+        device_id: CUDA device ordinal (only used if the operand resides on the CPU). The
+            default value is 0.
+
+    .. seealso::
+       :class:`ExecutionCPU`
+    """
+
+    name: ClassVar[Literal["cuda"]] = "cuda"
+    device_id: int = 0
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class ExecutionCPU:
+    """
+    A data class for providing CPU execution options.
+
+    Attributes:
+        num_threads: The number of CPU threads used to execute the operation.
+                     If not specified, defaults to the number of CPU cores available to the
+                     process.
+
+    .. seealso::
+       :class:`ExecutionCUDA`
+    """
+
+    name: ClassVar[Literal["cpu"]] = "cpu"
+    num_threads: int | None = None
+
+
+def copy_operand_perhaps(
+    internal_operand: utils.TensorHolder | None,
+    operand: utils.TensorHolder,
+    stream_holder: utils.StreamHolder | None,
+    execution_device_id: int | Literal["cpu"],
+    operands_device_id: int | Literal["cpu"],
+) -> tuple[utils.TensorHolder, utils.TensorHolder | None]:
+    """Private implementation of memory space management for tensor operands.
+
+    The `copy_operand_perhaps` function facilitates transitions of tensor operands between
+    different memory spaces, ensuring compatibility with execution requirements. Its role is
+    to determine whether a tensor operand needs to be copied to accommodate differing
+    execution and operand memory spaces, while preserving the original operand for cases
+    requiring in-place operations.
+
+    Args:
+        internal_operand: Represents an internal tensor for in-place
+            memory operations, or `None` if not applicable.
+
+        operand: Tensor to possibly copied to the execution memory space.
+
+        stream_holder: Manages the CUDA stream for device operations.
+
+        execution_device_id: Specifies the target execution space.
+
+        operands_device_id: Specifies the current operand memory space.
+
+    Returns:
+        A tuple containing:
+            - The operand copied to the execution space, or the original operand if
+              no copy is necessary.
+            - The original operand, or `None` if no copy occurred.
+
+    """
+    if execution_device_id == operands_device_id:
+        return operand, None
+    else:
+        # Copy the `operand` to memory that matches the exec space
+        # and keep the original `operand` to handle `options.inplace=True`
+        if internal_operand is None:
+            exec_space_copy = operand.to(execution_device_id, stream_holder)
+            return exec_space_copy, operand
+        else:
+            # In-place copy to existing pointer
+            internal_operand.copy_(src=operand, stream_holder=stream_holder)
+            return internal_operand, operand
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class StatefulAPIOptions:
+    """A dataclass for providing options to a stateful API object.
+
+    Attributes:
+        allocator: An object that supports the :class:`BaseCUDAMemoryManager` protocol, used
+            to draw device memory. If an allocator is not provided, a memory allocator from
+            the library package will be used (:func:`torch.cuda.caching_allocator_alloc` for
+            PyTorch operands, :func:`cupy.cuda.alloc` otherwise).
+
+        blocking: A flag specifying the behavior of the stream-ordered functions and
+            methods. When ``blocking`` is `True`, the stream-ordered methods do not return
+            until the operation is complete. When ``blocking`` is ``"auto"``, the methods
+            return immediately when the inputs are on the GPU. The stream-ordered methods
+            always block when the operands are on the CPU to ensure that the user doesn't
+            inadvertently use the result before it becomes available. The default is
+            ``"auto"``.
+
+        logger: Python Logger object. The root logger will be used if a
+            logger object is not provided.
+    """
+
+    allocator: memory.BaseCUDAMemoryManager | memory.BaseCUDAMemoryManagerAsync | None = None
+    blocking: Literal[True, "auto"] = "auto"
+    logger: Logger = dataclasses.field(default_factory=logging.getLogger)
+
+    def __post_init__(self):
+        if self.blocking not in (True, "auto"):
+            raise ValueError("The value specified for blocking must be either True or 'auto'.")
+
+        if self.allocator is not None and not isinstance(
+            self.allocator, memory.BaseCUDAMemoryManager | memory.BaseCUDAMemoryManagerAsync
+        ):
+            raise TypeError("The allocator must be an object of type that fulfills the BaseCUDAMemoryManager protocol.")

nvmath/_internal/threadsafe.py

@@ -0,0 +1,106 @@
+# Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. ALL RIGHTS RESERVED.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Reusable per-thread data structures."""
+
+import sys
+import threading
+import typing
+import weakref
+
+__all__ = ["HandleCache"]
+
+Key = typing.TypeVar("Key")
+
+
+class _CachedHandle(typing.Generic[Key]):
+    # A raw integer handle cannot be the referent of `weakref.finalize`, so we wrap it in
+    # this object and attach the finalizer to the wrapper. The finalizer fires when the
+    # wrapper is garbage-collected — i.e. when the owning thread's `threading.local` storage
+    # is dropped, or at interpreter shutdown.
+
+    __slots__ = ("handle", "__weakref__")
+
+    handle: typing.Final[int]
+
+    def __init__(self, key: Key, create: typing.Callable[[Key], int], destroy: typing.Callable[[int], None]):
+        self.handle = create(key)
+
+        def finalize(handle: int) -> None:
+            # `destroy` is the binding-agnostic callable injected by the consumer. It is
+            # expected to be safe to run on any thread regardless of the current device:
+            # e.g. `cublasDestroy` / `cublasLtDestroy` each internally call
+            # `cudaDeviceSynchronize()` on the handle's own device. That matters because the
+            # finalizer may run on whichever thread garbage-collects the cached handle, not
+            # necessarily the one that created it.
+            try:
+                destroy(handle)
+            except Exception:
+                # Tolerate destroy failures only at interpreter shutdown, where the bindings
+                # module may already be partially torn down. Outside shutdown a destroy
+                # failure is a real bug; re-raising surfaces it as the standard "Exception
+                # ignored in:" message from the finalizer rather than silently leaking the
+                # handle.
+                if not sys.is_finalizing():
+                    raise
+
+        weakref.finalize(self, finalize, self.handle)
+
+
+class HandleCache(typing.Generic[Key]):
+    """Per-thread cache of integer library handles, keyed by an opaque key.
+
+    The key is any hashable the caller chooses: a bare ``device_id``, or a tuple such as
+    ``(device_id, ...)`` for libraries that need to distinguish handles by more than device.
+    The cache never interprets the key — only the injected ``create`` callable does. Because
+    the caching behavior is per-thread, keys only have to be unique per-thread.
+
+    Args:
+
+        create: ``create(key) -> int`` makes a new handle for ``key``. The
+            callable must perform any device-context handling it needs.
+
+        destroy: ``destroy(handle) -> None`` destroys a handle. It is invoked
+            from ``weakref.finalize`` when the owning thread or the interpreter exits, so
+            must be able to run on a different thread than the one that created the handle.
+
+    Examples:
+
+    .. code-block:: python
+
+        from nvmath._internal import threadsafe
+
+
+        def create_handle(device_id: int) -> int:
+            with utils.device_ctx(device_id):
+                return cublas.create()
+
+
+        threadsafe.HandleCache[int](
+            create=create_handle,
+            destroy=cublas.destroy,
+        )
+
+    """
+
+    __slots__ = ("_create", "_destroy", "_tls")
+
+    def __init__(self, create: typing.Callable[[Key], int], destroy: typing.Callable[[int], None]):
+        self._create = create
+        self._destroy = destroy
+        # Per-thread storage; each thread mutates only its own `cache` dict, so
+        # no lock is required.
+        self._tls = threading.local()
+
+    def get(self, key: Key) -> int:
+        """Return the cached handle for ``key`` on the current thread."""
+        try:
+            cache = self._tls.cache
+        except AttributeError:
+            cache = self._tls.cache = {}
+        item = cache.get(key)
+        if item is None:
+            item = _CachedHandle(key, self._create, self._destroy)
+            cache[key] = item
+        return item.handle