# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1670718149 -3600
# Node ID 8523b23738c1f8058f75df86396f08d296930392
# Parent  280e444c468cfbd5a788af47e5c36947e528a350
Added PageMapper remarks and diagram.

diff -r 280e444c468c -r 8523b23738c1 docs/wiki/Paging
--- a/docs/wiki/Paging	Sun Dec 11 00:53:17 2022 +0100
+++ b/docs/wiki/Paging	Sun Dec 11 01:22:29 2022 +0100
@@ -2,8 +2,13 @@
 
 Within filesystem servers, a number of abstractions are combined to support
 [[FilesystemAccess|access to filesystem content]] through paging: the delivery
-of content to clients in mapped memory. The general mechanism used to support
-paging is depicted below.
+of content to clients in mapped memory.
+
+<<TableOfContents(2,3)>>
+
+== Overview ==
+
+The general mechanism used to support paging is depicted below.
 
 ######## A graph showing the general paging mechanism
 
@@ -97,6 +102,98 @@
 available or are no longer valid. It also requests the population of such
 pages through use of the associated `Accessor` for the file concerned.
 
+== Pagers and Files ==
+
+Each `PageMapper` is responsible for a particular file, and where multiple
+`Pager` objects provide access to a file for different clients, these will all
+share the same `PageMapper` and thus the same `AccessMap` and `Accessor`. The
+`PageMapper` is initialised when a [[Server Library#Providers|`Provider`]]
+object is created to represent a file.
+
+######## A graph showing the relationships between pagers and files
+
+{{{#!graphviz
+#format svg
+#transform notugly
+digraph pagers_and_files {
+  node [fontsize="12.0",fontname="sans-serif",shape=box];
+  edge [fontsize="12.0",fontname="sans-serif"];
+  rankdir=LR;
+
+  subgraph {
+    rank=same;
+
+    Pager_note12 [shape=note,style=filled,fillcolor=gold,
+     label="Provides\nfilesystem\ncontent\nfor file #1"];
+
+    Pager1 [label="Pager"];
+    Pager2 [label="Pager"];
+    Pager3 [label="Pager"];
+
+    Pager_note3 [shape=note,style=filled,fillcolor=gold,
+     label="Provides\nfilesystem\ncontent\nfor file #2"];
+
+    Pager_note12 -> Pager1 -> Pager2 [dir=none,style=dotted];
+    Pager3 -> Pager_note3 [dir=none,style=dotted];
+  }
+
+  subgraph {
+    rank=same;
+
+    PageMapper1_note [shape=note,style=filled,fillcolor=gold,
+     label="Provides\npopulated\nfile pages\nfor file #1"];
+
+    PageMapper1 [label="PageMapper"];
+    PageMapper2 [label="PageMapper"];
+
+    PageMapper2_note [shape=note,style=filled,fillcolor=gold,
+     label="Provides\npopulated\nfile pages\nfor file #2"];
+
+    PageMapper1_note -> PageMapper1 [dir=none,style=dotted];
+    PageMapper2 -> PageMapper2_note [dir=none,style=dotted];
+  }
+
+  subgraph {
+    rank=same;
+
+    AccessMap1_note [shape=note,style=filled,fillcolor=gold,
+     label="Manages\nfile pages\nfor file #1"];
+
+    AccessMap1 [label="AccessMap"];
+    AccessMap2 [label="AccessMap"];
+
+    AccessMap2_note [shape=note,style=filled,fillcolor=gold,
+     label="Manages\nfile pages\nfor file #2"];
+
+    AccessMap1_note -> AccessMap1 [dir=none,style=dotted];
+    AccessMap2 -> AccessMap2_note [dir=none,style=dotted];
+  }
+
+  subgraph {
+    rank=same;
+
+    Accessor_note [shape=note,style=filled,fillcolor=gold,label="Populates\nfile pages"];
+    Accessor;
+
+    Accessor_note -> Accessor [dir=none,style=dotted];
+  }
+
+  /* Relationships. */
+
+  Pager1 -> PageMapper1;
+  Pager2 -> PageMapper1;
+  Pager3 -> PageMapper2;
+
+  PageMapper1 -> AccessMap1;
+  PageMapper2 -> AccessMap2;
+
+  PageMapper1 -> Accessor;
+  PageMapper2 -> Accessor;
+}
+}}}
+
+########
+
 == Obtaining and Queuing Pages ==
 
 The `Pages` object may either obtain new memory pages from a `Memory` object