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

from __future__ import annotations

import uuid
from dataclasses import dataclass

from cuda.core._memory._buffer import Buffer
from cuda.core._memory._ipc import IPCAllocationHandle
from cuda.core._memory._memory_pool import _MemPool
from cuda.core._stream import Stream
from cuda.core.graph import GraphBuilder


@dataclass
class PinnedMemoryResourceOptions:
    """Customizable :obj:`~_memory.PinnedMemoryResource` options.

    Attributes
    ----------
    ipc_enabled : bool, optional
        Specifies whether to create an IPC-enabled memory pool. When set to
        True, the memory pool and its allocations can be shared with other
        processes. (Default to False)

    max_size : int, optional
        Maximum pool size. When set to 0, defaults to a system-dependent value.
        (Default to 0)

    numa_id : int or None, optional
        Host NUMA node ID for pool placement. When set to None (the default),
        the behavior depends on ``ipc_enabled``:

        - ``ipc_enabled=False``: OS-managed placement (location type HOST).
        - ``ipc_enabled=True``: automatically derived from the current CUDA
          device's ``host_numa_id`` attribute, requiring an active CUDA
          context.

        When set to a non-negative integer, that NUMA node is used explicitly
        regardless of ``ipc_enabled`` (location type HOST_NUMA).
    """
    ipc_enabled: bool = False
    max_size: int = 0
    numa_id: int | None = None

class PinnedMemoryResource(_MemPool):
    """
    A host-pinned memory resource managing a stream-ordered memory pool.

    Parameters
    ----------
    options : PinnedMemoryResourceOptions
        Memory resource creation options.

        If set to `None`, the memory resource uses the driver's current
        stream-ordered memory pool. If no memory
        pool is set as current, the driver's default memory pool
        is used.

        If not set to `None`, a new memory pool is created, which is owned by
        the memory resource.

        When using an existing (current or default) memory pool, the returned
        host-pinned memory resource does not own the pool (`is_handle_owned` is
        `False`), and closing the resource has no effect.

    Notes
    -----
    The device associated with ``stream`` must support host memory pools. If
    ``numa_id`` is set or derived for IPC, it must support host NUMA memory pools.
    You can query these capabilities through
    ``Device.properties.host_memory_pools_supported`` and
    ``Device.properties.host_numa_memory_pools_supported``. If the required pool
    is unsupported and stream-ordered allocation is not needed, use
    :class:`LegacyPinnedMemoryResource`.

    To create an IPC-Enabled memory resource (MR) that is capable of sharing
    allocations between processes, specify ``ipc_enabled=True`` in the initializer
    option. When IPC is enabled and ``numa_id`` is not specified, the NUMA node
    is automatically derived from the current CUDA device's ``host_numa_id``
    attribute, which requires an active CUDA context. If ``numa_id`` is
    explicitly set, that value is used regardless of ``ipc_enabled``.

    See :class:`DeviceMemoryResource` for more details on IPC usage patterns.
    """

    def __init__(self, options: PinnedMemoryResourceOptions | dict[str, object] | None=None) -> None:
        ...

    def allocate(self, size: int, *, stream: Stream | GraphBuilder) -> Buffer:
        """Allocate a host-pinned buffer asynchronously on the supplied stream."""

    def __reduce__(self) -> tuple[object, ...]:
        ...

    @staticmethod
    def from_registry(uuid: uuid.UUID) -> PinnedMemoryResource:
        """
        Obtain a registered mapped memory resource.

        Raises
        ------
        RuntimeError
            If no mapped memory resource is found in the registry.
        """

    def register(self, uuid: uuid.UUID) -> PinnedMemoryResource:
        """
        Register a mapped memory resource.

        Returns
        -------
        The registered mapped memory resource. If one was previously registered
        with the given key, it is returned.
        """

    @classmethod
    def from_allocation_handle(cls, alloc_handle: int | IPCAllocationHandle) -> PinnedMemoryResource:
        """Create a host-pinned memory resource from an allocation handle.

        Construct a new `PinnedMemoryResource` instance that imports a memory
        pool from a shareable handle. The memory pool is marked as owned.

        Parameters
        ----------
        alloc_handle : int | IPCAllocationHandle
            The shareable handle of the host-pinned memory resource to import. If an
            integer is supplied, it must represent a valid platform-specific
            handle. It is the caller's responsibility to close that handle.

        Returns
        -------
            A new host-pinned memory resource instance with the imported handle.
        """

    @property
    def allocation_handle(self) -> IPCAllocationHandle:
        """Shareable handle for this memory pool (requires IPC).

        The handle can be used to share the memory pool with other processes.
        The handle is cached in this `MemoryResource` and owned by it.
        """

    @property
    def device_id(self) -> int:
        """Return -1. Pinned memory is host memory and is not associated with a specific device."""

    @property
    def numa_id(self) -> int:
        """The host NUMA node ID used for pool placement, or -1 for OS-managed placement."""

    @property
    def is_device_accessible(self) -> bool:
        """Return True. This memory resource provides device-accessible buffers."""

    @property
    def is_host_accessible(self) -> bool:
        """Return True. This memory resource provides host-accessible buffers."""
__all__ = ['PinnedMemoryResource', 'PinnedMemoryResourceOptions']

def _deep_reduce_pinned_memory_resource(mr: object) -> tuple[object, ...]:
    ...