# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1641595746 -3600
# Node ID b6d45268d2d9d780582198c6b6713808ba4575e5
# Parent  9cfd2fb90c331d63c10e799500c6620fdba8e327
Added some documentation of the server framework.

diff -r 9cfd2fb90c33 -r b6d45268d2d9 docs/wiki/Filesystems
--- a/docs/wiki/Filesystems	Tue Jan 04 23:43:56 2022 +0100
+++ b/docs/wiki/Filesystems	Fri Jan 07 23:49:06 2022 +0100
@@ -5,6 +5,6 @@
 
 == Topics ==
 
- * [[Components]]
+ * [[Components]] and [[Mechanisms]]
  * [[ClientLibrary|Client Library]]
  * [[Users]]
diff -r 9cfd2fb90c33 -r b6d45268d2d9 docs/wiki/Mechanisms
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Mechanisms	Fri Jan 07 23:49:06 2022 +0100
@@ -0,0 +1,208 @@
+= Mechanisms =
+
+Within the filesystem server library, a number of different abstractions and
+mechanisms are employed to provide access to filesystem objects.
+
+<<TableOfContents(2,3)>>
+
+The abstractions or components used in the library are organised as follows.
+
+######## A graph showing the relationships between library components
+
+{{{#!graphviz
+#format svg
+#transform notugly
+digraph components {
+  node [fontsize="12.0",fontname="sans-serif",shape=box];
+  edge [fontsize="12.0",fontname="sans-serif"];
+  rankdir=LR;
+
+  subgraph {
+    rank=same;
+
+    Resource -> DirectoryResource -> FilePager
+    [dir=none,style=dotted];
+  }
+
+  subgraph {
+    rank=same;
+
+    Provider -> DirectoryProvider -> FileProvider
+    [dir=none,style=dotted];
+  }
+
+  subgraph {
+    rank=same;
+
+    Accessor -> Ext2FileAccessor
+    [dir=none,style=dotted];
+  }
+
+  subgraph {
+    rank=same;
+
+    DirectoryAccessor -> Ext2DirectoryAccessor
+    [dir=none,style=dotted];
+  }
+
+  subgraph {
+    node [shape=ellipse];
+    rank=same;
+
+    Directory [label="dir"];
+    File [label="dir/file"];
+  }
+
+  DirectoryResource -> DirectoryProvider -> Ext2DirectoryAccessor -> Directory;
+  FilePager -> FileProvider -> Ext2FileAccessor -> File;
+}
+}}}
+
+########
+
+== Accountable ==
+
+This interface provides the following operations:
+
+{{{
+attach()
+detach(out unsigned int count)
+}}}
+
+Its purpose is to provide reference counting for components, with the `attach`
+operation incrementing the number of users of a component, and with the
+`detach` operation decrementing the number of users. When components no longer
+have any attached users, they may perform operations to tidy up after
+themselves and permit their deallocation.
+
+== Accessors ==
+
+Accessors provide the means of accessing filesystem object data and metadata.
+Conceptually, files and directories are both exposed by accessors, although
+the interfaces and mechanisms may differ between these types of objects.
+
+=== Directory Accessors ===
+
+Currently, directory accessors provide support for traversing directory
+listings, obtaining the relevant filesystem metadata using the underlying
+filesystem access library.
+
+=== File Accessors ===
+
+File content is accessed through an interface with the following operations:
+
+{{{
+close()
+fill(inout Flexpage flexpage)
+flush(inout Flexpage flexpage)
+get_size(out offset_t size)
+set_size(in offset_t size)
+}}}
+
+The operations need to be supported with actual filesystem operations. For
+example, ext2-based filesystems employ a specific abstraction which invokes
+library functions provided by the `libext2fs` package.
+
+== Providers ==
+
+Providers encapsulate the essential functionality for accessing filesystem
+objects. Implementing the `Accountable` interface, they are shared by
+resources and discarded when no resources are using them.
+
+The following operations are supported by providers:
+
+{{{
+registry(out ProviderRegistry *registry)
+make_resource(out offset_t size, out object_flags_t object_flags, out Resource *resource)
+}}}
+
+Providers are associated with filesystem objects in a registry which can be
+obtained from each provider.
+
+Providers also support the creation of resources through which each user of a
+provider exercises its use of that provider.
+
+== Resources ==
+
+Resources allow each user of a filesystem object to access that object
+independently. They effectively provide a session in which accesses may occur.
+
+The base interface of a resource is as follows:
+
+{{{
+activate()
+close()
+}}}
+
+Activation of a resource is an optional operation that performs any
+initialisation before a resource is made available to its user.
+
+In practice, other operations are required to make resources useful.
+
+=== Directory Resources ===
+
+Directory resources primarily expose the contents of directories in the
+filesystem. They employ directory accessors which concern themselves with the
+actual filesystem content.
+
+[[Components#Directories|Directory components]] are provided using directory
+resources.
+
+=== Pagers ===
+
+Pagers are resources that support dataspace access operations, thus allowing
+the resources to expose filesystem content in mapped memory regions.
+
+[[Components#Files|File components]] and [[Components#Pipes|pipe components]]
+are provided using pagers.
+
+== Registries ==
+
+The basic mechanism for obtaining a resource involves a registry, as
+illustrated by the following diagram.
+
+######## A graph showing the use of a registry in obtaining resources
+
+{{{#!graphviz
+#format svg
+#transform notugly
+digraph registry {
+  node [fontsize="12.0",fontname="sans-serif",shape=box];
+  edge [fontsize="12.0",fontname="sans-serif"];
+  rankdir=LR;
+
+  subgraph {
+    node [label="OpenerContextResource"];
+    rank=same;
+
+    OpenerContextResource1 -> OpenerContextResource2 [dir=none,style=dotted];
+  }
+
+  subgraph {
+    node [label="OpenerResource"];
+    rank=same;
+
+    OpenerResource1 -> OpenerResource2 [dir=none,style=dotted];
+  }
+
+  subgraph {
+    rank=same;
+
+    ResourceRegistry -> Resource;
+  }
+
+  subgraph {
+    rank=same;
+
+    ProviderRegistry -> Provider;
+  }
+
+  OpenerContextResource1 -> OpenerResource1 [label="open"];
+  OpenerResource1 -> ResourceRegistry [label="get_resource"];
+  ResourceRegistry -> ProviderRegistry [label="get/set"];
+
+  Provider -> Resource -> OpenerResource2 -> OpenerContextResource2;
+}
+}}}
+
+########