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

from __future__ import annotations

from cuda.bindings import nvml
from cuda.core.system.typing import SystemEventType

from . import _device


class SystemEvent:
    """
    Data about a collection of system events.
    """

    def __init__(self, event_data: nvml.SystemEventData_v1):
        ...

    @property
    def event_type(self) -> SystemEventType:
        """
        The :obj:`~SystemEventType` that was triggered.
        """

    @property
    def gpu_id(self) -> int:
        """
        The GPU ID in PCI ID format.
        """

    @property
    def device(self) -> _device.Device:
        """
        The :obj:`~_device.Device` associated with this event.
        """

class SystemEvents:
    """
    Data about a collection of system events.
    """

    def __init__(self, event_data: nvml.SystemEventData_v1):
        ...

    def __len__(self) -> int:
        ...

    def __getitem__(self, idx: int) -> SystemEvent:
        """
        Get the :obj:`~_system_events.SystemEvent` at the specified index.
        """

class RegisteredSystemEvents:
    """
    Represents a set of events that can be waited on for a specific device.
    """

    def __init__(self, events: SystemEventType | str | list[SystemEventType | str]):
        ...

    def __dealloc__(self) -> None:
        ...

    def wait(self, timeout_ms: int=0, buffer_size: int=1) -> SystemEvents:
        """
        Wait for events in the system event set.

        For Fermi™ or newer fully supported devices.

        If some events are ready to be delivered at the time of the call,
        function returns immediately.  If there are no events ready to be
        delivered, function sleeps till event arrives but not longer than
        specified timeout. If timeout passes, a
        :class:`cuda.core.system.TimeoutError` is raised.  This function in
        certain conditions can return before specified timeout passes (e.g. when
        interrupt arrives)

        Parameters
        ----------
        timeout_ms: int
            The timeout in milliseconds. A value of 0 means to wait indefinitely.
        buffer_size: int
            The maximum number of events to retrieve.  Must be at least 1.

        Returns
        -------
        :obj:`~_system_events.SystemEvents`
            A set of events that were received.  The number of events returned may
            be less than the specified buffer size if fewer events were available.

        Raises
        ------
        :class:`cuda.core.system.TimeoutError`
            If the timeout expires before an event is received.
        :class:`cuda.core.system.GpuIsLostError`
            If the GPU has fallen off the bus or is otherwise inaccessible.
        """
_SYSTEM_EVENT_TYPE_MAPPING = {nvml.SystemEventType.GPU_DRIVER_UNBIND: SystemEventType.UNBIND, nvml.SystemEventType.GPU_DRIVER_BIND: SystemEventType.BIND}
_SYSTEM_EVENT_TYPE_INV_MAPPING = {v: k for k, v in _SYSTEM_EVENT_TYPE_MAPPING.items()}
__all__ = ['register_events']

def register_events(events: SystemEventType | str | list[SystemEventType | str]) -> RegisteredSystemEvents:
    """
    Starts recording of events on test system.

    For Linux only.

    All events that occurred before this call are not recorded.  Wait for events
    using the :meth:`RegisteredSystemEvents.wait` method on the result.

    Examples
    --------
    >>> from cuda.core import system
    >>> events = system.register_events([SystemEventType.UNBIND])
    >>> while event := events.wait(timeout_ms=10000):
    ...     print(f"Event {event.event_type} occurred.")

    Parameters
    ----------
    events: SystemEventType, str, or list of SystemEventType or str
        The event type or list of event types to register for this device.

    Returns
    -------
    :obj:`~_system_events.RegisteredSystemEvents`
        An object representing the registered events.  Call
        :meth:`~_system_events.RegisteredSystemEvents.wait` on this object to wait for events.

    Raises
    ------
    :class:`cuda.core.system.NotSupportedError`
        None of the requested event types are registered.
    """