1.1 --- a/docs/wiki/Paging Thu Jun 23 23:05:52 2022 +0200
1.2 +++ b/docs/wiki/Paging Sat Jun 25 22:50:02 2022 +0200
1.3 @@ -88,8 +88,8 @@
1.4
1.5 ########
1.6
1.7 -A [[FilesystemAccess#Pager|`Pager`]], being a resource that provides
1.8 -filesystem content to clients for a particular file, requests pages from the
1.9 +A [[ServerLibrary#Pager|`Pager`]], being a resource that provides filesystem
1.10 +content to clients for a particular file, requests pages from the
1.11 `PageMapper`, itself having the role of supplying populated pages of content
1.12 from the given file. The `PageMapper` relies on the `AccessMap` to discover
1.13 existing pages for any accessed region of a file, involving the `Pages` object
1.14 @@ -111,6 +111,15 @@
1.15 the queue are themselves recycled and it is then removed from the queue for
1.16 recycling.
1.17
1.18 +== Satisfying Requests for Pages ==
1.19 +
1.20 +The general procedure for satisfying requests for pages is as follows:
1.21 +
1.22 + 1. Attempt to find an existing page for the affected file region.
1.23 + 1. With an existing page, attempt to reserve the page for issuing.
1.24 + 1. Without an existing or reserved page, obtain a fresh page for populating.
1.25 + 1. Queue the page for eventual reuse.
1.26 +
1.27 Since many files are likely to be in use, and since a fixed amount of memory
1.28 may be shared to provide access to file content, the interaction between
1.29 different `PageMapper` objects, operating on behalf of different files, must
1.30 @@ -131,11 +140,13 @@
1.31 /* First page mapper activities. */
1.32
1.33 subgraph {
1.34 - rank=min;
1.35 + rank=same;
1.36
1.37 PageMapper1_note [shape=note,style=filled,fillcolor=gold,label="Find\nflexpage"];
1.38 PageMapper1 [label="PageMapper"];
1.39
1.40 + Accessor1 [label="Accessor"];
1.41 +
1.42 PageMapper1_reserve_note [shape=note,style=filled,fillcolor=gold,label="Reserve\nflexpage"];
1.43 PageMapper1_reserve [label="PageMapper"];
1.44
1.45 @@ -154,6 +165,7 @@
1.46
1.47 AccessMap_note [shape=note,style=filled,fillcolor=gold,label="Provides\nflexpages\ntentatively"];
1.48 AccessMap1 [label="AccessMap"];
1.49 +
1.50 Flexpage1 [label="Flexpage",shape=note,style=dashed];
1.51 Flexpage1_note [shape=note,style=filled,fillcolor=gold,label="Needs reservation\nif found\nby mapper"];
1.52
1.53 @@ -164,7 +176,6 @@
1.54 Flexpage1_queue [label="Flexpage",shape=note];
1.55
1.56 AccessMap_note -> AccessMap1 [dir=none,style=dotted];
1.57 - Flexpage1 -> Flexpage1_note [dir=none,style=dotted];
1.58 Flexpage1_note -> Flexpage1_reserve [dir=none,style=dotted];
1.59 Flexpage1_reserved -> Flexpage1_reserved_note [dir=none,style=dotted];
1.60
1.61 @@ -228,6 +239,8 @@
1.62 PageMapper2_note [shape=note,style=filled,fillcolor=gold,label="Obtain\nflexpage"];
1.63 PageMapper2 [label="PageMapper"];
1.64
1.65 + Accessor2 [label="Accessor"];
1.66 +
1.67 PageMapper2_record_note [shape=note,style=filled,fillcolor=gold,label="Record\nflexpage"];
1.68 PageMapper2_record [label="PageMapper"];
1.69
1.70 @@ -268,13 +281,16 @@
1.71
1.72 /* Flexpage removal from the access map. */
1.73
1.74 - Pages -> AccessMap1 [color="red",label="remove"];
1.75 + Pages -> AccessMap1 [color="red",label="remove\n(via PageMapper)"];
1.76 + AccessMap1 -> PageMapper1 [color="red",label="flush"];
1.77 + PageMapper1 -> Accessor1 [color="red",label="flush"];
1.78
1.79 /* Second pager dataflow. */
1.80
1.81 PageMapper2 -> Pages [color="red",label="flexpage"];
1.82 Pages -> Flexpage2 [color="red",dir=none];
1.83 Flexpage2 -> PageMapper2 [color="red"];
1.84 + PageMapper2 -> Accessor2 [label="fill"];
1.85
1.86 PageMapper2_record -> Flexpage2_reserved [dir=none,label="insert"];
1.87 Flexpage2_reserved -> AccessMap2;
1.88 @@ -290,16 +306,17 @@
1.89
1.90 When a `PageMapper` requests a page from the `Pages` object and when the
1.91 `Pages` object needs to reclaim such a previously issued page, the page
1.92 -obtained from the head of the queue is removed from the `AccessMap` that
1.93 -currently owns it. The "owner" of such a page is employing the page to satisfy
1.94 -requests for content in a region of a particular file. If modified, the page's
1.95 -contents may be flushed to the underlying file when it is removed from the
1.96 -owner. As a consequence of its removal, the `AccessMap` will no longer be able
1.97 -to offer this page to satisfy a request for data in the affected region to its
1.98 -`PageMapper`. A reclaimed page is then returned to the `PageMapper` requiring
1.99 -it, and since the page will no longer reside in the `PageQueue`, it will be
1.100 -exclusively available for that `PageMapper`, being populated with data from
1.101 -the underlying file and then issued to its client.
1.102 +obtained from the head of the queue is removed from the `AccessMap` employed
1.103 +by the `PageMapper` that currently owns it. The "owner" of such a page is
1.104 +employing the page to satisfy requests for content in a region of a particular
1.105 +file. If modified, the page's contents may be flushed to the underlying file
1.106 +when it is removed from the owner. As a consequence of its removal, the
1.107 +`AccessMap` will no longer be able to offer this page to satisfy a request for
1.108 +data in the affected region to its `PageMapper`. A reclaimed page is then
1.109 +returned to the `PageMapper` requiring it, and since the page will no longer
1.110 +reside in the `PageQueue`, it will be exclusively available for that
1.111 +`PageMapper`, being populated with data from the underlying file and then
1.112 +issued to its client.
1.113
1.114 == Reserving Available Pages ==
1.115