diff --git a/mps/code/check.h b/mps/code/check.h index 825e15c7e48..a2450bebd9a 100644 --- a/mps/code/check.h +++ b/mps/code/check.h @@ -281,10 +281,10 @@ extern unsigned CheckLevel; /* COMPAT* -- type compatibility checking * * .check.macros: The COMPAT* macros use some C trickery to attempt to - * verify that certain types and fields are equivalent. They do not - * do a complete job. This trickery is justified by the security gained - * in knowing that matches the MPM. See also - * mail.richard.1996-08-07.09-49. [This paragraph is intended to + * verify that certain types and fields are equivalent. They do not do + * a complete job. This trickery is justified by the security gained + * in knowing that matches the MPM. See + * . [This paragraph is intended to * satisfy rule.impl.trick.] */ diff --git a/mps/code/config.h b/mps/code/config.h index c0826daa104..396fbdb5532 100644 --- a/mps/code/config.h +++ b/mps/code/config.h @@ -209,24 +209,23 @@ #include "mpstd.h" -/* Suppress Visual C warnings at warning level 4, */ -/* see mail.richard.1997-09-25.13-26 and job003715. */ -/* Essentially the same settings are done in testlib.h. */ +/* Suppress Visual C warnings at /W4 (warning level 4) */ +/* This is also done in testlib.h. */ #ifdef MPS_BUILD_MV -/* "constant conditional" (MPS_END) */ +/* "constant conditional" (provoked by MPS_END) */ #pragma warning(disable: 4127) #endif /* MPS_BUILD_MV */ -/* Suppress Pelles C warnings at warning level 2 */ +/* Suppress Pelles C warnings at /W2 (warning level 2) */ /* Some of the same settings are done in testlib.h. */ #ifdef MPS_BUILD_PC -/* "Unreachable code" (AVER, if condition is constantly true). */ +/* "Unreachable code" (provoked by AVER, if condition is constantly true). */ #pragma warn(disable: 2154) /* "Consider changing type to 'size_t' for loop variable" */ diff --git a/mps/code/ring.c b/mps/code/ring.c index 54902ec3818..2f4be5066f2 100644 --- a/mps/code/ring.c +++ b/mps/code/ring.c @@ -8,8 +8,7 @@ * .purpose: Rings are used to manage potentially unbounded collections * of things. * - * .sources: , - * item 6 of mail.richard_brooksby.1996-03-25.16-02 + * .sources: */ #include "ring.h" @@ -21,9 +20,10 @@ SRCID(ring, "$Id$"); /* RingCheck, RingCheckSingle -- check the validity of a ring node * - * RingCheck performs a consistency check on the ring node. - * RingCheckSingle performs the same check, but also checks that - * the ring node is a singleton (). + * RingCheck performs a consistency check on the ring node + * (). RingCheckSingle performs the same check, but + * also checks that the ring node is a singleton + * (). */ Bool RingCheck(Ring ring) @@ -46,12 +46,25 @@ Bool RingCheckSingle(Ring ring) return TRUE; } + +/* RingIsSingle -- return true if ring is a singleton + * + * See + */ + Bool RingIsSingle(Ring ring) { AVERT(Ring, ring); return (ring->next == ring); } + +/* RingLength -- return the number of nodes in the ring, not including + * this node + * + * See + */ + Size RingLength(Ring ring) { Size size = 0; diff --git a/mps/code/ring.h b/mps/code/ring.h index cbde6afe814..9cb915f4bf4 100644 --- a/mps/code/ring.h +++ b/mps/code/ring.h @@ -32,7 +32,7 @@ extern Bool RingCheckSingle(Ring ring); extern Bool RingIsSingle(Ring ring); extern Size RingLength(Ring ring); -/* .ring.init: */ +/* .ring.init: See */ extern void (RingInit)(Ring ring); #define RingInit(ring) \ BEGIN \ @@ -43,7 +43,7 @@ extern void (RingInit)(Ring ring); AVER(RingCheck(_ring)); \ END -/* .ring.finish: */ +/* .ring.finish: See */ extern void (RingFinish)(Ring ring); #define RingFinish(ring) \ BEGIN \ @@ -53,7 +53,7 @@ extern void (RingFinish)(Ring ring); _ring->prev = RingNONE; \ END -/* .ring.append: */ +/* .ring.append: See */ extern void (RingAppend)(Ring ring, Ring new); #define RingAppend(ring, new) \ BEGIN \ @@ -79,7 +79,7 @@ extern void (RingInsert)(Ring ring, Ring new); _ring->next = _new; \ END -/* .ring.remove: */ +/* .ring.remove: See */ extern void (RingRemove)(Ring old); #define RingRemove(old) \ BEGIN \ @@ -92,11 +92,11 @@ extern void (RingRemove)(Ring old); _old->prev = _old; \ END -/* .ring.next: */ +/* .ring.next: See */ extern Ring (RingNext)(Ring ring); #define RingNext(ring) ((ring)->next) -/* .ring.prev: */ +/* .ring.prev: See */ extern Ring (RingPrev)(Ring ring); #define RingPrev(ring) ((ring)->prev) diff --git a/mps/code/testlib.h b/mps/code/testlib.h index edeaf5eb50b..6f059abcbb9 100644 --- a/mps/code/testlib.h +++ b/mps/code/testlib.h @@ -15,24 +15,23 @@ #include "mpstd.h" -/* Suppress Visual C warnings at warning level 4, */ -/* see mail.richard.1997-09-25.13-26 and job003715. */ -/* Essentially the same settings are done in config.h. */ +/* Suppress Visual C warnings at /W4 (warning level 4) */ +/* This is also done in config.h. */ #ifdef MPS_BUILD_MV -/* "constant conditional" (MPS_END) */ +/* "constant conditional" (provoked by MPS_END) */ #pragma warning(disable: 4127) #endif /* MPS_BUILD_MV */ -/* Suppress Pelles C warnings at warning level 2 */ +/* Suppress Pelles C warnings at /W2 (warning level 2) */ /* This is also done in config.h. */ #ifdef MPS_BUILD_PC -/* "Unreachable code" (AVER, if condition is constantly true). */ +/* "Unreachable code" (provoked by AVER, if condition is constantly true). */ #pragma warn(disable: 2154) #endif /* MPS_BUILD_PC */ @@ -143,7 +142,10 @@ typedef long longest_t; #define max(a, b) (((a) > (b)) ? (a) : (b)) -/* alignUp -- align word to alignment */ +/* alignUp -- align word to alignment + * + * Note: evaluates argument a twice. + */ #define alignUp(w, a) (((w) + (a) - 1) & ~((size_t)(a) - 1)) diff --git a/mps/design/bt.txt b/mps/design/bt.txt index d83d9af6c45..415484b775c 100644 --- a/mps/design/bt.txt +++ b/mps/design/bt.txt @@ -206,11 +206,13 @@ _`.req.speed.fast`: The following operations shall be very fast: (design.mps.poolams(2)), ``PoolClassEPVM`` (design.mps.poolepvm(0)). Of these AWL and EPVM have speed requirements. For AWL the length of range to be found will be the length of a Dylan table in words. - According to mail.tony.1999-05-05.11-36(0), only + According to `mail.tony.1999-05-05.11-36`_, only objects are allocated in AWL (though not all objects are allocated in AWL), and the mean length of an object is 486 Words. No data for EPVM alas. + .. _mail.tony.1999-05-05.11-36: https://info.ravenbrook.com/project/mps/mail/1999/05/05/11-36/0.txt + _`.req.speed.fast.other.why`: We might expect mark and sweep pools to make use of Bit Tables, the MPS has general requirements to support efficient mark and sweep pools, so that imposes general speed diff --git a/mps/design/buffer.txt b/mps/design/buffer.txt index 6f5f49ac3db..9b660ce4dd1 100644 --- a/mps/design/buffer.txt +++ b/mps/design/buffer.txt @@ -48,11 +48,12 @@ the archives if you can't find what you want here. 2006-06-09. _`.source.synchronize`: For a discussion of the synchronization -issues: +issues, see `mail.richard.1995-05-19.17-10`_, +`mail.ptw.1995-05-19.19-15`_, and `mail.richard.1995-05-24.10-18`_. -* `mail.richard.1995-05-19.17-10 `_ -* `mail.ptw.1995-05-19.19-15 `_ -* `mail.richard.1995-05-24.10-18 `_ +.. _mail.richard.1995-05-19.17-10: https://info.ravenbrook.com/project/mps/mail/1995/05/19/17-10/0.txt +.. _mail.ptw.1995-05-19.19-15: https://info.ravenbrook.com/project/mps/mail/1995/05/19/19-15/0.txt +.. _mail.richard.1995-05-24.10-18: https://info.ravenbrook.com/project/mps/mail/1995/05/24/10-18/0.txt .. note:: @@ -60,33 +61,39 @@ issues: incorrect. The operations should be in the other order. DRJ. _`.source.interface`: For a description of the buffer interface in C -prototypes: +prototypes, see `mail.richard.1997-04-28.09-25`_. -* `mail.richard.1997-04-28.09-25(0) `_ +.. _mail.richard.1997-04-28.09-25: https://info.ravenbrook.com/project/mps/mail/1997/04/28/09-25/0.txt _`.source.qa`: Discussions with QA were useful in pinning down the semantics and understanding of some obscure but important boundary -cases. See the thread starting -`mail.richard.tucker.1997-05-12.09-45(0) -`_ with subject "notes on -our allocation points discussion": +cases. See the thread with subject "notes on our allocation points +discussion" and messages `mail.richard.tucker.1997-05-12.09-45`_, +`mail.ptw.1997-05-12.12-46`_, `mail.richard.1997-05-12.13-15`_, +`mail.richard.1997-05-12.13-28`_, `mail.ptw.1997-05-13.15-15`_, +`mail.sheep.1997-05-14.11-52`_, `mail.rit.1997-05-15.09-19`_, +`mail.ptw.1997-05-15.21-22`_, `mail.ptw.1997-05-15.21-35`_, +`mail.rit.1997-05-16.08-02`_, `mail.rit.1997-05-16.08-42`_, +`mail.ptw.1997-05-16.12-36`_, `mail.ptw.1997-05-16.12-47`_, +`mail.richard.1997-05-19.15-46`_, `mail.richard.1997-05-19.15-56`_, +and `mail.ptw.1997-05-20.20-47`_. -* `mail.richard.tucker.1997-05-12.09-45 `_ -* `mail.ptw.1997-05-12.12-46(1) `_ -* `mail.richard.1997-05-12.13-15 `_ -* `mail.richard.1997-05-12.13-28 `_ -* `mail.ptw.1997-05-13.15-15 `_ -* `mail.sheep.1997-05-14.11-52 `_ -* `mail.rit.1997-05-15.09-19 `_ -* `mail.ptw.1997-05-15.21-22 `_ -* `mail.ptw.1997-05-15.21-35 `_ -* `mail.rit.1997-05-16.08-02 `_ -* `mail.rit.1997-05-16.08-42 `_ -* `mail.ptw.1997-05-16.12-36 `_ -* `mail.ptw.1997-05-16.12-47 `_ -* `mail.richard.1997-05-19.15-46 `_ -* `mail.richard.1997-05-19.15-56 `_ -* `mail.ptw.1997-05-20.20-47 `_ +.. _mail.richard.tucker.1997-05-12.09-45: https://info.ravenbrook.com/project/mps/mail/1997/05/12/09-45/0.txt +.. _mail.ptw.1997-05-12.12-46: https://info.ravenbrook.com/project/mps/mail/1997/05/12/12-46/1.txt +.. _mail.richard.1997-05-12.13-15: https://info.ravenbrook.com/project/mps/mail/1997/05/12/13-15/0.txt +.. _mail.richard.1997-05-12.13-28: https://info.ravenbrook.com/project/mps/mail/1997/05/12/13-28/0.txt +.. _mail.ptw.1997-05-13.15-15: https://info.ravenbrook.com/project/mps/mail/1997/05/13/15-15/0.txt +.. _mail.sheep.1997-05-14.11-52: https://info.ravenbrook.com/project/mps/mail/1997/05/14/11-52/0.txt +.. _mail.rit.1997-05-15.09-19: https://info.ravenbrook.com/project/mps/mail/1997/05/15/09-19/0.txt +.. _mail.ptw.1997-05-15.21-22: https://info.ravenbrook.com/project/mps/mail/1997/05/15/21-22/0.txt +.. _mail.ptw.1997-05-15.21-35: https://info.ravenbrook.com/project/mps/mail/1997/05/15/21-35/0.txt +.. _mail.rit.1997-05-16.08-02: https://info.ravenbrook.com/project/mps/mail/1997/05/16/08-02/0.txt +.. _mail.rit.1997-05-16.08-42: https://info.ravenbrook.com/project/mps/mail/1997/05/16/08-42/0.txt +.. _mail.ptw.1997-05-16.12-36: https://info.ravenbrook.com/project/mps/mail/1997/05/16/12-36/0.txt +.. _mail.ptw.1997-05-16.12-47: https://info.ravenbrook.com/project/mps/mail/1997/05/16/12-47/0.txt +.. _mail.richard.1997-05-19.15-46: https://info.ravenbrook.com/project/mps/mail/1997/05/19/15-46/0.txt +.. _mail.richard.1997-05-19.15-56: https://info.ravenbrook.com/project/mps/mail/1997/05/19/15-56/0.txt +.. _mail.ptw.1997-05-20.20-47: https://info.ravenbrook.com/project/mps/mail/1997/05/20/20-47/0.txt diff --git a/mps/design/guide.hex.trans.txt b/mps/design/guide.hex.trans.txt index 06b9dd83d5d..c4b1e9594fd 100644 --- a/mps/design/guide.hex.trans.txt +++ b/mps/design/guide.hex.trans.txt @@ -22,8 +22,10 @@ hexadecimal digits. _`.readership`: This document is intended for anyone devising arbitrary constants which may appear in hex-dumps. -_`.sources`: This transliteration was supplied by RichardK in -mail.richardk.1997-04-07.13-44. +_`.sources`: This transliteration was supplied by RHSK in +`mail.richardk.1997-04-07.13-44`_. + +.. _mail.richardk.1997-04-07.13-44: https://info.ravenbrook.com/project/mps/mail/1997/04/07/13-44/0.txt Transliteration diff --git a/mps/design/interface-c.txt b/mps/design/interface-c.txt index 1585318fa28..96b20354b45 100644 --- a/mps/design/interface-c.txt +++ b/mps/design/interface-c.txt @@ -18,7 +18,9 @@ Introduction _`.scope`: This document is the design for the Memory Pool System (MPS) interface to the C Language, impl.h.mps. -_`.bg`: See mail.richard.1996-07-24.10-57. +_`.bg`: See `mail.richard.1996-07-24.10-57`_. + +.. _mail.richard.1996-07-24.10-57: https://info.ravenbrook.com/project/mps/mail/1996/07/24/10-57/0.txt Analysis @@ -194,7 +196,10 @@ can be called outside of ``ArenaEnter()`` and ``ArenaLeave()``. _`.check.types`: We use definitions of types in both our external interface and our internal code, and we want to make sure that they are compatible. (The external interface changes less often and hides -more information.) This checking uses the following macros. +more information.) This checking uses the following macros, originally +from `mail.richard.1996-08-07.09-49`_. + +.. _mail.richard.1996-08-07.09-49: https://info.ravenbrook.com/project/mps/mail/1996/08/07/09-49/0.txt ``COMPATLVALUE(lvalue1, lvalue2)`` @@ -240,7 +245,9 @@ Binary compatibility issues --------------------------- As in, "Enumeration types are not allowed" (see -mail.richard.1995-09-08.09-28). +`mail.richard.1995-09-08.09-28`_). + +.. _mail.richard.1995-09-08.09-28: https://info.ravenbrook.com/project/mps/mail/1995/09/08/09-28/0.txt _`.compat`: There are two main aspects to run-time compatibility: binary interface and protocol. diff --git a/mps/design/io.txt b/mps/design/io.txt index 0e78d19d182..655eea8caf2 100644 --- a/mps/design/io.txt +++ b/mps/design/io.txt @@ -411,9 +411,12 @@ Document History - 1996-08-30 RB_ Document created from paper notes. -- 1997-06-10 RB_ Updated with mail.richard.1997-05-30.16-13 and +- 1997-06-10 RB_ Updated with `mail.richard.1997-05-30.16-13`_ and subsequent discussion in the Pool Hall at Longstanton. (See also - mail.drj.1997-06-05.15-20.) + `mail.drj.1997-06-05.15-20`_.) + + .. _mail.richard.1997-05-30.16-13: https://info.ravenbrook.com/project/mps/mail/1997/05/30/16-13/0.txt + .. _mail.drj.1997-06-05.15-20: https://info.ravenbrook.com/project/mps/mail/1997/06/05/15-20/0.txt - 2002-06-07 RB_ Converted from MMInfo database design document. diff --git a/mps/design/locus.txt b/mps/design/locus.txt index 336f120dc74..ed328336f42 100644 --- a/mps/design/locus.txt +++ b/mps/design/locus.txt @@ -20,8 +20,14 @@ the burden of having to be clever about tract/group placement away from the pools, preserving trace differentiability and contiguity where appropriate. -_`.source`: mail.gavinm.1998-02-05.17-52(0), mail.ptw.1998-02-05.19-53(0), -mail.pekka.1998-02-09.13-58(0), and mail.gavinm.1998-02-09.14-05(0). +_`.source`: `mail.gavinm.1998-02-05.17-52`_, +`mail.ptw.1998-02-05.19-53`_, `mail.pekka.1998-02-09.13-58`_, and +`mail.gavinm.1998-02-09.14-05`_. + +.. _mail.gavinm.1998-02-05.17-52: https://info.ravenbrook.com/project/mps/mail/1998/02/05/17-52/0.txt +.. _mail.ptw.1998-02-05.19-53: https://info.ravenbrook.com/project/mps/mail/1998/02/05/19-53/0.txt +.. _mail.pekka.1998-02-09.13-58: https://info.ravenbrook.com/project/mps/mail/1998/02/09/13-58/0.txt +.. _mail.gavinm.1998-02-09.14-05: https://info.ravenbrook.com/project/mps/mail/1998/02/09/14-05/0.txt _`.readership`: Any MPS developer. @@ -37,10 +43,12 @@ The MPS manages three main resources: The locus manager manages address space at the arena level. -.. note: +.. note:: - Tucker was right: see mail.ptw.1998-11-02.14-25. Richard Kistruck, - 2007-04-24. + Tucker was right: see `mail.ptw.1998-11-02.14-25`_. Richard + Kistruck, 2007-04-24. + + .. _mail.ptw.1998-11-02.14-25: https://info.ravenbrook.com/project/mps/mail/1998/11/02/14-25/0.txt When a pool wants some address space, it expresses some preferences to the locus manager. The locus manager and the arena (working together) diff --git a/mps/design/object-debug.txt b/mps/design/object-debug.txt index 8f92a0dc021..cd85771c37a 100644 --- a/mps/design/object-debug.txt +++ b/mps/design/object-debug.txt @@ -198,11 +198,14 @@ adjust the pointer and the size for alloc and free, to put down the fenceposts during alloc, and to check them; to avoid slowing down all allocation, this would require some MOPping to make the format class affect the choice of the alloc and free methods (see -mail.pekka.1998-06-11.18-18). +`mail.pekka.1998-06-11.18-18`_). + +.. _mail.pekka.1998-06-11.18-18: https://info.ravenbrook.com/project/mps/mail/1998/06/11/18-18/0.txt _`.fence.wrapper.alloc.size`: We could just communicate the size of the fenceposts between the format and the allocation routines, but -then you couldn't use variable fenceposts (.fence.wrapper.variable). +then you couldn't use variable fenceposts +(`.fence.wrapper.variable`_). .. note:: @@ -415,7 +418,9 @@ Document History - 1998-09-10 Pekka Pirinen The first draft merely records all the various ideas about fenceposting that came up in discussions in June, July and September 1998. This includes the format wrapping - idea from mail.ptw.1998-06-19.21-13(0). + idea from `mail.ptw.1998-06-19.21-13`_. + + .. _mail.ptw.1998-06-19.21-13: https://info.ravenbrook.com/project/mps/mail/1998/06/19/21-13/0.txt - 2002-06-07 RB_ Converted from MMInfo database design document. diff --git a/mps/design/poolawl.txt b/mps/design/poolawl.txt index bbbd7469d9b..253f7c04a5f 100644 --- a/mps/design/poolawl.txt +++ b/mps/design/poolawl.txt @@ -40,7 +40,9 @@ Must satisfy request.dylan.170123_. _`.req.obj-format`: Only objects of a certain format need be supported. This format is a subset of the Dylan Object Format. The pool uses the first slot in the fixed part of an object to store an -association. See mail.drj.1997-03-11.12-05 +association. See `mail.drj.1997-03-11.12-05`_. + +.. _mail.drj.1997-03-11.12-05: https://info.ravenbrook.com/project/mps/mail/1997/03/11/12-05/0.txt Definitions diff --git a/mps/design/poolmrg.txt b/mps/design/poolmrg.txt index ad363ed15c1..9f01ad3bca7 100644 --- a/mps/design/poolmrg.txt +++ b/mps/design/poolmrg.txt @@ -518,7 +518,9 @@ Future ------ _`.future.array`: In future, for speed or simplicity, this pool could -be rewritten to use an array. See mail.gavinm.1997-09-04.13-08(0). +be rewritten to use an array. See `mail.gavinm.1997-09-04.13-08`_. + +.. _mail.gavinm.1997-09-04.13-08: https://info.ravenbrook.com/project/mps/mail/1997/09/04/13-08/0.txt Tests diff --git a/mps/design/poolmvt.txt b/mps/design/poolmvt.txt index 06806744a30..7df1fde0a6a 100644 --- a/mps/design/poolmvt.txt +++ b/mps/design/poolmvt.txt @@ -27,7 +27,9 @@ _`.source`: req.dylan(6), req.epcore(16), req.product(2) _`.background`: design.mps.poolmv(0), design.mps.poolepdl(0), design.product.soft.drop(0), paper.wil95(1), paper.vo96(0), -paper.grun92(1), paper.beck82(0), mail.ptw.1998-02-25.22-18(0) +paper.grun92(1), paper.beck82(0), `mail.ptw.1998-02-25.22-18`_. + +.. _mail.ptw.1998-02-25.22-18: https://info.ravenbrook.com/project/mps/mail/1998/02/25/22-18/0.txt Definitions @@ -817,7 +819,9 @@ freeing. Standard checking and description should be provided. collected pools, but no manual pool currently does.] _`.impl.c.future`: The implementation should not preclude "buffered -free" (mail.ptw.1997-12-05.19-07(0), ff.) being added in the future. +free" (`mail.ptw.1997-12-05.19-07`_) being added in the future. + +.. _mail.ptw.1997-12-05.19-07: https://info.ravenbrook.com/project/mps/mail/1997/12/05/19-07/0.txt _`.impl.c.parameters`: The pool parameters are calculated as follows from the input parameters: minimum, mean, and maximum size are taked @@ -959,7 +963,9 @@ proc.release.epcore(2).test) Text ---- -Possible tweaks (from mail.pekka.1998-04-15.13-10(0)): +Possible tweaks (from `mail.pekka.1998-04-15.13-10`_): + +.. _mail.pekka.1998-04-15.13-10: https://info.ravenbrook.com/project/mps/mail/1998/04/15/13-10/0.txt - Try to coalesce splinters returned from AP's with the front (or any) block on the ABQ. @@ -973,16 +979,24 @@ B. Document History ------------------- - 1998-02-04 PTW Initial e-mail discussion. See thread starting with - mail.ptw.1998-02-04.21-27(0). + `mail.ptw.1998-02-04.21-27`_. + + .. _mail.ptw.1998-02-04.21-27: https://info.ravenbrook.com/project/mps/mail/1998/02/04/21-27/0.txt - 1998-02-13 PTW Initial draft based on e-mail request for comments. - See thread starting with mail.ptw.1998-02-12.03-36. + See thread starting with `mail.ptw.1998-02-12.03-36`_. + + .. _mail.ptw.1998-02-12.03-36: https://info.ravenbrook.com/project/mps/mail/1998/02/12/03-36/0.txt - 1998-04-01 PTW Revised in response to e-mail request for comments. - See thread starting with mail.ptw.1998-03-23.20-43(0). + See thread starting with `mail.ptw.1998-03-23.20-43`_. + + .. _mail.ptw.1998-03-23.20-43: https://info.ravenbrook.com/project/mps/mail/1998/03/23/20-43/0.txt - 1998-04-15 PTW Revised in response to e-mail request for comments. - See thread starting with mail.ptw.1998-04-13.21-40(0). + See thread starting with `mail.ptw.1998-04-13.21-40`_. + + .. _mail.ptw.1998-04-13.21-40: https://info.ravenbrook.com/project/mps/mail/1998/04/13/21-40/0.txt - 1998-05-06 PTW Revised in response to review review.design.mps.poolmv2.2(0). diff --git a/mps/design/protocol.txt b/mps/design/protocol.txt index e8442d97cfe..2ae5605d4f1 100644 --- a/mps/design/protocol.txt +++ b/mps/design/protocol.txt @@ -33,8 +33,12 @@ benefits of object-oriented class inheritance to maximize code reuse, minimize code maintenance and minimize the use of boilerplate code. _`.purpose.related`: For related discussion, see -mail.tony.1998-08-28.16-26(0), mail.tony.1998-09-01.11-38(0), -mail.tony.1998-10-06.11-03(0) and other messages in the same threads. +`mail.tony.1998-08-28.16-26`_, `mail.tony.1998-09-01.11-38`_, +`mail.tony.1998-10-06.11-03`_ and other messages in the same threads. + +.. _mail.tony.1998-10-06.11-03: https://info.ravenbrook.com/project/mps/mail/1998/10/06/11-03/0.txt +.. _mail.tony.1998-09-01.11-38: https://info.ravenbrook.com/project/mps/mail/1998/09/01/11-38/0.txt +.. _mail.tony.1998-08-28.16-26: https://info.ravenbrook.com/project/mps/mail/1998/08/28/16-26/0.txt Requirements @@ -330,7 +334,9 @@ specialized methods for ``coerceClass`` and ``coerceInst`` to be written (see `.overview.coerce-class`_ and `.overview.coerce-inst`_). Documentation on support for multiple inheritance is under construction. This facility is not currently used. The basic idea is -described in mail.tony.1998-10-06.11-03(0). +described in `mail.tony.1998-10-06.11-03`_. + +.. _mail.tony.1998-10-06.11-03: https://info.ravenbrook.com/project/mps/mail/1998/10/06/11-03/0.txt Protocol guidelines diff --git a/mps/design/pthreadext.txt b/mps/design/pthreadext.txt index b72e2926d0f..aa5072f0289 100644 --- a/mps/design/pthreadext.txt +++ b/mps/design/pthreadext.txt @@ -90,9 +90,10 @@ summary, a small number of POSIX functions are defined to be restriction in signal handlers. All other POSIX functions are considered to be unsafe. Behaviour is undefined if an unsafe function is interrupted by a signal and the signal handler then proceeds to -call another unsafe function. See mail.tony.1999-08-24.15-40(0)and +call another unsafe function. See `mail.tony.1999-08-24.15-40`_ and followups for some further analysis. +.. _mail.tony.1999-08-24.15-40: https://info.ravenbrook.com/project/mps/mail/1999/08/24/15-40/0.txt .. _sigaction: http://www.opengroup.org/onlinepubs/007908799/xsh/sigaction.html _`.anal.signal.safety.implication`: Since we can't assume that we diff --git a/mps/design/ring.txt b/mps/design/ring.txt index 15256b1fa1e..c0f4d9adfd4 100644 --- a/mps/design/ring.txt +++ b/mps/design/ring.txt @@ -15,8 +15,12 @@ Ring data structure Introduction ------------ -_`.source`: rings are derived from the earlier use of Deques. See -design.mps.deque. +_`.source`: rings are derived from the earlier use of double-ended +queues (deques). RB found that most of the deque features were unused +(see item 6 of `mail.richard.1996-03-25.16-02`_) and so the simple +doubly-linked list structure of rings suffices. + +.. _mail.richard.1996-03-25.16-02: https://info.ravenbrook.com/project/mps/mail/1996/03/25/16-02/0.txt Description @@ -45,14 +49,14 @@ and deletion because the entire ring can be found from any node. In the MPS, rings are used to connect a "parent" structure (such as a ``Arena``) to a number of "child" structures (such as ``Pool``), as -shown in `.fig.ring`_. Note the slight abuse of naming convention, in -that ``barRing`` is not called ``barRingStruct``. +shown in `.fig.ring`_. -_`.fig.ring`: A ring of ``Bar`` objects owned by a ``Foo`` object. +_`.fig.ring`: A ring of ``Child`` objects owned by a ``Parent`` +object. [missing figure] -_`.fig.empty`: An empty ring of ``Bar`` objects owned by a ``Foo`` +_`.fig.empty`: An empty ring of ``Child`` objects owned by a ``Parent`` object. [missing figure] @@ -60,7 +64,7 @@ object. _`.def.singleton`: A "singleton" ring is a ring containing one node, whose previous and next nodes are itself (see `.fig.single`_). -_`.fig.single`: A singleton ``Bar`` object not on any ring. +_`.fig.single`: A singleton ``Child`` object not on any ring. [missing figure] @@ -69,8 +73,11 @@ _`.fig.elt`: How ``RING_ELT()`` gets a parent pointer from a node pointer. [missing figure] +Interface +--------- + Init / Finish -------------- +............. ``void RingInit(Ring ring)`` @@ -84,8 +91,36 @@ ring must be a singleton ring before it can be finished (it is an error to attempt to finish a non-singleton ring). +Checking +........ + +``Bool RingCheck(Ring ring)`` + +_`.check`: ``RingCheck()`` is the check function for rings. See +design.mps.check_). + +.. _design.mps.check: check + +``Bool RingCheckSingle(Ring ring)`` + +_`.check.single`: ``RingCheckSingle()`` is a check function that +additionally checks that ``ring`` is a singleton (see +`.def.singleton`_). + +``Bool RingIsSingle(Ring ring)`` + +_`.is.single`: Return ``TRUE`` if ``ring`` is a singleton (see +`.def.singleton`_). + +``Size RingLength(Ring ring)`` + +_`.length`: Return the number of elements in the ring, not counting +``ring`` itself. This therefore returns 0 for singleton rings, and for +parent-children rings it returns the number of children. + + Iteration ---------- +......... ``RING_FOR(Ring node, Ring ring, Ring next)`` @@ -112,17 +147,25 @@ iteration. _`.for.ex`: An example:: Ring node, nextNode; - RING_FOR(node, &foo->barRing, nextNode) { - Bar bar = RING_ELT(Bar, FooRing, node); - frob(bar); + RING_FOR(node, &parent->childRing, nextNode) { + Child child = RING_ELT(Child, ParentRing, node); + foo(child); } _`.for.ex.elt`: Notice the idiomatic use of ``RING_ELT()`` which is almost universal when using ``RING_FOR()``. -Subclass --------- +Element access +.............. + +``Ring RingNext(Ring ring)`` + +_`.next`: ``RingNext()`` returns the next node in the ring. + +``Ring (RingPrev)(Ring ring)`` + +_`.prev`: ``RingPrev()`` returns the previous node in the ring. ``RING_ELT(type, field, Ring node)`` @@ -137,7 +180,7 @@ result is a pointer to the enclosing structure. Append / Remove ---------------- +............... ``void RingAppend(Ring ring, Ring new)`` @@ -162,11 +205,16 @@ that joined two rings. This is not done as it is not required. Naming ------ -_`.naming`: By convention, when one structure ``Foo`` contains one -ring of ``Bar`` structures, the field in ``Foo`` is usually known as -``barRing``, and the field in ``Bar`` is known as ``fooRing``. If the -``Foo`` structure contains more than one ring of ``Bar`` structures, -then they will have names such as ``spongRing`` and ``frobRing``. +_`.naming`: By convention, when one structure ``Parent`` contains one +ring of ``Child`` structures, the field in ``Parent`` is usually known +as ``childRing``, and the field in ``Child`` is known as +``parentRing``. If the ``Parent`` structure contains more than one +ring of ``Child`` structures, then they should have names like +``allocatedChildRing`` and ``freeChildRing``. + +_`.naming.rule.break`: Note the slight abuse of naming convention, in +that the ring members have names ending in ``Ring`` rather than +``RingStruct``. Deques @@ -186,7 +234,7 @@ This section documents known defects with the current design. _`.app_for.misuse`: It is easy to pass ``RingAppend()`` and ``RING_FOR()`` the arguments in the wrong order as all the arguments -have the same type. see `.head`_. +have the same type. _`.check.improve`: There is no method for performing a full integrity check. This could be added. diff --git a/mps/design/seg.txt b/mps/design/seg.txt index ab6da3aa8c9..405eb75b52b 100644 --- a/mps/design/seg.txt +++ b/mps/design/seg.txt @@ -319,7 +319,9 @@ Document History and 1) was as part of editing MMsrc!seg.c(MMdevel_action2.1). - 1999-04-16 Tony Mann. Rewritten to separate segments and tracts, - following mail.tony.1998-11-02.10-26 + following `mail.tony.1998-11-02.10-26`_. + + .. _mail.tony.1998-11-02.10-26: https://info.ravenbrook.com/project/mps/mail/1998/11/02/10-26/0.txt - 2002-06-07 RB_ Converted from MMInfo database design document. diff --git a/mps/design/telemetry.txt b/mps/design/telemetry.txt index dc8b2619f65..08a0ae6df18 100644 --- a/mps/design/telemetry.txt +++ b/mps/design/telemetry.txt @@ -21,8 +21,11 @@ the MPS. _`.readership`: This document is intended for any MPS developer. _`.source`: Various meetings and brainstorms, including -meeting.general.1997-03-04(0), mail.richard.1997-07-03.17-01(0), -mail.gavinm.1997-05-01.12-40(0). +meeting.general.1997-03-04(0), `mail.richard.1997-07-03.17-01`_, +`mail.gavinm.1997-05-01.12-40`_. + +.. _mail.gavinm.1997-05-01.12-40: https://info.ravenbrook.com/project/mps/mail/1997/05/01/12-40/0.txt +.. _mail.richard.1997-07-03.17-01: https://info.ravenbrook.com/project/mps/mail/1997/07/03/17-01/0.txt Overview diff --git a/mps/design/trace.txt b/mps/design/trace.txt index f1d25bf25bc..349a64bfce8 100644 --- a/mps/design/trace.txt +++ b/mps/design/trace.txt @@ -38,7 +38,9 @@ traces. This limitation is expressed in the symbol ``TraceLIMIT``. .. _request.mps.160020: https://info.ravenbrook.com/project/mps/import/2001-11-05/mmprevol/request/mps/160020 -_`.rate`: See `mail.nickb.1997-07-31.14-37 `_. +_`.rate`: See `mail.nickb.1997-07-31.14-37`_. + +.. _mail.nickb.1997-07-31.14-37: https://info.ravenbrook.com/project/mps/mail/1997/07/31/14-37/0.txt .. note:: @@ -60,7 +62,7 @@ that this is the case in ``TraceFix()``. need to adjust our strategy here. See `mail.dsm.1996-02-14.18-18`_ for a strategy of coping gracefully with ``PoolDestroy()``. -.. _mail.dsm.1996-02-14.18-18: https://info.ravenbrook.com/project/mps/mail/1996/02/14/18-18/0.txt + .. _mail.dsm.1996-02-14.18-18: https://info.ravenbrook.com/project/mps/mail/1996/02/14/18-18/0.txt _`.fix.fixed.all`: ``ss->fixedSummary`` is accumulated (in ``TraceFix()``) for all pointers, whether or not they are genuine