From: Nikolaus Rath <Nikolaus@rath.org>
Date: Tue, 6 Nov 2018 18:41:58 +0000 (+0000)
Subject: Document when  `fuse_lowlevel_notify_*` functions may block.
X-Git-Tag: fuse-3.3.0~4
X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=b7ccb0d4c9771b3a82f2e7a9d0b1902babe0279f;p=qemu-gpiodev%2Flibfuse.git

Document when  `fuse_lowlevel_notify_*` functions may block.
---

diff --git a/ChangeLog.rst b/ChangeLog.rst
index 24b4d9c..0b6ce98 100644
--- a/ChangeLog.rst
+++ b/ChangeLog.rst
@@ -17,6 +17,9 @@ Unreleased Changes
   filesystem fully unprivileged and unable to re-acquire privilege via setuid,
   fscaps, etc.
 
+* Documented under which conditions the `fuse_lowlevel_notify_*`
+  functions may block.
+
 libfuse 3.2.6 (2018-08-31)
 ==========================
 
diff --git a/include/fuse_lowlevel.h b/include/fuse_lowlevel.h
index 7ae8c1e..395c0d9 100644
--- a/include/fuse_lowlevel.h
+++ b/include/fuse_lowlevel.h
@@ -1531,6 +1531,15 @@ int fuse_lowlevel_notify_poll(struct fuse_pollhandle *ph);
  * this (or a newer) version, the function will return -ENOSYS and do
  * nothing.
  *
+ * If the filesystem has writeback caching enabled, invalidating an
+ * inode will first trigger a writeback of all dirty pages. The call
+ * will block until all writeback requests have completed and the
+ * inode has been invalidated. It will, however, not wait for
+ * completion of pending writeback requests that have been issued
+ * before.
+ *
+ * If there are no dirty pages, this function will never block.
+ *
  * @param se the session object
  * @param ino the inode number
  * @param off the offset in the inode where to start invalidating
@@ -1554,6 +1563,8 @@ int fuse_lowlevel_notify_inval_inode(struct fuse_session *se, fuse_ino_t ino,
  * removexattr(), readdir() or readdirplus() request for the inode
  * itself.
  *
+ * When called correctly, this function will never block.
+ *
  * Added in FUSE protocol version 7.12. If the kernel does not support
  * this (or a newer) version, the function will return -ENOSYS and do
  * nothing.
@@ -1582,6 +1593,8 @@ int fuse_lowlevel_notify_inval_entry(struct fuse_session *se, fuse_ino_t parent,
  * description of fuse_lowlevel_notify_inval_entry() for more
  * details).
  *
+ * When called correctly, this function will never block.
+ *
  * Added in FUSE protocol version 7.18. If the kernel does not support
  * this (or a newer) version, the function will return -ENOSYS and do
  * nothing.