From: George Hilliard Date: Sun, 19 Nov 2023 10:27:45 +0000 (-0600) Subject: Clarify fuse_lowlevel poll() docstring (#862) X-Git-Tag: fuse-3.17.1-rc0~163 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=3f6cf537b77597d89bebd8387e93d4e42428b966;p=qemu-gpiodev%2Flibfuse.git Clarify fuse_lowlevel poll() docstring (#862) The original docstring was confusing; it was not clear that the ph must be retained indefinitely, nor was it clear that the client *also* needs to reply to the poll call immediately. Clarify this by explaining that it is only necessary to retain a single handle, that the client must retain ph, and that it must immediately call reply. --- diff --git a/include/fuse_lowlevel.h b/include/fuse_lowlevel.h index 3ac97eb..32f4401 100644 --- a/include/fuse_lowlevel.h +++ b/include/fuse_lowlevel.h @@ -1066,21 +1066,24 @@ struct fuse_lowlevel_ops { /** * Poll for IO readiness * - * Note: If ph is non-NULL, the client should notify - * when IO readiness events occur by calling + * The client should immediately respond with fuse_reply_poll(), + * setting revents appropriately according to which events are ready. + * + * Additionally, if ph is non-NULL, the client must retain it and + * notify when all future IO readiness events occur by calling * fuse_lowlevel_notify_poll() with the specified ph. * - * Regardless of the number of times poll with a non-NULL ph - * is received, single notification is enough to clear all. - * Notifying more times incurs overhead but doesn't harm - * correctness. + * Regardless of the number of times poll with a non-NULL ph is + * received, a single notify_poll is enough to service all. (Notifying + * more times incurs overhead but doesn't harm correctness.) Any + * additional received handles can be immediately destroyed. * * The callee is responsible for destroying ph with * fuse_pollhandle_destroy() when no longer in use. * * If this request is answered with an error code of ENOSYS, this is * treated as success (with a kernel-defined default poll-mask) and - * future calls to pull() will succeed the same way without being send + * future calls to poll() will succeed the same way without being send * to the filesystem process. * * Valid replies: