MPS issue job003485

TitleInformation about cause of errors is lost
Assigned userGareth Rees
DescriptionWhen you call an MPS function and it fails, you get a result code back, perhaps MPS_RES_PARAM. But what does that mean? You might have many parameters and want to know which one was wrong. The MPS generally knows quite a lot about the cause of an error when it happens, but when it gets converted to an error code this information is lost.

This also makes it harder to diagnose failures in the test suite: see for example job003561.

Example 1. If you pass a pool_debug_options structure to a debugging pool class, but the size of the fencepost and splat patterns are not multiples of the pool alignment, you get a MPS_RES_PARAM but no explanation.
AnalysisCould have an errno/strerror-like interface. But it would have to be thread-safe.

On the other hand, there are in fact only 5 places where ResPARAM or MPS_RES_PARAM is returned (and only 3 of them are in documented functions), so maybe we could just turn them all into assertions?

dbgpool.c:158 -- fencepost pattern size not multiple of pool alignment
dbgpool.c:176 -- splat pattern size not multiple of pool alignment
arenavm.c:1771 -- desired increment too small [note: undocumented function; see job003448]
freelist.c:157 -- alignment not big enough to store a pointer [note: no public interface to get here]
poolams.c:807 -- generation chain has wrong number of generations

See also job001159 (lack of information from AVER with multiple conditions). These have crept back in, but probably we want an AVER_BETWEEN.

The distinction between assertion and ResPARAM is subtle, possibly undocumented, and possibly not useful. Most parameter errors are static programming errors, where the calling program contains a mistake. These can be caught by assertion. But some parameter errors might depend on dynamic conditions and need to be legitimately detected at run-time by the calling program. It's not statically wrong to pass the parameter, but it's illegal for some dynamic reason. (c.f. EINVAL) That's what ResPARAM is for. The cases above seem to be confused about this, and should be corrected. RB 2014-02-19

GDR 2014-04-10: Four of the five cases have now gone away: the dbgpool pattern size requirements were removed (change 185379); creating a freelist with a too-small alignment is a static programming error, not a dynamic failure condition (change 185426); and the restriction on the generation chain for AMS was removed (change 184229). This leaves just one use of ResPARAM in the source code!
How foundinspection
Observed in1.111.0
Created byGareth Rees
Created on2013-05-16 15:08:30
Last modified byGareth Rees
Last modified on2014-09-26 21:55:05
History2013-05-16 GDR Created.


Change Effect Date User Description
187057 closed 2014-09-26 21:55:05 Gareth Rees Don't return ResPARAM from mps_arena_vm_growth if desired < minimum: this is a static programming error (not a dynamic condition) so AVER instead.
185426 open 2014-04-10 13:02:22 Gareth Rees Trying to create a Freelist with too-small alignment is a static programming error, not a dynamic failure condition, so AVER instead of returning ResPARAM. (See job003485).
185379 open 2014-04-09 13:00:52 Gareth Rees Make debugging pool implementation more flexible -- there's no longer a requirement for fenceSize to be a multiple of the pool alignment, nor for freeSize to be a divisor of the pool alignment. This makes it easy to write simple and portable debug options structures without having to mess about with MPS_PF_ALIGN.
184229 open 2014-01-30 13:21:45 Richard Brooksby The AMS pool no longer requires a chain argument, but defaults to the arena default chain.
Chains passed to the AMS pool are no longer required to contain a single generation, though the AMS will only use the first generation by default.

Imported from Git
 Author: Richard Brooksby <> 1391088105 +0000
 Committer: Richard Brooksby <> 1391088105 +0000
 sha1: c802cffdee69a846a5180ce23c66738ec9371fa8