add poll notification support

Expose libfuse low-level poll support through pyfuse3 so
filesystems can implement poll(2), select(2) and epoll readiness
notifications.

Add bindings for struct fuse_pollhandle, fuse_reply_poll(),
fuse_lowlevel_notify_poll() and fuse_pollhandle_destroy(). Introduce a
Python PollHandle wrapper and a notify_poll() helper, allowing a
filesystem to retain the poll handle provided by Operations.poll() and
notify it later when readiness changes.

Wire the low-level FUSE poll callback into Operations.poll(), returning
the current readiness mask to the kernel. The default implementation
continues to raise ENOSYS so existing filesystems keep the previous
fallback behaviour unless they opt in.

This is needed by filesystems that emulate pollable kernel interfaces,
such as sysfs GPIO value files, where edge events must wake userspace
processes waiting for POLLPRI.

Fixes: #139
Signed-off-by: Christopher Obbard <christopher.obbard@linaro.org>

Author: obbardc

Include/fuse_common.pxd

@@ -42,6 +42,11 @@ cdef extern from * nogil: # fuse_common.h should not be included
     struct fuse_chan:
         pass
 
+    struct fuse_pollhandle:
+        pass
+
+    void fuse_pollhandle_destroy(fuse_pollhandle *ph)
+
     struct fuse_loop_config:
        int clone_fd
        unsigned max_idle_threads

Include/fuse_lowlevel.pxd

@@ -119,6 +119,8 @@ cdef extern from "<fuse_lowlevel.h>" nogil:
                            off_t offset, off_t length, fuse_file_info *fi) except *
         void (*readdirplus) (fuse_req_t req, fuse_ino_t ino, size_t size, off_t off,
                              fuse_file_info *fi) except *
+        void (*poll) (fuse_req_t req, fuse_ino_t ino, fuse_file_info *fi,
+                      fuse_pollhandle *ph) except *
 
 
     # Reply functions
@@ -137,6 +139,7 @@ cdef extern from "<fuse_lowlevel.h>" nogil:
                         fuse_buf_copy_flags flags)
     int fuse_reply_statfs(fuse_req_t req, statvfs *stbuf)
     int fuse_reply_xattr(fuse_req_t req, size_t count)
+    int fuse_reply_poll(fuse_req_t req, unsigned revents)
 
     size_t fuse_add_direntry(fuse_req_t req, const_char *buf, size_t bufsize,
                              const_char *name, struct_stat *stbuf,
@@ -157,6 +160,7 @@ cdef extern from "<fuse_lowlevel.h>" nogil:
                                    fuse_buf_copy_flags flags)
     int fuse_lowlevel_notify_retrieve(fuse_session *se, fuse_ino_t ino,
                                       size_t size, off_t offset, void *cookie)
+    int fuse_lowlevel_notify_poll(fuse_pollhandle *ph)
 
     # Utility functions
     void *fuse_req_userdata(fuse_req_t req)

src/pyfuse3/__init__.pyi

@@ -129,6 +129,9 @@ class FUSEError(Exception):
     def __init__(self, errno: int) -> None: ...
     def __str__(self) -> str: ...
 
+class PollHandle:
+    def __getstate__(self) -> None: ...
+
 def listdir(path: str) -> List[str]: ...
 def syncfs(path: str) -> str: ...
 def setxattr(path: str, name: str, value: bytes, namespace: NamespaceT = ...) -> None: ...
@@ -143,6 +146,7 @@ def invalidate_entry_async(
     inode_p: InodeT, name: FileNameT, deleted: InodeT = ..., ignore_enoent: bool = ...
 ) -> None: ...
 def notify_store(inode: InodeT, offset: int, data: bytes) -> None: ...
