Document fuse_conn_info.max_background

Fixes #95.

1 files changed, 26 insertions, 4 deletions

diff --git a/include/fuse_common.h b/include/fuse_common.h
index 251ad8b..966a566 100644
--- 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;