Document fuse_conn_info.max_background

Fixes #95.

diff --git a/include/fuse_common.h b/include/fuse_common.h
index 251ad8b01639e20f5e33cde7b06ff3a6cab63110..966a566bb5dbf027c18ea1554f358c0d008a072a 100644 (file)
--- a/include/fuse_common.h
+++ b/include/fuse_common.h
@@ -315,10 +315,32 @@ struct fuse_conn_info {
        unsigned want;
 
        /**
-        * Maximum number of backgrounded requests. If you want to
-        * know what this means, please refer to the kernel source
-        * (and, ideally, submit a brief explanation that can be
-        * included here).
+        * Maximum number of pending "background" requests. A
+        * background request is any type of request for which the
+        * total number is not limited by other means. As of kernel
+        * 4.8, only two types of requests fall into this category:
+        *
+        *   1. Read-ahead requests
+        *   2. Asychronous direct I/O requests
+        *
+        * Read-ahead requests are generated (if max_readahead is
+        * non-zero) by the kernel to preemptively fill its caches
+        * when it anticipates that userspace will soon read more
+        * data.
+        *
+        * Asynchronous direct I/O requests are generated if
+        * FUSE_CAP_ASYNC_DIO is enabled and userspace submits a large
+        * direct I/O request. In this case the kernel will internally
+        * split it up into multiple smaller requests and submit them
+        * to the filesystem concurrently.
+        *
+        * Note that the following requests are *not* background
+        * requests: writeback requests (limited by the kernel's
+        * flusher algorithm), regular (i.e., synchronous and
+        * buffered) userspace read/write requests (limited to one per
+        * thread), asynchronous read requests (Linux's io_submit(2)
+        * call actually blocks, so these are also limited to one per
+        * thread).
         */
        unsigned max_background;