+def notify_poll(handle: PollHandle) -> None: ...
 def get_sup_groups(pid: int) -> set[int]: ...
 def readdir_reply(
     token: ReaddirToken, name: FileNameT, attr: EntryAttributes, next_id: int

src/pyfuse3/__init__.pyx

@@ -504,6 +504,40 @@ cdef class FUSEError(Exception):
         return strerror(self.errno_)
 
 
+@cython.freelist(10)
+cdef class PollHandle:
+    '''Opaque handle for delivering poll(2) readiness notifications.
+
+    Instances of this class are created by pyfuse3 and passed to
+    `Operations.poll`. The filesystem may keep a reference and later
+    pass the handle to `notify_poll` to wake up any process currently
+    blocked in :manpage:`poll(2)`, :manpage:`select(2)` or
+    :manpage:`epoll_wait(2)` for the corresponding file descriptor.
+
+    A single notification is sufficient to clear all pending waiters;
+    further notifications on the same handle are harmless but redundant.
+
+    The underlying ``fuse_pollhandle`` is automatically destroyed when
+    the Python object is garbage collected, so filesystems should simply
+    drop the reference (e.g. by overwriting it with a fresh handle from
+    a subsequent ``poll`` call) when the notification is no longer
+    needed.
+    '''
+
+    cdef fuse_pollhandle *_ph
+
+    def __cinit__(self):
+        self._ph = NULL
+
+    def __dealloc__(self):
+        if self._ph is not NULL:
+            fuse_pollhandle_destroy(self._ph)
+            self._ph = NULL
+
+    def __getstate__(self):
+        raise PicklingError("PollHandle instances can't be pickled")
+
+
 def listdir(path):
     '''Like `os.listdir`, but releases the GIL.
 
@@ -952,6 +986,34 @@ def invalidate_entry_async(inode_p, name, deleted=0, ignore_enoent=False):
     _notify_queue.put((inode_p, name, deleted, ignore_enoent))
 
 
+def notify_poll(PollHandle handle not None):
+    '''Notify IO readiness for *handle*.
+
+    *handle* must be a `PollHandle` instance that was previously received
+    by an `Operations.poll` call. After this returns, any process waiting
+    in :manpage:`poll(2)`, :manpage:`select(2)` or :manpage:`epoll_wait(2)`
+    on the corresponding file descriptor will be woken so it can re-poll
+    the filesystem for the current readiness mask.
+
+    A single notification is enough to clear all pending waiters; calling
+    this function again on the same handle is harmless but redundant.
+    The handle remains valid (and may be notified again) until its Python
+    reference is dropped, at which point the underlying ``fuse_pollhandle``
+    is destroyed.
+    '''
+
+    cdef int ret
+
+    if handle._ph is NULL:
+        raise RuntimeError('PollHandle has been invalidated')
+
+    with nogil:
+        ret = fuse_lowlevel_notify_poll(handle._ph)
+
+    if ret != 0:
+        raise OSError(-ret, 'fuse_lowlevel_notify_poll returned: ' + strerror(-ret))
+
+
 def notify_store(inode, offset, data):
     '''Store data in kernel page cache
 

src/pyfuse3/_pyfuse3.py

@@ -35,6 +35,7 @@
         EntryAttributes,
         FileInfo,
         FUSEError,
+        PollHandle,
         ReaddirToken,
         RequestContext,
         SetattrFields,
@@ -451,6 +452,39 @@ async def fsync(self, fh: FileHandleT, datasync: bool) -> None:
 
         raise FUSEError(errno.ENOSYS)
 
+    async def poll(
+        self,
+        inode: InodeT,
+        fh: FileHandleT,
+        poll_handle: Optional["PollHandle"],
+        ctx: "RequestContext",
+    ) -> int:
+        '''Check IO readiness on an open file.
+
+        This method is called when a process performs :manpage:`poll(2)`,
+        :manpage:`select(2)` or :manpage:`epoll_wait(2)` on a file descriptor
+        backed by *fh* (returned by a prior `open` or `create` call). *inode*
+        identifies the inode that *fh* refers to.
+
+        The method must return the bitwise-or of the currently active poll
+        events (e.g. ``select.POLLIN``, ``select.POLLOUT``, ``select.POLLPRI``).
+        If no events are currently ready, return ``0``.
+
+        If *poll_handle* is not ``None``, the kernel is requesting to be
+        notified the next time readiness changes. The filesystem should
+        store the handle and later call `notify_poll` exactly once when
+        a relevant event becomes available. Each `~Operations.poll` call
+        produces a fresh handle; storing a new handle implicitly drops
+        any previously held one (which destroys the underlying libfuse
+        object).
+
+        If this method raises ``FUSEError(errno.ENOSYS)`` (the default),
+        the kernel will fall back to a default poll implementation and
+        will not call this handler again for the lifetime of the mount.
+        '''
+
+        raise FUSEError(errno.ENOSYS)
+
     async def opendir(self, inode: InodeT, ctx: "RequestContext") -> FileHandleT:
         '''Open the directory with inode *inode*.
 

src/pyfuse3/handlers.pxi

@@ -836,6 +836,40 @@ async def fuse_access_async (_Container c):
 
 
 
+cdef void fuse_poll (fuse_req_t req, fuse_ino_t ino, fuse_file_info *fi,
+                     fuse_pollhandle *ph):
+    cdef _Container c = _Container()
+    cdef PollHandle py_ph
+    c.req = req
+    c.ino = ino
+    if fi is NULL:
+        c.fh = 0
+    else:
+        c.fh = fi.fh
+    if ph is NULL:
+        py_ph = None
+    else:
+        py_ph = PollHandle.__new__(PollHandle)
+        py_ph._ph = ph
+    save_retval(fuse_poll_async(c, py_ph))
+
+async def fuse_poll_async (_Container c, PollHandle py_ph):
+    cdef int ret
+    cdef unsigned revents
+
+    ctx = get_request_context(c.req)
+    try:
+        result = await operations.poll(c.ino, c.fh, py_ph, ctx)
+    except FUSEError as e:
+        ret = fuse_reply_err(c.req, e.errno)
+    else:
+        revents = <unsigned> (result if result is not None else 0)
+        ret = fuse_reply_poll(c.req, revents)
+
+    if ret != 0:
+        log.error('fuse_poll(): fuse_reply_* failed with %s', strerror(-ret))
+
+
 cdef void fuse_create (fuse_req_t req, fuse_ino_t parent, const_char *name,
                        mode_t mode, fuse_file_info *fi):
     cdef _Container c = _Container()

src/pyfuse3/internal.pxi

@@ -69,6 +69,7 @@ cdef void init_fuse_ops():
     fuse_ops.create = fuse_create
     fuse_ops.forget_multi = fuse_forget_multi
     fuse_ops.write_buf = fuse_write_buf
+    fuse_ops.poll = fuse_poll
 
 cdef make_fuse_args(args, fuse_args* f_args):
     cdef char* arg