# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1648168935 -3600
# Node ID eae169ac85c0bda335962dea38822df463d0ca96
# Parent  6c6d66497ac45dd7e07db767f7f327102d9d7e46
Adjusted the resource description, also adding filesystem-related opener
configuration details.

diff -r 6c6d66497ac4 -r eae169ac85c0 docs/wiki/Mechanisms
--- a/docs/wiki/Mechanisms	Fri Mar 25 01:20:33 2022 +0100
+++ b/docs/wiki/Mechanisms	Fri Mar 25 01:42:15 2022 +0100
@@ -124,8 +124,8 @@
 
 == Resources ==
 
-Resources allow each user of a filesystem object to access that object
-independently. They effectively provide a session in which accesses may occur.
+Resources are objects accessed by clients that support a basic level of
+accounting and management.
 
 The base interface of a resource is as follows:
 
@@ -139,23 +139,37 @@
 
 In practice, other operations are required to make resources useful.
 
+In some cases, resources provide the mechanism by which each user of a
+filesystem object may access that object independently. They would then
+effectively provide a session in which accesses can occur.
+
 === 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.
+filesystem to a user. They employ directory accessors which concern themselves
+with the actual filesystem content.
 
 [[Components#Directories|Directory components]] are provided using directory
 resources.
 
-=== Pagers ===
+=== Pagers or File Resources ===
 
 Pagers are resources that support dataspace access operations, thus allowing
-the resources to expose filesystem content in mapped memory regions.
+the resources to expose filesystem content in mapped memory regions to a
+particular user of the object providing the content.
 
 [[Components#Files|File components]] and [[Components#Pipes|pipe components]]
 are provided using pagers.
 
+=== Filesystem Resources ===
+
+Filesystem resources provide the entry point for access to a filesystem by
+other components or programs. Since filesystems often enforce identity-based
+access controls, a filesystem resource will typically support the
+`open_for_user` operation in various forms, with the result of this operation
+being the instantiation of an `OpenerResource` configured for the indicated
+user identity.
+
 == Registries ==
 
 The basic mechanism for obtaining a resource involves a registry, as
@@ -242,4 +256,7 @@
 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.
+the opener in return. This is slightly more convenient than the alternative
+since the opener can be configured with a given user identity, and such
+identity details will ultimately be employed when accessing the underlying
+filesystem itself.