From: Nikolaus Rath <Nikolaus@rath.org>
Date: Sun, 18 Sep 2016 03:03:58 +0000 (-0700)
Subject: Added notes for libfuse hackers.
X-Git-Tag: fuse-3.0.0pre0~24
X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=944d1e1521935e82a3e667a401c7184467793ebc;p=qemu-gpiodev%2Flibfuse.git

Added notes for libfuse hackers.
---

diff --git a/doc/developer-notes.rst b/doc/developer-notes.rst
new file mode 100644
index 0000000..4e9b31a
--- /dev/null
+++ b/doc/developer-notes.rst
@@ -0,0 +1,35 @@
+=================
+ Developer Notes
+=================
+
+If you are working on libfuse itself (rather than using it for a
+different project) this file should be of interest to you. Otherwise
+you should ignore it entirely.
+
+Channel Interface
+=================
+
+From the API, it may appear as if every fuse session (`struct
+fuse_session`) is associated with a single fuse channel (`struct
+fuse_chan`) that is created by `fuse_mount()` and assigned to the
+session in `fuse_session_add_chan()`. Therefore, one may wonder why
+there are two separate structs in the first place, and why the channel
+structure has a reference counter and mutex.
+
+The answer is that when using the multi-threaded session loop with the
+*clone_fd* option enabled, there are actually multiple channel objects
+per session. The session only holds a reference to the first one, and
+the additional channel objects don't actually hold references to the
+session object -- but they still exist. The additional channels are
+created by duplicating the fd (in `fuse_clone_chan()`, called by
+`fuse_loop_start_thread`). When processing a request,
+`fuse_session_process_buf()` records the active channel in the request
+object (`struct fuse_req`) so that it can be retrieved by e.g.  the
+``fuse_reply_*`` functions. Since the request object can potentially
+live longer than the worker thread that created it, we need to keep a
+reference count for the channel.
+
+The reason for not having references to the session object from the
+extra channels is not clear, but with the current implementation this
+would not work because `fuse_session_remove_chan` always attempts to
+remove the channel from the session.