# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1648167633 -3600
# Node ID 6c6d66497ac45dd7e07db767f7f327102d9d7e46
# Parent  69806f7995c8bd5407c92ed3401e15478f75aa37
Document the current arrangement of openers, registries and opening objects.

diff -r 69806f7995c8 -r 6c6d66497ac4 docs/wiki/Mechanisms
--- a/docs/wiki/Mechanisms	Thu Mar 24 22:11:47 2022 +0100
+++ b/docs/wiki/Mechanisms	Fri Mar 25 01:20:33 2022 +0100
@@ -206,3 +206,40 @@
 }}}
 
 ########
+
+The `ResourceRegistry` coordinates access to filesystem resources and, through
+synchronisation, prevents conflicting operations from occurring concurrently.
+For example, a removal operation on a file may not be allowed to occur while
+an opening operation is in progress.
+
+To achieve this, a common lock is employed to serialise access, with any
+underlying filesystem operations being initiated from the registry while the
+lock is held. An object providing the `FileOpening` interface for a filesystem
+provides such operations, and the following interaction pattern is thereby
+employed:
+
+######## A graph showing the registry coordinating filesystem operations
+
+{{{#!graphviz
+#format svg
+#transform notugly
+digraph registry_operations {
+  node [fontsize="12.0",fontname="sans-serif",shape=box];
+  edge [fontsize="12.0",fontname="sans-serif"];
+  rankdir=LR;
+
+  OpenerContextResource -> OpenerResource -> ResourceRegistry -> FileOpening;
+}
+}}}
+
+########
+
+Since the `ResourceRegistry` functionality is generic, it could be specialised
+for each filesystem or be configured with an appropriate reference to a
+`FileOpening` object. The `OpenerResource` would then be generic, invoking the
+registry which would, in turn, invoke the opening object.
+
+However, the chosen approach is to permit `OpenerResource` objects to
+implement the `FileOpening` interface for each filesystem, meaning that the
+`ResourceRegistry` will end up being called by the opener and then invoking
+the opener in return.