Added notes for libfuse hackers.

1 files changed, 35 insertions, 0 deletions

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.