# This file was generated by stubgen-pyx v0.2.6 from cuda_core/cuda/core/_utils/_weak_handles.pyx

"""Test-only weak handles for resource-handle lifetime checks.

This module is **not** part of the public ``cuda.core`` API. It is built into
the package (like other private ``_utils`` modules) purely so the test suite can
observe, deterministically, when the strong references that keep a CUDA resource
alive have all been released -- without relying on driver- or hardware-specific
side effects (for example, whether freed device memory happens to remain
readable).

Every resource handle is owned by a C++ ``std::shared_ptr``. A **weak handle**
is a non-owning ``std::weak_ptr`` observer of that control block: truthy while
some strong owner remains, falsy once the last one is gone. Use :func:`weak_handle`
to obtain a weak handle from a supported front-end object.

To support another type, add a ``cdef _weak_from_<type>`` that reads its ``cdef``
handle field (see ``*.pxd``), assigns to :ctype:`OpaqueHandle`, and extend the
``isinstance`` chain in :func:`weak_handle`. Types whose slots hold arbitrary
Python owners via ``make_opaque_py`` are not covered here -- use
:class:`weakref.ref` on a weak-referenceable owner object in tests instead.
"""
from __future__ import annotations


class WeakHandle:
    """Non-owning weak handle for a resource's shared control block.

    Truthy while some strong owner of the underlying resource handle remains,
    falsy once the last strong reference is released. Obtain instances via
    :func:`weak_handle` rather than constructing directly.
    """

    def __bool__(self):
        ...

    def expired(self):
        """Return ``True`` once every strong owner of the handle is gone."""

    def use_count(self):
        """Number of strong owners currently sharing the handle."""

def weak_handle(obj):
    """Return a :class:`WeakHandle` observing the resource behind ``obj``.

    Currently supports :class:`~cuda.core.Buffer` (allocation handle) and
    :class:`~cuda.core.graph.GraphDefinition` (graph hierarchy handle). See
    the module docstring for how to add more types.

    Raises
    ------
    ValueError
        If ``obj`` is a :class:`~cuda.core.Buffer` with no active allocation.
    TypeError
        If ``obj`` is not a supported type.
    """