"""POSIX fd-readiness helper shared by the stdout drains and the PTY bridge.

``select.select()`` raises ``ValueError: filedescriptor out of range in select()``
once an fd reaches FD_SETSIZE (1024). A long-lived gateway/desktop process holds
that many open fds, and every drain swallowed that ValueError as "fd already
closed", silently discarding output (issue #94928).

``selectors.DefaultSelector`` (epoll on Linux, kqueue on macOS) has no FD_SETSIZE
ceiling. ``poll()`` is not the default: macOS ``poll()`` does not support device
fds and reports a PTY master as POLLNVAL, i.e. "ready" at once, so a PTY read loop
would spin a core. It stays the fallback because, unlike epoll/kqueue, it needs no
fd of its own.
"""

import errno
import os
import selectors
import stat
import sys


class FdWaiter:
    """Readability wait on one fd. Owns a selector (epoll/kqueue are fds themselves):
    create it once per reader lifetime and ``close()`` it when the reader is done."""

    def __init__(self, fd: int, selector_cls):
        self._selector = selector_cls()
        try:
            self._selector.register(fd, selectors.EVENT_READ)
        except BaseException:
            self._selector.close()
            raise

    def wait(self, timeout_s: float) -> bool:
        """True as soon as the fd is readable (EOF and hangup included), False when
        *timeout_s* elapses idle."""
        return bool(self._selector.select(max(timeout_s, 0)))

    def close(self) -> None:
        self._selector.close()


def open_fd_waiter(fd: int):
    """Return an :class:`FdWaiter` for *fd*, or None only when *fd* is closed/invalid
    and there is nothing to drain. Raises OSError when no safe wait exists."""
    try:
        return FdWaiter(fd, selectors.DefaultSelector)
    except ValueError:
        return None
    except OSError as exc:
        if exc.errno == errno.EBADF:
            return None
        # The selector itself could not be set up (EMFILE: the process is at its fd limit)
        # while the fd is still live. poll() needs no extra fd; never report that as EOF.
        # On macOS it is no wait at all for a device (PTY): raise rather than spin.
        if sys.platform == "darwin" and stat.S_ISCHR(os.fstat(fd).st_mode):
            raise
    return FdWaiter(fd, selectors.PollSelector)