MPS issue job003327

TitlePurpose of reservoirs is unclear
Statusclosed
Prioritynice
Assigned userRichard Brooksby
OrganizationRavenbrook
DescriptionThe external interface to the MPS contains these symbols that directly refer to the "reservoir":

mps_ap_fill_with_reservoir_permit
mps_reservoir_limit_set
mps_reservoir_limit
mps_reservoir_available
mps_reserve_with_reservoir_permit
MPS_RESERVE_WITH_RESERVOIR_PERMIT_BLOCK

In addition, the documentation for these symbols refers to the reservoir:

mps_sac_alloc [1]
MPS_SAC_ALLOC_FAST [2]

I cannot document these symbols without understanding the purpose of the reservoir. There's a design document [3] but this just says, "The low-memory reservoir provides client support for implementing handlers for low-memory situations which allocate" which isn't clear enough to turn into user documentation.
AnalysisRB dislikes the reservoir design (it causes a proliferation of "reservoir" versions of symbols in the code), so maybe the best thing to do is to deprecate the thing and start again? Needs thought, anyway.

GDR: for the moment I've not documented any of the symbols with "reservoir" in their names, and for mps_sac_alloc I've just said to pass false for the "has_reservoir_permit" argument.
How foundinspection
Evidence[1] <https://info.ravenbrook.com/project/mps/master/manual/reference/#mps_sac_alloc>
[2] <https://info.ravenbrook.com/project/mp...er/manual/reference/#MPS_SAC_ALLOC_FAST>
[3] <https://info.ravenbrook.com/project/mps/master/design/reservoir/>
Observed in1.110.0
Created byGareth Rees
Created on2012-10-19 14:13:08
Last modified byRichard Brooksby
Last modified on2016-03-15 13:22:57
History2012-10-19 GDR Created.

Fixes

Change Effect Date User Description
190106 closed 2016-03-15 13:19:27 Richard Brooksby Merging branch mps/branch/2016-03-13/without-reservation into master sources.