1.1 --- a/docs/wiki/Paging Wed Jun 22 00:52:51 2022 +0200
1.2 +++ b/docs/wiki/Paging Wed Jun 22 17:48:29 2022 +0200
1.3 @@ -97,6 +97,8 @@
1.4 available or are no longer valid. It also requests the population of such
1.5 pages through use of the associated `Accessor` for the file concerned.
1.6
1.7 +== Obtaining and Queuing Pages ==
1.8 +
1.9 The `Pages` object may either obtain new memory pages from a `Memory` object
1.10 or reclaim (or recycle) existing pages from a `PageQueue`, this recording all
1.11 pages that have been populated and supplied to clients. Since it may be
1.12 @@ -109,31 +111,12 @@
1.13 the queue are themselves recycled and it is then removed from the queue for
1.14 recycling.
1.15
1.16 -When a `PageMapper` requests a page from the `Pages` object and when the
1.17 -`Pages` object needs to reclaim such a previously issued page, the page
1.18 -obtained from the head of the queue is removed from the `AccessMap` that
1.19 -currently owns it. The "owner" of such a page is employing the page to satisfy
1.20 -requests for content in a region of a particular file. If modified, the page's
1.21 -contents may be flushed to the underlying file when it is removed from the
1.22 -owner. As a consequence of its removal, the `AccessMap` will no longer be able
1.23 -to offer this page to satisfy a request for data in the affected region to its
1.24 -`PageMapper`. A reclaimed page is then returned to the `PageMapper` requiring
1.25 -it, and since the page will no longer reside in the `PageQueue`, it will be
1.26 -exclusively available for that `PageMapper`, being populated with data from
1.27 -the underlying file and then issued to its client.
1.28 -
1.29 -When an `AccessMap` is able to satisfy a request for a page providing access
1.30 -to a region in a particular file, the `PageMapper` must secure exclusive
1.31 -access to that page. Otherwise, the possibility exists that the page will be
1.32 -reclaimed and recycled concurrently by another `PageMapper`. Thus, the
1.33 -`PageMapper` must request that the page be reserved by the `Pages` object
1.34 -which in turn removes the page from the `PageQueue`. Since no other party can
1.35 -now obtain the page independently, it can be issued safely.
1.36 -
1.37 -Once a page has been issued to a client by the `Pager`, regardless of how it
1.38 -was obtained, it must be made available for future reuse. This is achieved by
1.39 -the `PageMapper` requesting the queuing of the page, with it being added to
1.40 -the end of the `PageQueue`.
1.41 +Since many files are likely to be in use, and since a fixed amount of memory
1.42 +may be shared to provide access to file content, the interaction between
1.43 +different `PageMapper` objects, operating on behalf of different files, must
1.44 +be taken into consideration. The following diagram depicts the principal
1.45 +mechanisms involved in securing access to pages so as to provide access to
1.46 +file content.
1.47
1.48 ######## A graph showing concurrency considerations
1.49
1.50 @@ -173,9 +156,11 @@
1.51 AccessMap1 [label="AccessMap"];
1.52 Flexpage1 [label="Flexpage",shape=note,style=dashed];
1.53 Flexpage1_note [shape=note,style=filled,fillcolor=gold,label="Needs reservation\nif found\nby mapper"];
1.54 +
1.55 Flexpage1_reserve [label="Flexpage",shape=note,style=dashed];
1.56 Flexpage1_reserved [label="Flexpage",shape=note];
1.57 Flexpage1_reserved_note [shape=note,style=filled,fillcolor=gold,label="Claimed if\nstill available"];
1.58 +
1.59 Flexpage1_queue [label="Flexpage",shape=note];
1.60
1.61 AccessMap_note -> AccessMap1 [dir=none,style=dotted];
1.62 @@ -193,7 +178,7 @@
1.63 PageQueue [label="PageQueue"];
1.64 Flexpage [shape=note];
1.65 Pages [label="Pages"];
1.66 - Pages_note [shape=note,style=filled,fillcolor=gold,label="Claim and\nrecycle\nflexpage"];
1.67 + Pages_note [shape=note,style=filled,fillcolor=gold,label="Reclaim and\nrecycle\nflexpage"];
1.68
1.69 Flexpage_reserve [label="Flexpage",shape=note];
1.70 Pages_reserve [label="Pages"];
1.71 @@ -272,3 +257,35 @@
1.72 }}}
1.73
1.74 ########
1.75 +
1.76 +== Reclaiming and Recycling Pages ==
1.77 +
1.78 +When a `PageMapper` requests a page from the `Pages` object and when the
1.79 +`Pages` object needs to reclaim such a previously issued page, the page
1.80 +obtained from the head of the queue is removed from the `AccessMap` that
1.81 +currently owns it. The "owner" of such a page is employing the page to satisfy
1.82 +requests for content in a region of a particular file. If modified, the page's
1.83 +contents may be flushed to the underlying file when it is removed from the
1.84 +owner. As a consequence of its removal, the `AccessMap` will no longer be able
1.85 +to offer this page to satisfy a request for data in the affected region to its
1.86 +`PageMapper`. A reclaimed page is then returned to the `PageMapper` requiring
1.87 +it, and since the page will no longer reside in the `PageQueue`, it will be
1.88 +exclusively available for that `PageMapper`, being populated with data from
1.89 +the underlying file and then issued to its client.
1.90 +
1.91 +== Reserving Available Pages ==
1.92 +
1.93 +When an `AccessMap` is able to satisfy a request for a page providing access
1.94 +to a region in a particular file, the `PageMapper` must secure exclusive
1.95 +access to that page. Otherwise, the possibility exists that the page will be
1.96 +reclaimed and recycled concurrently by another `PageMapper`. Thus, the
1.97 +`PageMapper` must request that the page be reserved by the `Pages` object
1.98 +which in turn removes the page from the `PageQueue`. Since no other party can
1.99 +now obtain the page independently, it can be issued safely.
1.100 +
1.101 +== Queuing Issued Pages ==
1.102 +
1.103 +Once a page has been issued to a client by the `Pager`, regardless of how it
1.104 +was obtained, it must be made available for future reuse. This is achieved by
1.105 +the `PageMapper` requesting the queuing of the page, with it being added to
1.106 +the end of the `PageQueue`.