From 997524703ddf347415142f750e92e5b8bb5e2058 Mon Sep 17 00:00:00 2001 From: Richard Brooksby Date: Tue, 18 Jun 2002 16:41:00 +0100 Subject: [PATCH 01/11] Branching mps for version 1.100. Copied from Perforce Change: 30259 ServerID: perforce.ravenbrook.com From 8356d2cae767b04b5b35f03d08fa34b36e744c7b Mon Sep 17 00:00:00 2001 From: Richard Brooksby Date: Tue, 18 Jun 2002 16:56:18 +0100 Subject: [PATCH 02/11] Updating version 1.100 documents to say version 1.100 not master. Copied from Perforce Change: 30260 ServerID: perforce.ravenbrook.com --- mps/design/alloc-frame/index.html | 8 ++++---- mps/design/arena/index.html | 8 ++++---- mps/design/arenavm/index.html | 8 ++++---- mps/design/bt/index.html | 8 ++++---- mps/design/buffer/index.html | 8 ++++---- mps/design/cbs/index.html | 8 ++++---- mps/design/check/index.html | 8 ++++---- mps/design/class-interface/index.html | 8 ++++---- mps/design/collection/index.html | 8 ++++---- mps/design/config/index.html | 8 ++++---- mps/design/finalize/index.html | 8 ++++---- mps/design/index.html | 4 ++-- mps/design/interface-c/index.html | 8 ++++---- mps/design/io/index.html | 8 ++++---- mps/design/lib/index.html | 8 ++++---- mps/design/lock/index.html | 8 ++++---- mps/design/locus/index.html | 8 ++++---- mps/design/message/index.html | 8 ++++---- mps/design/pool/index.html | 8 ++++---- mps/design/poolamc/index.html | 8 ++++---- mps/design/poolams/index.html | 8 ++++---- mps/design/poolawl/index.html | 8 ++++---- mps/design/poollo/index.html | 8 ++++---- mps/design/poolmfs/index.html | 8 ++++---- mps/design/poolmrg/index.html | 8 ++++---- mps/design/poolmv/index.html | 8 ++++---- mps/design/poolmvff/index.html | 8 ++++---- mps/design/poolmvt/index.html | 8 ++++---- mps/design/prot/index.html | 8 ++++---- mps/design/protan/index.html | 8 ++++---- mps/design/protli/index.html | 8 ++++---- mps/design/protocol/index.html | 8 ++++---- mps/design/protsu/index.html | 8 ++++---- mps/design/pthreadext/index.html | 8 ++++---- mps/design/reservoir/index.html | 8 ++++---- mps/design/ring/index.html | 8 ++++---- mps/design/root/index.html | 8 ++++---- mps/design/scan/index.html | 8 ++++---- mps/design/seg/index.html | 8 ++++---- mps/design/sig/index.html | 8 ++++---- mps/design/splay/index.html | 8 ++++---- mps/design/sso1al/index.html | 8 ++++---- mps/design/telemetry/index.html | 8 ++++---- mps/design/trace/index.html | 8 ++++---- mps/design/type/index.html | 8 ++++---- mps/design/version-library/index.html | 8 ++++---- mps/design/version/index.html | 8 ++++---- mps/design/vm/index.html | 8 ++++---- mps/design/vman/index.html | 8 ++++---- mps/design/vmo1/index.html | 8 ++++---- mps/design/vmso/index.html | 8 ++++---- mps/design/writef/index.html | 8 ++++---- mps/index.html | 12 ++++++------ mps/manual/index.html | 4 ++-- mps/manual/reference/index.html | 8 ++++---- mps/procedure/index.html | 4 ++-- mps/procedure/release-build/index.html | 8 ++++---- mps/tool/index.html | 4 ++-- 58 files changed, 226 insertions(+), 226 deletions(-) diff --git a/mps/design/alloc-frame/index.html b/mps/design/alloc-frame/index.html index 76b9cb07ba8..27c4a22ac78 100644 --- a/mps/design/alloc-frame/index.html +++ b/mps/design/alloc-frame/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -506,8 +506,8 @@ following operations: Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/arena/index.html b/mps/design/arena/index.html index ae35b79d48f..b3e42ade94d 100644 --- a/mps/design/arena/index.html +++ b/mps/design/arena/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -548,8 +548,8 @@ an incremental serial which is the serial of the next root. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/arenavm/index.html b/mps/design/arenavm/index.html index b9848e904a3..3f60f42fd93 100644 --- a/mps/design/arenavm/index.html +++ b/mps/design/arenavm/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -269,8 +269,8 @@ ATTACHMENT Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/bt/index.html b/mps/design/bt/index.html index abb5daf9d18..b4b9029e020 100644 --- a/mps/design/bt/index.html +++ b/mps/design/bt/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -712,8 +712,8 @@ extensively. See change.mps.epcore.brisling.160181 TEST1 and TEST2. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/buffer/index.html b/mps/design/buffer/index.html index 5186a8e9bc4..3b11a4c6992 100644 --- a/mps/design/buffer/index.html +++ b/mps/design/buffer/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -801,8 +801,8 @@ Buffer States (richardized) Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/cbs/index.html b/mps/design/cbs/index.html index cf6643e1e98..c50ca86ab89 100644 --- a/mps/design/cbs/index.html +++ b/mps/design/cbs/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -661,8 +661,8 @@ methods (for sub-module internal use): Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/check/index.html b/mps/design/check/index.html index bfdb4c69678..58dad028720 100644 --- a/mps/design/check/index.html +++ b/mps/design/check/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -171,8 +171,8 @@ Thing is not a fully fledged type (.full-type). Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/class-interface/index.html b/mps/design/class-interface/index.html index c8b45805d51..899359146fe 100644 --- a/mps/design/class-interface/index.html +++ b/mps/design/class-interface/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -300,8 +300,8 @@ allow an unaligned size to be passed. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/collection/index.html b/mps/design/collection/index.html index eecfb2eb504..c858a94954b 100644 --- a/mps/design/collection/index.html +++ b/mps/design/collection/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -389,8 +389,8 @@ Software barriers Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/config/index.html b/mps/design/config/index.html index 4128b2cd4c0..2c635f22991 100644 --- a/mps/design/config/index.html +++ b/mps/design/config/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -535,8 +535,8 @@ To do: Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/finalize/index.html b/mps/design/finalize/index.html index 0322ed35b8b..eefb626d13b 100644 --- a/mps/design/finalize/index.html +++ b/mps/design/finalize/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -202,8 +202,8 @@ Pekka 1997-12-09] Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/index.html b/mps/design/index.html index 2c87ce1d267..6b6dfb68d08 100644 --- a/mps/design/index.html +++ b/mps/design/index.html @@ -18,7 +18,7 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources +Version 1.100 Sources

Memory Pool System Project

@@ -543,7 +543,7 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources +Version 1.100 Sources

diff --git a/mps/design/interface-c/index.html b/mps/design/interface-c/index.html index 4e343846090..6726f6788da 100644 --- a/mps/design/interface-c/index.html +++ b/mps/design/interface-c/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -365,8 +365,8 @@ where necessary. Only exceptions are noted in comments. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/io/index.html b/mps/design/io/index.html index 39f86b3bc95..88e9276c955 100644 --- a/mps/design/io/index.html +++ b/mps/design/io/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -483,8 +483,8 @@ ATTACHMENTS Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/lib/index.html b/mps/design/lib/index.html index 53501c8416b..627b3aceec4 100644 --- a/mps/design/lib/index.html +++ b/mps/design/lib/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -192,8 +192,8 @@ ATTACHMENT Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/lock/index.html b/mps/design/lock/index.html index 012be68703a..67b98a1c2ed 100644 --- a/mps/design/lock/index.html +++ b/mps/design/lock/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -245,8 +245,8 @@ EDEADLK (indicating a recursive claim). Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/locus/index.html b/mps/design/locus/index.html index 9b2df67dbda..dd567b58f6d 100644 --- a/mps/design/locus/index.html +++ b/mps/design/locus/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -537,8 +537,8 @@ that PoolDestroy won't have to be used for that purpose. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/message/index.html b/mps/design/message/index.html index 5e0aba889af..bf85a7ec194 100644 --- a/mps/design/message/index.html +++ b/mps/design/message/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -465,8 +465,8 @@ del - frees both the link part and the reference part of the guardian. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/pool/index.html b/mps/design/pool/index.html index 0d13918b02a..216886d0bcf 100644 --- a/mps/design/pool/index.html +++ b/mps/design/pool/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -146,8 +146,8 @@ See also design.mps.poolclass Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/poolamc/index.html b/mps/design/poolamc/index.html index 829194ee6fa..df9f06aff4c 100644 --- a/mps/design/poolamc/index.html +++ b/mps/design/poolamc/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -548,8 +548,8 @@ Group Scanning Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/poolams/index.html b/mps/design/poolams/index.html index 1135a1262c7..dd5d34f70c5 100644 --- a/mps/design/poolams/index.html +++ b/mps/design/poolams/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -485,8 +485,8 @@ current tracer interface. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/poolawl/index.html b/mps/design/poolawl/index.html index 78078d0ec0a..def64d78255 100644 --- a/mps/design/poolawl/index.html +++ b/mps/design/poolawl/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -566,8 +566,8 @@ buffers and pools and exit Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/poollo/index.html b/mps/design/poollo/index.html index 5c7558c9fb4..87f51ac88f5 100644 --- a/mps/design/poollo/index.html +++ b/mps/design/poollo/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -302,8 +302,8 @@ ATTACHMENT Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/poolmfs/index.html b/mps/design/poolmfs/index.html index 94d7a6eb1be..47e053bd8f2 100644 --- a/mps/design/poolmfs/index.html +++ b/mps/design/poolmfs/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -118,8 +118,8 @@ object that an instance can manage is declared when the instance is created. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/poolmrg/index.html b/mps/design/poolmrg/index.html index 43f539a2670..cc6b3ac20e8 100644 --- a/mps/design/poolmrg/index.html +++ b/mps/design/poolmrg/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -617,8 +617,8 @@ sometimes get delayed. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/poolmv/index.html b/mps/design/poolmv/index.html index 6c3f4b61a10..394ca92a3db 100644 --- a/mps/design/poolmv/index.html +++ b/mps/design/poolmv/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -114,8 +114,8 @@ being freed) and the call to allocate the block fails. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/poolmvff/index.html b/mps/design/poolmvff/index.html index b707c1a1a25..56c32ea55da 100644 --- a/mps/design/poolmvff/index.html +++ b/mps/design/poolmvff/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -208,8 +208,8 @@ request.mps.170186. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/poolmvt/index.html b/mps/design/poolmvt/index.html index 58fcf1c0525..070cc4fce5a 100644 --- a/mps/design/poolmvt/index.html +++ b/mps/design/poolmvt/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -862,8 +862,8 @@ to recently allocated blocks. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/prot/index.html b/mps/design/prot/index.html index fc9a1984091..bd39a6dd23b 100644 --- a/mps/design/prot/index.html +++ b/mps/design/prot/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -187,8 +187,8 @@ instruction which was causing the fault to be executed. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/protan/index.html b/mps/design/protan/index.html index 2f52c6779a6..1c8bb3ec557 100644 --- a/mps/design/protan/index.html +++ b/mps/design/protan/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -169,8 +169,8 @@ PoolAccess. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/protli/index.html b/mps/design/protli/index.html index fc59bc7a0af..494288035dc 100644 --- a/mps/design/protli/index.html +++ b/mps/design/protli/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -257,8 +257,8 @@ Separate signal stacks apparantly don't work properly with Pthreads. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/protocol/index.html b/mps/design/protocol/index.html index 42c663051e6..ce08f8c8967 100644 --- a/mps/design/protocol/index.html +++ b/mps/design/protocol/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -543,8 +543,8 @@ module -- see design.mps.lock(0). Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/protsu/index.html b/mps/design/protsu/index.html index 3260f55e903..681b9ce99d3 100644 --- a/mps/design/protsu/index.html +++ b/mps/design/protsu/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -207,8 +207,8 @@ faults. (Contrast this with Win32 Structured Exception Handling.) Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/pthreadext/index.html b/mps/design/pthreadext/index.html index f7c6e18c152..1dd009ea0dd 100644 --- a/mps/design/pthreadext/index.html +++ b/mps/design/pthreadext/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -376,8 +376,8 @@ ATTACHMENTS Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/reservoir/index.html b/mps/design/reservoir/index.html index 039fb17e082..37a0e7a39a8 100644 --- a/mps/design/reservoir/index.html +++ b/mps/design/reservoir/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -197,8 +197,8 @@ stored in the TractP fields of each tract object. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/ring/index.html b/mps/design/ring/index.html index e9be32e45d3..5360b98511f 100644 --- a/mps/design/ring/index.html +++ b/mps/design/ring/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -256,8 +256,8 @@ ATTACHMENT Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/root/index.html b/mps/design/root/index.html index 7d29c67fc71..92a82c896de 100644 --- a/mps/design/root/index.html +++ b/mps/design/root/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -167,8 +167,8 @@ some more notes about root methods in meeting.qa.1996-10-16.] Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/scan/index.html b/mps/design/scan/index.html index 49a0f6a3b13..04ae17278ca 100644 --- a/mps/design/scan/index.html +++ b/mps/design/scan/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -178,8 +178,8 @@ summary to RefSetUNIV. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/seg/index.html b/mps/design/seg/index.html index 828e8f0282d..f0da925bf92 100644 --- a/mps/design/seg/index.html +++ b/mps/design/seg/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -375,8 +375,8 @@ varieties. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/sig/index.html b/mps/design/sig/index.html index 31fc7f8c005..624e901ab79 100644 --- a/mps/design/sig/index.html +++ b/mps/design/sig/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -130,8 +130,8 @@ transliteration of "SIG". Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/splay/index.html b/mps/design/splay/index.html index c28c008614f..86539ff5318 100644 --- a/mps/design/splay/index.html +++ b/mps/design/splay/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -894,8 +894,8 @@ reverse them. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/sso1al/index.html b/mps/design/sso1al/index.html index fe4f57073cc..de9c6666f00 100644 --- a/mps/design/sso1al/index.html +++ b/mps/design/sso1al/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -192,8 +192,8 @@ return value for StackScan. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/telemetry/index.html b/mps/design/telemetry/index.html index 6e39c54ccc5..8681cf8cc36 100644 --- a/mps/design/telemetry/index.html +++ b/mps/design/telemetry/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -454,8 +454,8 @@ TEXT: Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/trace/index.html b/mps/design/trace/index.html index 1b8e8b4ecde..b91f4660e97 100644 --- a/mps/design/trace/index.html +++ b/mps/design/trace/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -197,8 +197,8 @@ improvement [insert actual speed improvement here]. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/type/index.html b/mps/design/type/index.html index 317c9e89e5e..627a478c937 100644 --- a/mps/design/type/index.html +++ b/mps/design/type/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -499,8 +499,8 @@ functions such as PointerAdd. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/version-library/index.html b/mps/design/version-library/index.html index 07cef14472e..c82f633e86d 100644 --- a/mps/design/version-library/index.html +++ b/mps/design/version-library/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -192,8 +192,8 @@ checkpoint is made. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/version/index.html b/mps/design/version/index.html index dde2b7b733a..23b6b48f2e1 100644 --- a/mps/design/version/index.html +++ b/mps/design/version/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -125,8 +125,8 @@ others. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/vm/index.html b/mps/design/vm/index.html index a8efaaff505..a8a046d8886 100644 --- a/mps/design/vm/index.html +++ b/mps/design/vm/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -197,8 +197,8 @@ for ideas on how to test this. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/vman/index.html b/mps/design/vman/index.html index 40607f110aa..3cc11af6fb6 100644 --- a/mps/design/vman/index.html +++ b/mps/design/vman/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -116,8 +116,8 @@ vm->block is the pointer returned by malloc (used when during VMDestroy). Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/vmo1/index.html b/mps/design/vmo1/index.html index cfa2a88b8ee..4d81c498fbe 100644 --- a/mps/design/vmo1/index.html +++ b/mps/design/vmo1/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -136,8 +136,8 @@ can't create a new file reference. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/vmso/index.html b/mps/design/vmso/index.html index 3faf7d6146c..e8d66816271 100644 --- a/mps/design/vmso/index.html +++ b/mps/design/vmso/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -199,8 +199,8 @@ gets reused. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/design/writef/index.html b/mps/design/writef/index.html index 9366257e668..13ed1a91b75 100644 --- a/mps/design/writef/index.html +++ b/mps/design/writef/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

Memory Pool System Project

@@ -190,8 +190,8 @@ be extended to include function name lookup. Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Design Documents +Version 1.100 Sources / +Design Documents

diff --git a/mps/index.html b/mps/index.html index 1747977c13c..57fce142f1b 100644 --- a/mps/index.html +++ b/mps/index.html @@ -6,7 +6,7 @@ -Master Product Sources +Version 1.100 Sources @@ -25,7 +25,7 @@
-

Master Product Sources

+

Version 1.100 Sources

MPS Staff, @@ -38,13 +38,13 @@

1. Introduction

-

This document catalogues the master sources for the Memory Pool +

This document catalogues the version 1.100 sources for the Memory Pool System project. (See [RB 1999-05-20, 8] for a discussion of master sources, versions, and releases.)

-

This document will be modified as the master sources are +

This document will be modified as the version 1.100 sources are developed.

The readership of this document is the project developers, and also @@ -53,9 +53,9 @@ anyone interested in the project.

This document is not confidential.

-

2. Master sources

+

2. Product sources

-

The master sources are everything which is used to construct the +

The product sources are everything which is used to construct the product and everything which is developed as the product develops, and must therefore be branched and maintained in product versions.

diff --git a/mps/manual/index.html b/mps/manual/index.html index 440d2ef4b2e..ea60c29d0c4 100644 --- a/mps/manual/index.html +++ b/mps/manual/index.html @@ -18,7 +18,7 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources +Version 1.100 Sources

Memory Pool System Project

@@ -134,7 +134,7 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources +Version 1.100 Sources

diff --git a/mps/manual/reference/index.html b/mps/manual/reference/index.html index 9c041aee24e..42e597aef26 100644 --- a/mps/manual/reference/index.html +++ b/mps/manual/reference/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Product Manuals +Version 1.100 Sources / +Product Manuals

Memory Pool System Project

@@ -9566,8 +9566,8 @@ void InitThread(ThreadLocals *thr) Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Product Manuals +Version 1.100 Sources / +Product Manuals

diff --git a/mps/procedure/index.html b/mps/procedure/index.html index 1c88b5a5ebf..fa7e1dd6ffe 100644 --- a/mps/procedure/index.html +++ b/mps/procedure/index.html @@ -18,7 +18,7 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources +Version 1.100 Sources

Memory Pool System Project

@@ -112,7 +112,7 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources +Version 1.100 Sources

diff --git a/mps/procedure/release-build/index.html b/mps/procedure/release-build/index.html index 05238cb41a7..bd36a95bcff 100644 --- a/mps/procedure/release-build/index.html +++ b/mps/procedure/release-build/index.html @@ -18,8 +18,8 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Procedures +Version 1.100 Sources / +Procedures

Memory Pool System Project

@@ -225,8 +225,8 @@ href="mailto:mps-staff@ravenbrook.com">mps-staff@ravenbrook.com.

Ravenbrook / Projects / Memory Pool System / -Master Product Sources / -Procedures +Version 1.100 Sources / +Procedures

diff --git a/mps/tool/index.html b/mps/tool/index.html index f6f2b22ece8..e1d232518c6 100644 --- a/mps/tool/index.html +++ b/mps/tool/index.html @@ -18,7 +18,7 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources +Version 1.100 Sources

Memory Pool System Project

@@ -102,7 +102,7 @@ Ravenbrook / Projects / Memory Pool System / -Master Product Sources +Version 1.100 Sources

From ba680615003e39f08b06c4dd85e4e1b84c525f74 Mon Sep 17 00:00:00 2001 From: Nick Barnes Date: Wed, 19 Jun 2002 14:34:51 +0100 Subject: [PATCH 03/11] Improved release build procedure and readme based on experience of release 1.100.0. Copied from Perforce Change: 30301 ServerID: perforce.ravenbrook.com --- mps/procedure/release-build/index.html | 36 +++++++++++++++++++++----- mps/readme.txt | 6 +++-- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/mps/procedure/release-build/index.html b/mps/procedure/release-build/index.html index bd36a95bcff..71da8901181 100644 --- a/mps/procedure/release-build/index.html +++ b/mps/procedure/release-build/index.html @@ -97,24 +97,38 @@ change to get it.

  • -

    Create a tarball containing the MPS sources:

    +

    Create a tarball containing the MPS sources, and open it for add:

    cp -r version/VERSION mps-kit-RELEASE
    + mkdir -p release/RELEASE
    tar cf - mps-kit-RELEASE | gzip -c > release/RELEASE/mps-kit-RELEASE.tar.gz
    - rm -r mps-kit-RELEASE + rm -r mps-kit-RELEASE
    + p4 add release/RELEASE/mps-kit-RELEASE.tar.gz
    • -

  • Add the tarball to Perforce with the comment "Adding the MPS Kit tarball for release RELEASE."

    • +
  • + +

    Add the readme.txt file to the release directory:

    + +
    + p4 integrate version/VERSION/readme.txt release/RELEASE/readme.txt +
    + +
    • + +

  • Submit the tarball and the readme.txt file to Perforce with +the comment "Adding the MPS Kit tarball and readme.txt file for +release RELEASE."

    • 2.3. MPS Kit Zip file

    -

    On a Window box:

    +

    On a Microsoft Windows box:

      @@ -122,9 +136,9 @@ change to get it.

    1. Launch WinZip and create a new archive called "mps-kit-RELEASE.zip" in the directory "release/RELEASE". Add the MPS sources by selecting "version/VERSION" and turning on "Include subfolders" option.

      2. -

    2. Make a self-extracting archive called "mps-kit-RELEASE.exe" from "mps-kit-RELEASE.zip" (in the same directory), by selcting Actions → Make .EXE File. Specify the default "unzip to" folder as "mps-kit-RELEASE".

      3. +

    3. Make a self-extracting archive called "mps-kit-RELEASE.exe" from "mps-kit-RELEASE.zip" (in the same directory), by selcting Actions → Make .EXE File.

      4. -

    4. Add the self-extracting archive to Perforce with the comment "Adding the MPS Kit zip file for release RELEASE."

      5. +

    5. Add the self-extracting archive and the zip file to Perforce with the comment "Adding the MPS Kit zip file for release RELEASE."

    @@ -193,6 +207,16 @@ href="mailto:mps-staff@ravenbrook.com">mps-staff@ravenbrook.com.

    + + + 2002-06-19 + + NB + + Fixed up based on experience of release 1.100.0. + + + diff --git a/mps/readme.txt b/mps/readme.txt index 49c58a74ceb..21ed02f542b 100644 --- a/mps/readme.txt +++ b/mps/readme.txt @@ -53,8 +53,9 @@ This document is not confidential. The MPS Kit is a complete set of sources and documentation to enable third parties to use, modify, and adapt the MPS. -For Windows, the kit is distributed as the ZIP archive -"mps-kit-1.100.0.zip". Unpack it using WinZip. +For Windows, the kit is distributed as the self-extracting archive +"mps-kit-1.100.0.exe", and also as the ZIP archive +"mps-kit-1.100.0.zip", which may be unpacked using WinZip. For Unix and Mac OS X, the integration kit is distributed as the tarball "mps-kit-1.100.0.tar.gz". Unpack it using the command "gunzip -c @@ -250,6 +251,7 @@ B. DOCUMENT HISTORY 2002-05-20 RB Created based on template from P4DTI project. 2002-06-18 NB Minor updates and corrections. 2002-06-18 RB Removed obsolete requirement for MASM. +2002-06-19 NB Added note on self-extracting archive C. COPYRIGHT AND LICENSE From fbab213798fc5d82bd1494ef9a305d4a6c6478c4 Mon Sep 17 00:00:00 2001 From: Nick Barnes Date: Thu, 20 Jun 2002 15:46:41 +0100 Subject: [PATCH 04/11] New design/poolams from pekka, and a bunch of proof-reading on the reference manual. Copied from Perforce Change: 30339 ServerID: perforce.ravenbrook.com --- mps/design/poolams/index.html | 558 +-- mps/manual/reference/index.html | 7659 +++++++++++++++++-------------- 2 files changed, 4635 insertions(+), 3582 deletions(-) diff --git a/mps/design/poolams/index.html b/mps/design/poolams/index.html index dd5d34f70c5..33f343ae139 100644 --- a/mps/design/poolams/index.html +++ b/mps/design/poolams/index.html @@ -32,385 +32,413 @@ THE DESIGN OF THE AUTOMATIC MARK-AND-SWEEP POOL CLASS design.mps.poolams draft design - nickb 1997-08-14 + pekka 1997-08-14 -INTRODUCTION: +INTRODUCTION -This is the design of the AMS pool class. +.intro: This is the design of the AMS pool class. .readership: MM developers. -.source: design.mps.buffer, design.mps.trace, design.mps.scan, -design.mps.action and design.mps.class-interface [none of these were actually -used -- pekka 1998-04-21]. No requirements doc [we need a req.mps that -captures the commonalities between the products -- pekka 1998-01-27]. +.source: design.mps.buffer, design.mps.trace, design.mps.scan, +design.mps.action and design.mps.class-interface [none of these were +actually used -- pekka 1998-04-21]. No requirements doc [we need a +req.mps that captures the commonalities between the products -- pekka +1998-01-27]. Document History -.hist.0: Nick Barnes wrote down some notes on the implementation 1997-08-14. -Pekka P. Pirinen wrote the first draft design 1998-01-27. +.hist.0: Nick Barnes wrote down some notes on the implementation +1997-08-14. Pekka P. Pirinen wrote the first draft design 1998-01-27. -.hist.1: Pekka edited on the basis of review.design.mps.poolams.0, and -redesigned the colour representation (results mostly in +.hist.1: Pekka edited on the basis of review.design.mps.poolams.0, and +redesigned the colour representation (results mostly in analysis.non-moving-colour(0)). -.hist.2: Described subclassing and allocation policy. pekka 1999-01-04 +.hist.2: Described subclassing and allocation policy. pekka +1999-01-04 + +.hist.3: New colour encoding scheme. pekka 2002-01-11 +OVERVIEW -OVERVIEW: - -This document describes the design of the AMS pool class. The AMS pool is a -proof-of-concept design for a mark-sweep pool in the MPS. It's not meant to be -efficient, but it could serve as a model for an implementation of a more -advanced pool (such as EPVM). +.overview: This document describes the design of the AMS pool class. +The AMS pool is a proof-of-concept design for a mark-sweep pool in the +MPS. It's not meant to be efficient, but it could serve as a model +for an implementation of a more advanced pool (such as EPVM). -REQUIREMENTS: +REQUIREMENTS .req.mark-sweep: The pool must use a mark-and-sweep GC algorithm. -.req.colour: The colour representation should be as efficient as possible. +.req.colour: The colour representation should be as efficient as +possible. .req.incremental: The pool must support incremental GC. -.req.ambiguous: The pool must support ambiguous references to objects in it -(but ambiguous references into the middle of an object do not preserve the -object). +.req.ambiguous: The pool must support ambiguous references to objects +in it (but ambiguous references into the middle of an object do not +preserve the object). .req.format: The pool must be formatted, for generality. -.req.correct: The design and the implementation should be simple enough to be -seen to be correct. +.req.correct: The design and the implementation should be simple +enough to be seen to be correct. -.req.simple: Features not related to mark-and-sweep GC should initially be -implemented as simply as possible, in order to save development effort. +.req.simple: Features not related to mark-and-sweep GC should +initially be implemented as simply as possible, in order to save +development effort. -.not-req.grey: We haven't figured out how buffers ought to work with a grey -mutator, so we use .req.correct to allow us to design a pool that doesn't work -in that phase. This is acceptable as long as we haven't actually implemented -grey mutator collection. +.not-req.grey: We haven't figured out how buffers ought to work with a +grey mutator, so we use .req.correct to allow us to design a pool that +doesn't work in that phase. This is acceptable as long as we haven't +actually implemented grey mutator collection. -ARCHITECTURE: +ARCHITECTURE Subclassing -.subclass: Since we expect to have many mark-and-sweep pools, we build in some -protocol for subclasses to modify various aspects of the behaviour. Notably -there's a subclassable segment class, and a protocol for performing iteration. +.subclass: Since we expect to have many mark-and-sweep pools, we build +in some protocol for subclasses to modify various aspects of the +behaviour. Notably there's a subclassable segment class, and a +protocol for performing iteration. Allocation -.align: We divide the segments in grains, each the size of the format -alignment. .alloc-bit-table: We keep track of allocated grains using a bit -table. This allows a simple implementation of allocation and freeing using the -bit table operators, satisfying .req.simple, and can simplify the GC routines. -Eventually, this should use some sophisticated allocation technique suitable -for non-moving automatic pools. +.align: We divide the segments in grains, each the size of the format +alignment. .alloc-bit-table: We keep track of allocated grains using +a bit table. This allows a simple implementation of allocation and +freeing using the bit table operators, satisfying .req.simple, and can +simplify the GC routines. Eventually, this should use some +sophisticated allocation technique suitable for non-moving automatic +pools. -.buffer: We use buffered allocation, satisfying .req.incremental. The AMC -buffer technique is reused, although it is not suitable for non-moving pools, -but req.simple allows us to do that for now. +.buffer: We use buffered allocation, satisfying .req.incremental. The +AMC buffer technique is reused, although it is not suitable for +non-moving pools, but req.simple allows us to do that for now. -.extend: If there's no space in any existing segment, a new segment is -allocated. The actual class is allowed to decide the size of the new segment. +.extend: If there's no space in any existing segment, a new segment is +allocated. The actual class is allowed to decide the size of the new +segment. -.no-alloc: Do not support PoolAlloc, because we can't support one-phase -allocation for a scannable pool (unless we disallow incremental collection). -For exact details, see design.mps.buffer. +.no-alloc: Do not support PoolAlloc, because we can't support +one-phase allocation for a scannable pool (unless we disallow +incremental collection). For exact details, see design.mps.buffer. -.no-free: Do not support PoolFree, because automatic pools don't need explicit -free and having it encourages clients to use it (and therefore to have dangling -pointers, double frees, &c.) +.no-free: Do not support PoolFree, because automatic pools don't need +explicit free and having it encourages clients to use it (and +therefore to have dangling pointers, double frees, etc.) Colours -.colour: Objects in a segment which is _not_ condemned (for some trace) take -their colour (for this trace) from the segment. .colour.object: Since we need -to implement a non-copying GC, we keep track of the colour of each object in a -condemned segment separately. For this, we use bit tables with a bit for each -grain. This format is fast to access, has better locality than mark bits in -the objects themselves, and allows cheap interoperation with the allocation bit -table. As to the details, we follow analysis.non-moving-colour(0), with the -the analysis.non-moving-colour.free.black option [why?]. .colour.alloc-table: -We choose to keep a separate allocation table, for generality. +.colour: Objects in a segment which is _not_ condemned (for some +trace) take their colour (for this trace) from the segment. +.colour.object: Since we need to implement a non-copying GC, we keep +track of the colour of each object in a condemned segment separately. +For this, we use bit tables with a bit for each grain. This format is +fast to access, has better locality than mark bits in the objects +themselves, and allows cheap interoperation with the allocation bit +table. .colour.encoding: As to the details, we follow +analysis.non-moving-colour(3), implementing both the alloc-white +sharing option described in +analysis.non-moving-colour.constraint.reclaim.white-free-bit and the +vanilla three-table option, because the former cannot work with +interior pointers. However, the colour encoding in both is the same. -.ambiguous.middle: We will allow ambiguous references into the middle of an -object (as required by .req.ambiguous), using the trick in -analysis.non-moving-colour.interior.ambiguous-only to speed up scanning. -.interior-pointer: Note that non-ambiguous interior pointers are outlawed. +.ambiguous.middle: We will allow ambiguous references into the middle +of an object (as required by .req.ambiguous), using the trick in +analysis.non-moving-colour.interior.ambiguous-only to speed up +scanning. .interior-pointer: Note that non-ambiguous interior +pointers are outlawed. -.colour.alloc: Objects are allocated black. This is the most efficient -alternative for traces in the black mutator phase, and .not-req.grey means -that's sufficient. [Some day, we need to think about allocating grey or white -during the grey mutator phase.] +.colour.alloc: Objects are allocated black. This is the most +efficient alternative for traces in the black mutator phase, and +.not-req.grey means that's sufficient. [Some day, we need to think +about allocating grey or white during the grey mutator phase.] Scanning -.scan.segment: The tracer protocol requires (for segment barrier hits) that -there is a method for scanning a segment and turning all grey objects on it -black. This cannot be achieved with a single sequential sweep over the -segment, since objects that the sweep has already passed may become grey as -later objects are scanned. .scan.graph: For a non-moving GC, it is more -efficient to trace along the reference graph than segment by segment [it would -also allow passing type information from fix to scan]. Currently, the tracer -doesn't offer this option when it's polling for work. +.scan.segment: The tracer protocol requires (for segment barrier hits) +that there is a method for scanning a segment and turning all grey +objects on it black. This cannot be achieved with a single sequential +sweep over the segment, since objects that the sweep has already +passed may become grey as later objects are scanned. .scan.graph: For +a non-moving GC, it is more efficient to trace along the reference +graph than segment by segment [it would also allow passing type +information from fix to scan]. Currently, the tracer doesn't offer +this option when it's polling for work. -.scan.stack: Tracing along the reference graph cannot be done by recursive -descent, because we can't guarantee that the stack won't overflow. We can, -however, maintain an explicit stack of things to trace, and fall back on -iterative methods (.scan.iter) when it overflows and can't be extended. +.scan.stack: Tracing along the reference graph cannot be done by +recursive descent, because we can't guarantee that the stack won't +overflow. We can, however, maintain an explicit stack of things to +trace, and fall back on iterative methods (.scan.iter) when it +overflows and can't be extended. -.scan.iter: As discussed in .scan.segment, when scanning a segment, we need to -ensure that there are no grey objects in the segment when the scan method -returns. We can do this by iterating a sequential scan over the segment until -nothing is grey (see .marked.scan for details). .scan.iter.only: Some -iterative method is needed as a fallback for the more advanced methods, and as -this is the simplest way of implementing the current tracer protocol, we will -start by implementing it as the only scanning method. +.scan.iter: As discussed in .scan.segment, when scanning a segment, we +need to ensure that there are no grey objects in the segment when the +scan method returns. We can do this by iterating a sequential scan +over the segment until nothing is grey (see .marked.scan for details). +.scan.iter.only: Some iterative method is needed as a fallback for the +more advanced methods, and as this is the simplest way of implementing +the current tracer protocol, we will start by implementing it as the +only scanning method. -.scan.buffer: We do not scan between ScanLimit and Limit of a buffer (see -.iteration.buffer), as usual [design.mps.buffer should explain why this works, -but doesn't. Pekka 1998-02-11]. +.scan.buffer: We do not scan between ScanLimit and Limit of a buffer +(see .iteration.buffer), as usual [design.mps.buffer should explain +why this works, but doesn't. Pekka 1998-02-11]. -.fix.to-black: When fixing a reference to a white object, if the segment does -not refer to the white set, the object cannot refer to the white set, and can -therefore be marked as black immediately (rather than grey). +.fix.to-black: When fixing a reference to a white object, if the +segment does not refer to the white set, the object cannot refer to +the white set, and can therefore be marked as black immediately +(rather than grey). - -ANALYSIS: - -[This section intentionally left blank.] - - -IDEAS: - -[This section intentionally left blank.] - - -IMPLEMENTATION: +IMPLEMENTATION Colour -.colour.determine: Following the plan in .colour, if SegWhite(seg) includes the -trace, the colour of an object is given by the bit tables. Otherwise if -SegGrey(seg) includes the trace, all the objects are grey. Otherwise all the -objects are black. +.colour.determine: Following the plan in .colour, if SegWhite(seg) +includes the trace, the colour of an object is given by the bit +tables. Otherwise if SegGrey(seg) includes the trace, all the objects +are grey. Otherwise all the objects are black. -.colour.bits: As we only have searches for runs of zero bits, we use two bit -tables, the non-grey and non-white tables, but this is hidden beneath a layer -of macros talking about grey and white in positive terms. +.colour.bits: As we only have searches for runs of zero bits, we use +two bit tables, the non-grey and non-white tables, but this is hidden +beneath a layer of macros talking about grey and white in positive +terms. -.colour.single: We have only implemented a single set of mark and scan tables, -so we can only condemn a segment for one trace at a time. This is checked for -in condemnation. If we want to do overlapping white sets, each trace needs its -own set of tables. +.colour.single: We have only implemented a single set of mark and scan +tables, so we can only condemn a segment for one trace at a time. +This is checked for in condemnation. If we want to do overlapping +white sets, each trace needs its own set of tables. -.colour.check: The grey&white state is illegal, and free objects must be not -grey and not white as explained in analysis.non-moving-colour.free.black. +.colour.check: The +grey&non-white state is illegal, and free objects must be white as +explained in analysis.non-moving-colour.contraint.reclaim. Iteration -.iteration: Scan, reclaim and other operations need to iterate over all objects -in a segment. We abstract this into a single iteration function, even though -we no longer use it for reclaiming and rarely for scanning. +.iteration: Scan, reclaim and other operations need to iterate over +all objects in a segment. We abstract this into a single iteration +function, even though we no longer use it for reclaiming and rarely +for scanning. -.iteration.buffer: Iteration skips directly from ScanLimit to Limit of a -buffer. This is because this area may contain partially-initialized and -uninitialized data, which cannot be processed. [ScanLimit is used for reasons -which are not documented in design.mps.buffer.] Since the iteration skips the -buffer, callers need to take the appropriate action, if any, on it. +.iteration.buffer: Iteration skips directly from ScanLimit to Limit of +a buffer. This is because this area may contain partially-initialized +and uninitialized data, which cannot be processed. [ScanLimit is used +for reasons which are not documented in design.mps.buffer.] Since the +iteration skips the buffer, callers need to take the appropriate +action, if any, on it. Scanning Algorithm -.marked: Each segment has a 'marksChanged' flag, indicating whether anything in -it has been made grey since the last scan iteration (.scan.iter) started. This -flag only concerns the colour of objects with respect to the trace for which -the segment is condemned, as this is the only trace for which objects in the -segment are being made grey by fixing. Note that this flag doesn't imply that -there are grey objects in the segment, because the grey objects might have been +.marked: Each segment has a 'marksChanged' flag, indicating whether +anything in it has been made grey since the last scan iteration +(.scan.iter) started. This flag only concerns the colour of objects +with respect to the trace for which the segment is condemned, as this +is the only trace for which objects in the segment are being made grey +by fixing. Note that this flag doesn't imply that there are grey +objects in the segment, because the grey objects might have been subsequently scanned and blackened. -.marked.fix: The marksChanged flag is set TRUE by AMSFix when an object is made -grey. +.marked.fix: The marksChanged flag is set TRUE by AMSFix when an +object is made grey. -.marked.scan: AMSScan must blacken all grey objects on the segment, so it must -iterate over the segment until all grey objects have been seen. Scanning an -object in the segment might grey another one (.marked.fix), so the scanner -iterates until this flag is FALSE, setting it to FALSE before each scan. It is -safe to scan the segment even if it contains nothing grey. +.marked.scan: AMSScan must blacken all grey objects on the segment, so +it must iterate over the segment until all grey objects have been +seen. Scanning an object in the segment might grey another one +(.marked.fix), so the scanner iterates until this flag is FALSE, +setting it to FALSE before each scan. It is safe to scan the segment +even if it contains nothing grey. -.marked.scan.fail: If the format scanner returns failure (see -protocol.mps.scanning [is that the best reference?]), we abort the scan in the -middle of a segment. So in this case the marksChanged flag is set back to -TRUE, because we may not have blackened all grey objects. +.marked.scan.fail: If the format scanner returns failure (see +protocol.mps.scanning [is that the best reference?]), we abort the +scan in the middle of a segment. So in this case the marksChanged +flag is set back to TRUE, because we may not have blackened all grey +objects. -.marked.unused: The marksChanged flag is meaningless unless the segment is -condemned. We make it FALSE in these circumstances. +.marked.unused: The marksChanged flag is meaningless unless the +segment is condemned. We make it FALSE in these circumstances. -.marked.condemn: Condemnation makes all objects in a segment either black or -white, leaving nothing grey, so it doesn't need to set the marksChanged flag -which must already be FALSE. +.marked.condemn: Condemnation makes all objects in a segment either +black or white, leaving nothing grey, so it doesn't need to set the +marksChanged flag which must already be FALSE. -.marked.reclaim: When a segment is reclaimed, it can contain nothing marked as -grey, so the marksChanged flag must already be FALSE. +.marked.reclaim: When a segment is reclaimed, it can contain nothing +marked as grey, so the marksChanged flag must already be FALSE. -.marked.blacken: When the tracer decides not to scan, but to call PoolBlacken, -we know that any greyness can be removed. AMSBlacken does this and resets the -marksChanged flag, if it finds that the segment has been condemned. +.marked.blacken: When the tracer decides not to scan, but to call +PoolBlacken, we know that any greyness can be removed. AMSBlacken +does this and resets the marksChanged flag, if it finds that the +segment has been condemned. -.marked.clever: AMS could be clever about not setting the marksChanged flag, if -the fixed object is ahead of the current scan pointer. It could also keep low- -and high-water marks of grey objects, but we don't need to implement these -improvements at first. +.marked.clever: AMS could be clever about not setting the marksChanged +flag, if the fixed object is ahead of the current scan pointer. It +could also keep low- and high-water marks of grey objects, but we +don't need to implement these improvements at first. Allocation -.buffer-init: We take one init arg to set the Rank on the buffer, just to see -how it's done. +.buffer-init: We take one init arg to set the Rank on the buffer, just +to see how it's done. -.no-bit: As an optimization, we won't use the alloc bit table until the first -reclaim on the segment. Before that, we just keep a high-water mark. +.no-bit: As an optimization, we won't use the alloc bit table until +the first reclaim on the segment. Before that, we just keep a +high-water mark. -.fill: AMSBufferFill takes the simplest approach: it iterates over the segments -in the pool, looking for one which can be used to refill the buffer. -.fill.colour: The objects allocated from the new buffer must be black for all -traces (.colour.alloc), so putting it on a black segment (meaning one where -neither SegWhite(seg) nor SegGrey(seg) include the trace, see -.colour.determine) is obviously OK. White segments (where SegWhite(seg) -includes the trace) are also fine, as we can use the colour tables to make it -black (we don't actually have to adjust the tables, since free grains have the -same colour table encoding as black, see .colour.object). At first glance, it -seems we can't put it on a segment that is grey for some trace (one where where -SegWhite(seg) doesn't include the trace, but SegGrey(seg) does), because the -new objects would become grey as the buffer's ScanLimit advanced. We could -switch the segment over to using colour tables, but this becomes very hairy -when multiple traces are happening, so in that case, we'd be better off either -not attaching to grey segments or allowing grey allocation, wasteful as it is -[@@@@ decide which]. +.fill: AMSBufferFill takes the simplest approach: it iterates over the +segments in the pool, looking for one which can be used to refill the +buffer. .fill.colour: The objects allocated from the new buffer must +be black for all traces (.colour.alloc), so putting it on a black +segment (meaning one where neither SegWhite(seg) nor SegGrey(seg) +include the trace, see .colour.determine) is obviously OK. White +segments (where SegWhite(seg) includes the trace) are also fine, as we +can use the colour tables to make it black. At first glance, it seems +we can't put it on a segment that is grey but not white for some trace +(one where SegWhite(seg) doesn't include the trace, but SegGrey(seg) +does), because the new objects would become grey as the buffer's +ScanLimit advanced. However, in many configurations, the mutator +would hit a barrier as soon as it started initializing the object, +which would flip the buffer. In fact, the current (2002-01) +implementation of buffers assumes buffers are black, so they'd better. +.fill.colour.reclaim: In fact, putting a buffer on a condemned segment +will screw up the accounting in AMCReclaim, so it's disallowed. -.fill.slow: AMSBufferFill gets progressively slower as more segments fill up, -as it laboriously checks whether the buffer can be refilled from each segment, -by inspecting the allocation bitmap. This is helped a bit by keeping count of -free grains in each segment, but it still spends a lot of time iterating over -all the full segments checking the free size. Obviously, this can be much -improved (we could keep track of the largest free block in the segment and in -the pool, or we could keep the segments in some more efficient structure, or we -could have a real free list structure). +.fill.slow: AMSBufferFill gets progressively slower as more segments +fill up, as it laboriously checks whether the buffer can be refilled +from each segment, by inspecting the allocation bit map. This is +helped a bit by keeping count of free grains in each segment, but it +still spends a lot of time iterating over all the full segments +checking the free size. Obviously, this can be much improved (we +could keep track of the largest free block in the segment and in the +pool, or we could keep the segments in some more efficient structure, +or we could have a real free list structure). -.fill.extend: If there's no space in any existing segment, the segSize method -is called to decide the size of the new segment to allocate. If that fails, -the code tries to allocate a segment that's just large enough to satisfy the -request. +.fill.extend: If there's no space in any existing segment, the segSize +method is called to decide the size of the new segment to allocate. +If that fails, the code tries to allocate a segment that's just large +enough to satisfy the request. -.empty: AMSBufferEmpty makes the unused space free, since there's no reason not -to. We don't have to adjust the colour tables, since free grains have the same -colour table encoding as black, see .colour.object. +.empty: AMSBufferEmpty makes the unused space free, since there's no +reason not to. We have to adjust the colour tables as well, since +these grains were black and now they need to be white (or at least +encoded -G and W). -.reclaim.empty.buffer: Segments which after reclaim only contain a buffer could -be destroyed by trapping the buffer, but there's no point to this. +.reclaim.empty.buffer: Segments which after reclaim only contain a +buffer could be destroyed by trapping the buffer, but there's no point +to this. Initialization -.init: The initialization method AMSInit() takes one additional argument: the -format of objects allocated in the pool. The pool alignment is set equal to -the format alignment (see design.mps.align). +.init: The initialization method AMSInit() takes three additional +arguments: the format of objects allocated in the pool, the chain that +controls GC timing, and a flag for supporting ambiguous references. +.init.share: If support for ambiguity is required, the shareAllocTable +flag is reset to indicate the pool uses three separate bit tables, +otherwise it is set and the pool shares a table for non-white and +alloc (see .colour.encoding). -.init.internal: Subclasses call AMSInitInternal() to avoid the problems of -sharing va_list and emitting a superfluous PoolInitAMS event. +.init.align: The pool alignment is set equal to the format alignment +(see design.mps.align). + +.init.internal: Subclasses call AMSInitInternal() to avoid the +problems of sharing va_list and emitting a superfluous PoolInitAMS +event. Condemnation -.action: We use PoolCollectAct to condemn the whole pool (except the buffers) -at once. +.condemn.buffer: Buffers are not condemned, instead they are coloured +black, to make sure that the objects allocated will be black, +following .colour.alloc (or, if you wish, because buffers are ignored +like free space, so need the same encoding). -.condemn.buffer: Buffers are not condemned, instead they are coloured black, to -make sure that the objects allocated will be black, following .colour.alloc -(or, if you wish, because buffers are ignored like free space, so need the same -encoding). -.benefit.guess: The benefit computation is pulled out of a hat; any real pool -class will need a real benefit computation. It will return a positive value -when the allocated size of the pool is over one megabyte and more than twice -what it was when the last segment in this pool was reclaimed (we call this -lastReclaimedSize). +Reclaim -.benefit.repeat: We reset lastReclaimedSize when starting a trace in order to -avoid repeat condemnation (i.e., the next AMSBenefit returning 1.0 for the same -reason as the last). In the future we need to do better here. +.reclaim: Reclaim uses either of analysis.non-moving-colour +.constraint.reclaim.white-free-bit (just reuse the non-white table as +the alloc table) or +analysis.non-moving-colour.constraint.reclaim.free-bit (copy it), +depending on the shareAllocTable flag (as set by +.init.share). However, bit table still has to be iterated over to +count the free grains. Also, in a debug pool, each white block has to +be splatted. Segment Merging and Splitting -.split-merge: We provide methods for splitting and merging AMS segments. The -pool implementation doesn't cause segments to be split or merged - but a -subclass might want to do this (see .stress.split-merge). The methods serve as -an example of how to implement this facility. +.split-merge: We provide methods for splitting and merging AMS +segments. The pool implementation doesn't cause segments to be split +or merged - but a subclass might want to do this (see +.stress.split-merge). The methods serve as an example of how to +implement this facility. -.split-merge.constrain: There are some additional constraints on what segments -may be split or merged: +.split-merge.constrain: There are some additional constraints on what +segments may be split or merged: -.split-merge.constrain.align: Segments may only be split or merged at an -address which is aligned to the pool alignment as well as to the arena -alignment. .split-merge.constrain.align.justify: This constraint is implied by -the design of allocation and colour tables, which cannot represent segments -starting at unaligned addresses. The constraint only arises if the pool -alignment is larger than the arena alignment. There's no requirement to split -segments at unaligned addresses. +.split-merge.constrain.align: Segments may only be split or merged at +an address which is aligned to the pool alignment as well as to the +arena alignment. .split-merge.constrain.align.justify: This constraint +is implied by the design of allocation and colour tables, which cannot +represent segments starting at unaligned addresses. The constraint +only arises if the pool alignment is larger than the arena alignment. +There's no requirement to split segments at unaligned addresses. -.split-merge.constrain.empty: The higher segment must be empty. I.e. the higher -segment passed to SegMerge must be empty, and the higher segment returned by -SegSplit must be empty. .split-merge.constrain.empty.justify: This constraint -makes the code significantly simpler. There's no requirement for a more complex +.split-merge.constrain.empty: The higher segment must be empty. That +is, the higher segment passed to SegMerge must be empty, and the +higher segment returned by SegSplit must be +empty. .split-merge.constrain.empty.justify: This constraint makes the +code significantly simpler. There's no requirement for a more complex solution at the moment (as the purpose is primarily pedagogic). -.split-merge.fail: The split and merge methods are not proper anti-methods for -each other (see design.mps.seg.split-merge.fail.anti.no). Methods will not -reverse the side-effects of their counterparts if the allocation of the colour -and allocation bit tables should fail. Client methods which over-ride split and -merge should not be written in such a way that they might detect failure after -calling the next method, unless they have reason to know that the bit table -allocations will not fail. +.split-merge.fail: The split and merge methods are not proper +anti-methods for each other (see +design.mps.seg.split-merge.fail.anti.no). Methods will not reverse +the side-effects of their counterparts if the allocation of the colour +and allocation bit tables should fail. Client methods which over-ride +split and merge should not be written in such a way that they might +detect failure after calling the next method, unless they have reason +to know that the bit table allocations will not fail. +TESTING + +.stress: There's a stress test, MMsrc!amsss.c, that does 800 kB of +allocation, enough for about three GCs. It uses a modified Dylan +format, and checks for corruption by the GC. Both ambiguous and exact +roots are tested. + +.stress.split-merge: There's also a stress test for segment splitting +and merging, MMsrc!segsmss.c. This is similar to amsss.c - but it +defines a subclass of AMS, and causes segments to be split and merged. +Both buffered and non-buffered segments are split / merged. +NOTES -TESTING: +.addr-index.slow: Translating from an address to and from a grain +index in a segment uses macros such as AMS_INDEX and AMS_INDEX_ADDR. +These are slow because they call SegBase on every translation - we +could cache that. -.stress: There's a stress test, MMsrc!amsss.c, that does 800 KB of allocation, -enough for about three GCs. It uses a modified Dylan format, and checks for -corruption by the GC. Both ambiguous and exact roots are tested. - -.stress.split-merge: There's also a stress test for segment splitting and -merging, MMsrc!segsmss.c. This is similar to amsss.c - but it defines a -subclass of AMS, and causes segments to be split and merged. Both buffered and -non-buffered segments are split / merged. - - -TEXT: - -.addr-index.slow: Translating from an address to and from a grain index in a -segment uses macros such as AMSAddrIndex and AMSIndexAddr. These are slow -because they call SegBase on every translation. - -.grey-mutator: To enforce the restriction set in .not-req.grey we check that -all the traces are flipped in AMSScan. It would be good to check in AMSFix as -well, but we can't do that, because it's called during the flip, and we can't -tell the difference between the flip and the grey mutator phases with the -current tracer interface. +.grey-mutator: To enforce the restriction set in .not-req.grey we +check that all the traces are flipped in AMSScan. It would be good to +check in AMSFix as well, but we can't do that, because it's called +during the flip, and we can't tell the difference between the flip and +the grey mutator phases with the current tracer interface. @@ -453,6 +481,16 @@ current tracer interface. + + + 2002-06-20 + + NB + + Re-imported from Global Graphics. + + + diff --git a/mps/manual/reference/index.html b/mps/manual/reference/index.html index 42e597aef26..c97226fe95e 100644 --- a/mps/manual/reference/index.html +++ b/mps/manual/reference/index.html @@ -122,11 +122,9 @@
  • type mps_assert_t
  • function mps_bool_t
  • function mps_class_amc
    • -
  • mps_class_epdl_debug
    • -
  • mps_class_epdr_debug
    • -
  • mps_class_mv2
  • function mps_class_mvff
  • function mps_class_snc
    • +
  • mps_class_mvt
  • Type mps_class_t
  • function mps_finalize
  • type mps_fmt_A_s
    • @@ -185,7 +183,7 @@
  • function mps_root_create_table_masked
  • type mps_root_scan_t
  • type mps_roots_stepper_t
    • -
  • type mps_sac_classes_s
    • +
  • type mps_sac_class_s
  • function mps_sac_create
  • function mps_sac_destroy
  • function mps_sac_flush
    • @@ -197,35 +195,38 @@
  • function mps_telemetry_label
    • -

    MPS_ARCH_AL

    +

    MPS_ARCH_AL

    -

    Name

    +

    Name

    -

    MPS_ARCH_AL

    +

    MPS_ARCH_AL

    -

    Summary

    +

    Summary

    -

    MPS_ARCH_AL is a C preprocessor macro that indicates, if defined, that the targetprocessor architecture of the compilation is a member of the DEC Alpha family. It is defined, ifappropriate, by "mpstd.h".

    +

    MPS_ARCH_AL is a C +preprocessor macro that indicates, if defined, that the target +processor architecture of the compilation is a member of the DEC Alpha +family. It is defined, if appropriate, by "mpstd.h".

    -

    Associated Protocols

    +

    Associated Protocols

    -

    None.

    +

    None.

    -

    Resources

    +

    Resources

    -

    mpstd.h.

    +

    mpstd.h.

    -

    Description

    +

    Description

    -

    See summary.

    +

    See summary.

    -

    Example

    +

    Example

     #ifdef MPS_ARCH_AL
@@ -248,53 +249,65 @@ typedef struct RegisterFile {
    -

    Error Handling

    +

    Error Handling

    -

    Not applicable.

    +

    Not applicable.

    -

    See Also

    +

    See Also

    -

    MPS_PF_*, MPS_OS_*, MPS_BUILD_*, MPS_ARCH_*

    +

    + +MPS_PF_*, + +MPS_OS_*, + +MPS_BUILD_*, + +MPS_ARCH_*

    -

    Notes

    +

    Notes

    -

    Internal Notes

    +

    Internal Notes

    -

    I'm not sure that the user ought to be using these symbols. GavinM 1997-05-01

    +

    I'm not sure that the user ought to be using these symbols. GavinM +1997-05-01

    -

    MPS_ARCH_M6

    +

    MPS_ARCH_M6

    -

    Name

    +

    Name

    -

    MPS_ARCH_M6

    +

    MPS_ARCH_M6

    -

    Summary

    +

    Summary

    -

    MPS_ARCH_M6 is a C preprocessor macro that indicates, if defined, that the targetprocessor architecture of the compilation is a member of the Motorola 68000 family. It is defined, if appropriate, by "mpstd.h".

    +

    MPS_ARCH_M6 is a C +preprocessor macro that indicates, if defined, that the target +processor architecture of the compilation is a member of the Motorola +68000 family. It is defined, if appropriate, by "mpstd.h".

    -

    Associated Protocols

    +

    Associated Protocols

    -

    None.

    +

    None.

    -

    Resources

    +

    Resources

    -

    msptd.h.

    +

    msptd.h.

    -

    Description

    +

    Description

    -

    See summary.

    +

    See summary.

    -

    Example

    +

    Example

     #ifdef MPS_ARCH_M6
@@ -309,68 +322,95 @@ typedef struct RegisterFile {
    -

    Error Handling

    +

    Error Handling

    -

    Not applicable.

    +

    Not applicable.

    -

    See Also

    +

    See Also

    -

    MPS_PF_*, MPS_OS_*, MPS_BUILD_*, MPS_ARCH_*

    +

    + +MPS_PF_*, + +MPS_OS_*, + +MPS_BUILD_*, + +MPS_ARCH_*

    -

    function mps_fix

    +

    function mps_fix

    -

    Name

    +

    Name

    -

    mps_fix

    +

    mps_fix

    -

    Summary

    +

    Summary

    -

    The function mps_fix is the part of the scanning protocol used to indicate references to theMPS. It may only be called from within a scanning function.

    +

    The function mps_fix is the +part of the scanning protocol used to indicate references to the +MPS. It may only be called from within a scanning function.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Scanning.

    +

    Scanning.

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_fix(mps_ss_t mps_ss, mps_addr_t *ref_io)

    +

    mps_res_t mps_fix(mps_ss_t mps_ss, mps_addr_t *ref_io)

    -

    Arguments

    +

    Arguments

    -

    mps_ss the scan state argument that was passed to the scanning function

    +

    mps_ss the scan state argument that was passed to the +scanning function

    -

    ref_io a pointer to a reference within the object being scanned

    +

    ref_io a pointer to a reference within the object +being scanned

    -

    Returned Values

    +

    Returned Values

    -

    Returns a result code, see ERROR HANDLING.

    +

    Returns a result code, see ERROR HANDLING.

    -

    If the reference rank of the object being scanned is not MPS_RANK_AMBIG thenthe reference pointed to by ref_io may be modified by mps_fix.

    +

    If the reference rank of the object being scanned is not MPS_RANK_AMBIG then the reference +pointed to by ref_io may be modified by mps_fix.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This function is the part of the scanning protocol used to indicate references. Scanningfunctions apply it, or MPS_FIX12, or MPS_FIX1 and MPS_FIX2 tothe references in the object being scanned.

    +

    This function is the part of the scanning protocol used to indicate +references. Scanning functions apply it, or MPS_FIX12, or MPS_FIX1 and MPS_FIX2 tothe references in the object +being scanned.

    -

    It may only be called from within a scanning function. If it is called within a MPS_SCAN_BEGIN block, MPS_FIX_CALL must be used (yes, really).

    +

    It may only be called from within a scanning function. If it is +called within a MPS_SCAN_BEGIN block, MPS_FIX_CALL must be used (yes, +really).

    -

    This function does not perform any particular operation. The MPS may call scanning functionsfor a number of reasons, and mps_fix may take different actions depending on thosereasons.

    +

    This function does not perform any particular operation. The MPS +may call scanning functions for a number of reasons, and mps_fix may take different actions +depending on those reasons.

    -

    Example

    +

    Example

     mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length)
@@ -389,64 +429,113 @@ mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length)
    -

    Error Handling

    +

    Error Handling

    -

    The function returns MPS_RES_OK if it was successful, in which case the scanning functionshould continue to scan the rest of the object, applying mps_fix to the remaining references. If mps_fix returns a value other than MPS_RES_OK, the scanning function must return that value, and mayreturn without scanning further references. Generally, it is better if it returns as soon aspossible.

    +

    The function returns MPS_RES_OK if it was successful, in +which case the scanning function should continue to scan the rest of +the object, applying mps_fix to +the remaining references. If mps_fix returns a value other than MPS_RES_OK, the scanning function must +return that value, and may return without scanning further +references. Generally, it is better if it returns as soon +as possible.

    -

    See Also

    +

    See Also

    -

    mps_ss_t, mps_root_scan_t, mps_fmt_scan_t, mps_reg_scan_t, MPS_SCAN_BEGIN, MPS_SCAN_END, MPS_FIX12, MPS_FIX1, MPS_FIX2, MPS_FIX_CALL

    +

    + +mps_ss_t, + +mps_root_scan_t, + +mps_fmt_scan_t, + +mps_reg_scan_t, + +MPS_SCAN_BEGIN, + +MPS_SCAN_END, + +MPS_FIX12, + +MPS_FIX1, + +MPS_FIX2, + +MPS_FIX_CALL + +

    -

    macro MPS_FIX1

    +

    macro MPS_FIX1

    -

    Name

    +

    Name

    -

    MPS_FIX1

    +

    MPS_FIX1

    -

    Summary

    +

    Summary

    -

    The macro MPS_FIX1 is the part of the scanning protocol used to indicate references to theMPS. It may only be used from within MPS_SCAN_BEGIN and MPS_SCAN_END.

    +

    The macro MPS_FIX1 is the part +of the scanning protocol used to indicate references to the MPS. It +may only be used from within MPS_SCAN_BEGIN and MPS_SCAN_END.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    Syntax

    +

    Syntax

    -

    MPS_FIX1(mps_ss, ref)

    +

    MPS_FIX1(mps_ss, ref)

    -

    Arguments

    +

    Arguments

    -

    mps_ss the scan state argument that was passed to the scanning function

    +

    mps_ss the scan state argument +that was passed to the scanning function

    -

    ref a reference within the object being scanned, type mps_addr_t

    +

    ref a reference within the object being scanned, type +mps_addr_t

    -

    Returned Values

    +

    Returned Values

    -

    Returns a truth value (type mps_bool_t) indicating whether the reference is likely to beinteresting to the MPS.

    +

    Returns a truth value (type mps_bool_t) indicating whether the +reference is likely to be interesting to the MPS.

    -

    Resources

    +

    Resources

    -

    mps.h.

    +

    mps.h.

    -

    Description

    +

    Description

    -

    MPS_FIX1 and MPS_FIX2 are a trick to speed up scanning by splitting MPS_FIX12 into two macros. MPS_FIX1 is a fast test to see if the reference is likely to be interesting to the MPS; ifit returns false, the scanner can proceed to the next reference. If it returns true, the scan methodmust invoke MPS_FIX2, which does the actual fixing.

    +

    MPS_FIX1 and MPS_FIX2 are a trick to speed up scanning +by splitting MPS_FIX12 into two +macros. MPS_FIX1 is a fast test +to see if the reference is likely to be interesting to the MPS; if it +returns false, the scanner can proceed to the next reference. If it +returns true, the scan method must invoke MPS_FIX2, which does the actual +fixing.

    -

    This macro may only be used in code textually between MPS_SCAN_BEGIN and MPS_SCAN_END.

    +

    This macro may only be used in code textually between MPS_SCAN_BEGIN and MPS_SCAN_END.

    -

    Example

    +

    Example

     mps_res_t scan_array(mps_ss_t ss, Array object, size_t length)
@@ -474,65 +563,105 @@ mps_res_t scan_array(mps_ss_t ss, Array object, size_t length)
    -

    See Also

    +

    See Also

    -

    MPS_FIX12, MPS_FIX2, mps_fix, mps_ss_t, mps_root_scan_t, mps_fmt_scan_t, mps_reg_scan_t, MPS_SCAN_BEGIN, MPS_SCAN_END, MPS_FIX_CALL

    +

    + +MPS_FIX12, + +MPS_FIX2, + +mps_fix, + +mps_ss_t, + +mps_root_scan_t, + +mps_fmt_scan_t, + +mps_reg_scan_t, + +MPS_SCAN_BEGIN, + +MPS_SCAN_END, + +MPS_FIX_CALL

    -

    macro MPS_FIX12

    +

    macro MPS_FIX12

    -

    Name

    +

    Name

    -

    MPS_FIX12

    +

    MPS_FIX12

    -

    Summary

    +

    Summary

    -

    The macro MPS_FIX12 is the part of the scanning protocol used to indicatereferences to the MPS. It may only be used from within MPS_SCAN_BEGIN and MPS_SCAN_END.

    +

    The macro MPS_FIX12 is the +part of the scanning protocol used to indicate references to the +MPS. It may only be used from within MPS_SCAN_BEGIN and MPS_SCAN_END.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Scanning.

    +

    Scanning.

    -

    Syntax

    +

    Syntax

    -

    MPS_FIX12(mps_ss, ref_io);

    +

    MPS_FIX12(mps_ss, ref_io);

    -

    Arguments

    +

    Arguments

    -

    mps_ss the scan state argument that was passed to the scanning function

    +

    mps_ss the scan state argument that was passed to the scanning function

    -

    ref_io a pointer to a reference within the object being scanned, type mps_addr_t *

    +

    ref_io a pointer to a reference within the object +being scanned, type mps_addr_t *

    -

    Returned Values

    +

    Returned Values

    -

    Returns a result code, see ERROR HANDLING.

    +

    Returns a result code, see ERROR HANDLING.

    -

    If the reference rank of the object being scanned is not MPS_RANK_AMBIG then the reference pointed to by ref_io may be modified by MPS_FIX12.

    +

    If the reference rank of the object being scanned is not MPS_RANK_AMBIG then the reference +pointed to by ref_io may be modified by MPS_FIX12.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This macro is used in the scanning protocol to indicate references. Scanning functions apply it or mps_fix or MPS_FIX1 and MPS_FIX2 to the references in the object being scanned.

    +

    This macro is used in the scanning protocol to indicate +references. Scanning functions apply it or mps_fix or MPS_FIX1 and MPS_FIX2 to the references in the object +being scanned.

    -

    It may only be used in code textually between MPS_SCAN_BEGIN and MPS_SCAN_END.

    +

    It may only be used in code textually between MPS_SCAN_BEGIN and MPS_SCAN_END.

    -

    It is permitted for the reference (*ref_io) to point outside the MPS arena being scanned, or to be NULL; in that case, it is simply ignored.

    +

    It is permitted for the reference (*ref_io) to point +outside the MPS arena being scanned, or to be NULL; in that case, it +is simply ignored.

    -

    This macro does not perform any particular operation. The MPS may call scanning functions for a number of reasons, and MPS_FIX may take different actions depending on those reasons.

    +

    This macro does not perform any particular operation. The MPS may +call scanning functions for a number of reasons, and MPS_FIX may take different actions +depending on those reasons.

    -

    Example

    +

    Example

     mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length) {
@@ -553,73 +682,110 @@ mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length) {
    -

    Error Handling

    +

    Error Handling

    -

    The macro returns MPS_RES_OK if it was successful, in which case the scanningfunction should continue to scan the rest of the object, fixing the remaining references. If MPS_FIX12 returns a value other than MPS_RES_OK, the scanning functionmust return that value, and may return without scanning further references. Generally, it is better if it returns as soon as possible.

    +

    The macro returns MPS_RES_OK +if it was successful, in which case the scanning function should +continue to scan the rest of the object, fixing the remaining +references. If MPS_FIX12 returns +a value other than MPS_RES_OK, +the scanning function must return that value, and may return without +scanning further references. Generally, it is better if it returns as +soon as possible.

    -

    See Also

    +

    See Also

    -

    mps_fix, mps_ss_t, mps_root_scan_t, mps_fmt_scan_t, mps_reg_scan_t, MPS_SCAN_BEGIN, MPS_SCAN_END, MPS_FIX1, MPS_FIX2, MPS_FIX_CALL

    +

    + +mps_fix, + +mps_ss_t, + +mps_root_scan_t, + +mps_fmt_scan_t, + +mps_reg_scan_t, + +MPS_SCAN_BEGIN, + +MPS_SCAN_END, + +MPS_FIX1, + +MPS_FIX2, + +MPS_FIX_CALL

    -

    Notes

    +

    Notes

    -

    MPS_FIX12 is so called, as it basically performs the work of both MPS_FIX1 and MPS_FIX2.

    +

    MPS_FIX12 is so called, as it basically performs the work of both MPS_FIX1 and MPS_FIX2.

    -

    macro MPS_FIX2

    +

    macro MPS_FIX2

    -

    Name

    +

    Name

    -

    MPS_FIX2

    +

    MPS_FIX2

    -

    Summary

    +

    Summary

    -

    The macro MPS_FIX2, together with MPS_FIX1, is the part of the scanning protocol used to indicate references to the MPS. It may only be used from within MPS_SCAN_BEGIN and MPS_SCAN_END.

    +

    The macro MPS_FIX2, together with MPS_FIX1, is the part of the scanning protocol used to indicate references to the MPS. It may only be used from within MPS_SCAN_BEGIN and MPS_SCAN_END.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Scanning.

    +

    Scanning.

    -

    Syntax

    +

    Syntax

    -

    MPS_FIX2(mps_ss, ref_io);

    +

    MPS_FIX2(mps_ss, ref_io);

    -

    Arguments

    +

    Arguments

    -

    mps_ss the scan state argument that was passed to the scanning function

    +

    mps_ss the scan state argument +that was passed to the scanning function

    -

    ref_io a pointer to a reference within the object being scanned, type mps_addr_t *

    +

    ref_io a pointer to a reference within the object +being scanned, type mps_addr_t *

    -

    Returned Values

    +

    Returned Values

    -

    Returns a result code, see ERROR HANDLING.

    +

    Returns a result code, see ERROR HANDLING.

    -

    If the reference rank of the object being scanned is not MPS_RANK_AMBIG then the reference pointed to by ref_io may be modified by MPS_FIX2.

    +

    If the reference rank of the object being scanned is not MPS_RANK_AMBIG then the reference pointed to by ref_io may be modified by MPS_FIX2.

    -

    Resources

    +

    Resources

    -

    mps.h.

    +

    mps.h.

    -

    Description

    +

    Description

    -

    MPS_FIX1 and MPS_FIX2 are a trick to speed up scanning by splitting MPS_FIX12 into two macros. MPS_FIX1 is a fast test to see if the reference is likely to be interesting to the MPS; ifit returns false, the scanner can proceed to the next reference. If it returns true, the scan methodmust invoke MPS_FIX2, which does the actual fixing.

    +

    MPS_FIX1 and MPS_FIX2 are a trick to speed up scanning +by splitting MPS_FIX12 into two +macros. MPS_FIX1 is a fast test +to see if the reference is likely to be interesting to the MPS; if it +returns false, the scanner can proceed to the next reference. If it +returns true, the scan method must invoke MPS_FIX2, which does the actual +fixing.

    -

    This macro may only be used in code textually between MPS_SCAN_BEGIN and MPS_SCAN_END.

    +

    This macro may only be used in code textually between MPS_SCAN_BEGIN and MPS_SCAN_END.

    -

    This macro does not perform any particular operation. The MPS may call scanning functions for a number of reasons, and MPS_FIX2 may take different actions depending on those reasons.

    +

    This macro does not perform any particular operation. The MPS may call scanning functions for a number of reasons, and MPS_FIX2 may take different actions depending on those reasons.

    -

    Example

    +

    Example

     mps_res_t scan_array(mps_ss_t ss, Array object, size_t length) {
@@ -646,64 +812,104 @@ mps_res_t scan_array(mps_ss_t ss, Array object, size_t length) {
    -

    Error Handling

    +

    Error Handling

    -

    The macro returns MPS_RES_OK if it was successful, in which case the scanningfunction should continue to scan the rest of the object, fixing the remaining references. IfMPS_FIX2 returns a value other than MPS_RES_OK, the scanning functionmust return that value, and may return without scanning further references. Generally, it is betterif it returns as soon as possible.

    +

    The macro returns MPS_RES_OK +if it was successful, in which case the scanning function should +continue to scan the rest of the object, fixing the remaining +references. IfMPS_FIX2 returns a +value other than MPS_RES_OK, +the scanning function must return that value, and may return without +scanning further references. Generally, it is better if it returns as +soon as possible.

    -

    See Also

    +

    See Also

    -

    MPS_FIX12, MPS_FIX1, mps_fix, mps_ss_t, mps_root_scan_t, mps_fmt_scan_t, mps_reg_scan_t, MPS_SCAN_BEGIN, MPS_SCAN_END, MPS_FIX_CALL

    +

    + +MPS_FIX12, + +MPS_FIX1, + +mps_fix, + +mps_ss_t, + +mps_root_scan_t, + +mps_fmt_scan_t, + +mps_reg_scan_t, + +MPS_SCAN_BEGIN, + +MPS_SCAN_END, + +MPS_FIX_CALL

    -

    macro MPS_FIX_CALL

    +

    macro MPS_FIX_CALL

    -

    Name

    +

    Name

    -

    MPS_FIX_CALL

    +

    MPS_FIX_CALL

    -

    Summary

    +

    Summary

    -

    MPS_FIX_CALL is used to call a scanning function from within MPS_SCAN_BEGIN and MPS_SCAN_END.

    +

    MPS_FIX_CALL is used to call a scanning function from within MPS_SCAN_BEGIN and MPS_SCAN_END.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Scanning.

    +

    Scanning.

    -

    Syntax

    +

    Syntax

    -

    MPS_FIX_CALL(ss, call);

    +

    MPS_FIX_CALL(ss, call);

    -

    Arguments

    +

    Arguments

    -

    mps_ss the scan state argument that was passed to the scanning function

    +

    mps_ss the scan state argument that was passed to the scanning function

    -

    call an expression (containing a call to a scanning function)

    +

    call an expression (containing a call to a scanning function)

    -

    Returned Values

    +

    Returned Values

    -

    None.

    +

    None.

    -

    Resources

    +

    Resources

    -

    mps.h.

    +

    mps.h.

    -

    Description

    +

    Description

    -

    When using the MPS_SCAN_BEGIN and MPS_SCAN_END macros, you can't directly call a separatefunction to do part of the scanning, because between MPS_SCAN_BEGIN and MPS_SCAN_END, thescan_state parameter is in a strange state, so you shouldn't pass it as an argument to a function.However, if really want to do it (say, because you have an embedded structure shared between twoscan methods), you can pass the scan state correctly using MPS_FIX_CALL.

    +

    When using the MPS_SCAN_BEGIN and MPS_SCAN_END macros, you can't +directly call a separate function to do part of the scanning, because +between MPS_SCAN_BEGIN and +MPS_SCAN_END, the +scan_state parameter is in a strange state, so you +shouldn't pass it as an argument to a function. However, if you +really want to do it (say, because you have an embedded structure +shared between two scan methods), you can pass the scan state +correctly using MPS_FIX_CALL.

    -

    Note that you must receive the return value of the scanning function called, and pass it onas described in the ERROR HANDLING section.

    +

    Note that you must receive the return value of the scanning +function called, and pass it on as described in the ERROR HANDLING +section.

    -

    Example

    +

    Example

     mps_res_t foo_scan(mps_ss_t scan_state, mps_addr_t base, mps_addr_t limit)
@@ -728,40 +934,73 @@ mps_res_t foo_scan(mps_ss_t scan_state, mps_addr_t base, mps_addr_t limit)
    -

    Error Handling

    +

    Error Handling

    -

    You must receive the return value of the function called. Like all scanning functions, itreturns MPS_RES_OK if it was successful, in which case the caller should continue toscan the rest of the object, fixing the remaining references. If it returns a value other thanMPS_RES_OK, the calling scanning function must return that value, and may returnwithout scanning further references. Generally, it is better if it returns as soon as possible.

    +

    You must receive the return value of the function called. Like all +scanning functions, itreturns MPS_RES_OK if it was successful, in +which case the caller should continue to scan the rest of the object, +fixing the remaining references. If it returns a value other +thanMPS_RES_OK, the calling +scanning function must return that value, and may return without +scanning further references. Generally, it is better if it returns as +soon as possible.

    -

    See Also

    +

    See Also

    -

    mps_fix, mps_ss_t, mps_root_scan_t, mps_fmt_scan_t, mps_reg_scan_t, MPS_SCAN_BEGIN, MPS_SCAN_END, MPS_FIX12, MPS_FIX1, MPS_FIX2

    +

    + +mps_fix, + +mps_ss_t, + +mps_root_scan_t, + +mps_fmt_scan_t, + +mps_reg_scan_t, + +MPS_SCAN_BEGIN, + +MPS_SCAN_END, + +MPS_FIX12, + +MPS_FIX1, + +MPS_FIX2

    -

    constant MPS_RES_LIMIT

    +

    constant MPS_RES_LIMIT

    -

    Name

    +

    Name

    -

    MPS_RES_LIMIT

    +

    MPS_RES_LIMIT

    -

    Summary

    +

    Summary

    -

    MPS_RES_LIMIT is a result code, indicating that an operation failed because an internallimit was reached.

    +

    MPS_RES_LIMIT is a result +code, indicating that an operation failed because an internal limit +was reached.

    -

    Resources

    +

    Resources

    -

    mps.h.

    +

    mps.h.

    -

    Description

    +

    Description

    -

    This result code is returned if an operation could not be completed as requested because ofan internal limitation of the MPS. The precise meaning depends on the function that returned thecode. Refer to the documentation of that function for details.

    +

    This result code is returned if an operation could not be completed +as requested because of an internal limitation of the MPS. The precise +meaning depends on the function that returned the code. Refer to the +documentation of that function for details.

    -

    Example

    +

    Example

       switch(mps_alloc(&(mps_addr_t)object, pool, size)) {
@@ -775,85 +1014,109 @@ mps_res_t foo_scan(mps_ss_t scan_state, mps_addr_t base, mps_addr_t limit)
    -

    See Also

    +

    See Also

    -

    mps_res_t

    +

    + +mps_res_t

    -

    constant MPS_RES_MEMORY

    +

    constant MPS_RES_MEMORY

    -

    Name

    +

    Name

    -

    MPS_RES_MEMORY

    +

    MPS_RES_MEMORY

    -

    Summary

    +

    Summary

    -

    MPS_RES_MEMORY is a result code, indicating that an operation failed because it ran out of memory.

    +

    MPS_RES_MEMORY is a result code, indicating that an operation failed because it ran out of memory.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    All.

    +

    All.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This result code is returned if an operation could not be completed because there wasn'tenough memory available. You need to deallocate something or allow the garbage collector to reclaimsomething to free enough memory, or expand the arena (if you're using an arena where that does nothappen automatically).

    +

    This result code is returned if an operation could not be completed +because there wasn't enough memory available. You need to deallocate +something or allow the garbage collector to reclaim something to free +enough memory, or expand the arena (if you're using an arena for which +that does not happen automatically).

    -

    Note that failing to acquire enough memory because the arena commit limit would have beenexceeded is indicated by returning MPS_RES_COMMIT_LIMIT, not MPS_RES_MEMORY.

    +

    Note that failing to acquire enough memory because the arena commit +limit would have been exceeded is indicated by returning MPS_RES_COMMIT_LIMIT, not +MPS_RES_MEMORY.

    -

    Note that running out of address space (as might happen in virtual memory systems) isindicated by returning MPS_RES_RESOURCE, not MPS_RES_MEMORY.

    +

    Note that running out of address space (as might happen in virtual +memory systems) is indicated by returning MPS_RES_RESOURCE, not MPS_RES_MEMORY.

    -

    Example

    +

    Example

    -

    See Also

    +

    See Also

    -

    mps_res_t, MPS_RES_RESOURCE, MPS_RES_COMMIT_LIMIT

    +

    + +mps_res_t, + +MPS_RES_RESOURCE, + +MPS_RES_COMMIT_LIMIT

    -

    MPS_RES_PARAM

    +

    MPS_RES_PARAM

    -

    Name

    +

    Name

    -

    MPS_RES_PARAM

    +

    MPS_RES_PARAM

    -

    Summary

    +

    Summary

    -

    MPS_RES_PARAM is a result code, indicating that an operation failed because an invalidparameter was specified for the operation.

    +

    MPS_RES_PARAM is a result +code, indicating that an operation failed because an invalid parameter +was specified for the operation.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    All.

    +

    All.

    -

    Type

    +

    Type

    -

    mps_res_t

    +

    mps_res_t

    -

    Resources

    +

    Resources

    -

    mps.h.

    +

    mps.h.

    -

    Description

    +

    Description

    -

    This result code is returned if an operation could not be completed as requested because aninvalid parameter was specified for the operation. The precise meaning depends on the function thatreturned the code. Refer to the documentation of that function for details.

    +

    This result code is returned if an operation could not be completed +as requested because an invalid parameter was specified for the +operation. The precise meaning depends on the function that returned +the code. Refer to the documentation of that function for details.

    -

    Example

    +

    Example

       switch( res = mps_pool_create_v(&pool, arena, class, params) ) {
@@ -867,53 +1130,69 @@ mps_res_t foo_scan(mps_ss_t scan_state, mps_addr_t base, mps_addr_t limit)
    -

    See Also

    +

    See Also

    -

    mps_res_t

    +

    + +mps_res_t

    -

    Notes

    +

    Notes

    -

    Internal Notes

    +

    Internal Notes

    -

    MPS_RM_CONST

    +

    MPS_RM_CONST

    -

    Name

    +

    Name

    -

    MPS_RM_CONST

    +

    MPS_RM_CONST

    -

    Summary

    +

    Summary

    -

    MPS_RM_CONST is a constant used in root mode arguments to indicate constant roots.

    +

    MPS_RM_CONST is a constant used in root mode arguments to indicate constant roots.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Root.

    +

    Root.

    -

    Type

    +

    Type

    -

    Integral constant.

    +

    Integral constant.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    MPS_RM_CONST is a preprocessor macro defining a constant that can be OR'ed to otherMPS_RM_* constants, and passed as the root mode argument to certain root creation functions (mps_root_create, mps_root_create_fmt, mps_root_create_table, mps_root_create_table_masked,mps_root_create_reg ).

    +

    MPS_RM_CONST is a +preprocessor macro defining a constant that can be OR'ed with other +MPS_RM_* constants, and passed as the root mode argument +to certain root creation functions (mps_root_create, mps_root_create_fmt, mps_root_create_table, +mps_root_create_table_masked, +mps_root_create_reg +).

    -

    Passing MPS_RM_CONST means that the client program will not change the root after it isdeclared. I.e., scanning the root will produce the same set of references every time. Furthermore,for formatted and table roots, the client program may not write to the root at all.

    +

    Passing MPS_RM_CONST means +that the client program will not change the root after it is +declared. I.e., scanning the root will produce the same set of +references every time. Furthermore, for formatted and table roots, the +client program may not write to the root at all.

    -

    Example

    +

    Example

       res = mps_root_create_table(&mmRoot,
@@ -925,57 +1204,83 @@ mps_res_t foo_scan(mps_ss_t scan_state, mps_addr_t base, mps_addr_t limit)
    -

    See Also

    +

    See Also

    -

    mps_root_create, mps_root_create_fmt, mps_root_create_table, mps_root_create_table_masked, mps_root_create_reg

    +

    + +mps_root_create, + +mps_root_create_fmt, + +mps_root_create_table, + +mps_root_create_table_masked, + +mps_root_create_reg

    -

    Notes

    +

    Notes

    -

    Internal Notes

    +

    Internal Notes

    -

    Currently ignored. -- drj 1997-12-18.

    +

    Currently ignored. -- drj 1997-12-18.

    -

    MPS_RM_PROT

    +

    MPS_RM_PROT

    -

    Name

    +

    Name

    -

    MPS_RM_PROT

    +

    MPS_RM_PROT

    -

    Summary

    +

    Summary

    -

    MPS_RM_PROT is a constant used in root mode arguments to indicate protectable roots.

    +

    MPS_RM_PROT is a constant used in root mode arguments to indicate protectable roots.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Root.

    +

    Root.

    -

    Type

    +

    Type

    -

    Integral constant.

    +

    Integral constant.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    MPS_RM_PROT is a preprocessor macro defining a constant that can be OR'ed to other MPS_RM_* contants, and passed as the root mode argument to certain root creation functions (mps_root_create_fmt, mps_root_create_table, mps_root_create_table_masked).

    +

    MPS_RM_PROT is a +preprocessor macro defining a constant that can be OR'ed with other +MPS_RM_* contants, and passed as the root mode argument +to certain root creation functions (mps_root_create_fmt, mps_root_create_table, +mps_root_create_table_masked).

    -

    Passing MPS_RM_PROT means that t he MPS may place a hardware write barrier on any pageswhich any part of the root covers. Format methods and any scanning function (except for the one forthis root) may not write data in this root. They may read it.

    +

    Passing MPS_RM_PROT means +that the MPS may place a hardware write barrier on any pages which any +part of the root covers. Format methods and any scanning function +(except for the one for this root) may not write data in this +root. They may read it.

    -

    You mustn't specify MPS_RM_PROT on a root allocated from the MPS.

    +

    You mustn't specify MPS_RM_PROT on a root allocated from +the MPS.

    -

    Example

    +

    Example

       res = mps_root_create_table(&mmRoot,
@@ -987,61 +1292,99 @@ mps_res_t foo_scan(mps_ss_t scan_state, mps_addr_t base, mps_addr_t limit)
    -

    See Also

    +

    See Also

    -

    mps_root_create_fmt, mps_root_create_table, mps_root_create_table_masked, MPS_RM_PROT_INNER

    +

    + +mps_root_create_fmt, + +mps_root_create_table, + +mps_root_create_table_masked, + +MPS_RM_PROT_INNER

    -

    Notes

    +

    Notes

    -

    No page may contain parts of two or more roots with MPS_RM_PROT [how does one preventthat?]. You mustn't specify MPS_RM_PROT if the client program or anything other than (thisinstance of) the MPS is going to protect or unprotect the relevant pages.

    +

    No page may contain parts of two or more roots with MPS_RM_PROT [how does one prevent +that?]. You mustn't specify MPS_RM_PROT if the client program or +anything other than (this instance of) the MPS is going to protect or +unprotect the relevant pages.

    -

    Internal Notes

    +

    Internal Notes

    -

    Future meaning: The MPS may place a hardware read and/or write barrier on any pages whichany part of the root covers. Format methods and scanning functions (except for the one for thisroot) may not read or write data in this root. You may specify MPS_RM_PROT on a root allocatedfrom the MPS, as long as it's not from a GCd pool. - drj 1997-12-18

    +

    Future meaning: The MPS may place a hardware read and/or write +barrier on any pages which any part of the root covers. Format methods +and scanning functions (except for the one for thisroot) may not read +or write data in this root. You may specify MPS_RM_PROT on a root allocated from +the MPS, as long as it's not from a GCd pool. - drj 1997-12-18

    -

    This feature is far too technical for most of our clients: we should think about producingsome guidelines on how to use it. - pekka 1998-01-27

    +

    This feature is far too technical for most of our clients: we +should think about producing some guidelines on how to use it. - pekka +1998-01-27

    -

    There may be problems if the client wants the OS to access the root. Lots of OSes can't copewith writing to protected pages. So we'll need to document that caveat too. drj 1998-05-20

    +

    There may be problems if the client wants the OS to access the +root. Lots of OSes can't cope with writing to protected pages. So +we'll need to document that caveat too. drj 1998-05-20

    -

    MPS_RM_PROT_INNER

    +

    MPS_RM_PROT_INNER

    -

    Name

    +

    Name

    -

    MPS_RM_PROT_INNER

    +

    MPS_RM_PROT_INNER

    -

    Summary

    +

    Summary

    -

    MPS_RM_PROT_INNER is a constant used in root mode arguments to indicate partiallyprotectable roots.

    +

    MPS_RM_PROT_INNER is +a constant used in root mode arguments to indicate partially +protectable roots.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Root.

    +

    Root.

    -

    Type

    +

    Type

    -

    Integral constant.

    +

    Integral constant.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    MPS_RM_PROT_INNER is a preprocessor macro defining a constant that can be OR'ed to other MPS_RM_* contants, and passed as the root mode argument to certain root creation functions(mps_root_create_fmt, mps_root_create_table, mps_root_create_table_masked).

    +

    MPS_RM_PROT_INNER is +a preprocessor macro defining a constant that can be OR'ed with other +MPS_RM_* constants, and passed as the root mode argument +to certain root creation functions (mps_root_create_fmt, mps_root_create_table, +mps_root_create_table_masked).

    -

    Pas sing MPS_RM_PROT_INNER means that the MPS may place a hardware write barrier on anypages which are entirely covered by the root. Format methods and any scanning function (except forthe one for this root) may not write data in this root. They may read it.

    +

    Passing MPS_RM_PROT_INNER means that the +MPS may place a hardware write barrier on any pages which are entirely +covered by the root. Format methods and any scanning function (except +for the one for this root) may not write data in this root. They may +read it.

    -

    Example

    +

    Example

     res = mps_root_create_table(&mmRoot, arena, mps_rank_exact(),
@@ -1050,75 +1393,104 @@ res = mps_root_create_table(&mmRoot, arena, mps_rank_exact(),
    -

    See Also

    +

    See Also

    -

    mps_root_create_fmt, mps_root_create_table, mps_root_create_table_masked, MPS_RM_PROT

    +

    + +mps_root_create_fmt, + +mps_root_create_table, + +mps_root_create_table_masked, + +MPS_RM_PROT

    -

    Notes

    +

    Notes

    -

    To specify MPS_RM_PROT_INNER, you must also specify MPS_RM_PROT. The meaning of MPS_RM_PROT is overridden by MPS_RM_PROT_INNER.

    +

    To specify MPS_RM_PROT_INNER, you must also +specify MPS_RM_PROT. The +meaning of MPS_RM_PROT is +overridden by MPS_RM_PROT_INNER.

    -

    Internal Notes

    +

    Internal Notes

    -

    Future meaning: The MPS may place a hardware read and/or write barrier on any pages whichare entirely covered by the root. Format methods and scanning functions (except for the one for thisroot) may not read or write data in this root.

    +

    Future meaning: The MPS may place a hardware read and/or write +barrier on any pages which are entirely covered by the root. Format +methods and scanning functions (except for the one for this root) may +not read or write data in this root.

    -

    function mps_sac_alloc

    +

    function mps_sac_alloc

    -

    Name

    +

    Name

    -

    mps_sac_alloc

    +

    mps_sac_alloc

    -

    Summary

    +

    Summary

    -

    This function allocates a block using the segregated allocation cache given.

    +

    This function allocates a block using the segregated allocation +cache given.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Allocation cache

    +

    Allocation cache

    -

    Type

    +

    Type

    -

    mps_res_t mps_sac_alloc(mps_addr_t *p_o, mps_sac_t sac, size_t size, mps_bool_thas_reservoir_permit);

    +

    mps_res_t mps_sac_alloc(mps_addr_t *p_o, mps_sac_t sac, size_t size, mps_bool_t has_reservoir_permit);

    -

    Arguments

    +

    Arguments

    -

    p_o a pointer to a variable to hold the address of the new block

    +

    p_o a pointer to a variable to hold the address of the new block

    -

    sac the segregated allocation cache

    +

    sac the segregated allocation cache

    -

    size the size of the block requested

    +

    size the size of the block requested

    -

    has_reservoir_permit regulates access to the reservoir

    +

    has_reservoir_permit regulates access to the reservoir

    -

    Returned Values

    +

    Returned Values

    -

    If the return value is MPS_RES_OK, the address of a new block in *p_o .

    +

    If the return value is MPS_RES_OK, the address of a new block +is *p_o .

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This function allocates a block using the cache given. If no suitable block exists in the cache, it will ask for more memory from the associated pool. size does not have to beone of the class sizes of the cache; it does not have to be aligned.

    +

    This function allocates a block using the cache given. If no +suitable block exists in the cache, it will ask for more memory from +the associated pool. size does not have to be one of the +class sizes of the cache; it does not have to be aligned.

    -

    The client is responsible for synchronising the access to the cache, but if the cachedecides to access the pool, the MPS will properly synchronize with any other threads that might beaccessing the same pool.

    +

    The client is responsible for synchronising the access to the +cache, but if the cache decides to access the pool, the MPS will +properly synchronize with any other threads that might be accessing +the same pool.

    -

    has_reservoir_permit regulates whether the pool has permission to get morememory from the reservoir to satisfy this request.

    +

    has_reservoir_permit regulates whether the pool has +permission to get more memory from the reservoir to satisfy this +request.

    -

    Example

    +

    Example

       void *p;
@@ -1137,49 +1509,91 @@ res = mps_root_create_table(&mmRoot, arena, mps_rank_exact(),
    -

    Error Handling

    +

    Error Handling

    -

    mps_sac_alloc returns MPS_RES_MEMORY when it fails to find enough memory; see the documentation for this return code for recovery options. It returns MPS_RES_COMMIT_LIMIT if it can't allocate without exceeding the arena commit limit; Free something to make more space or increase the limit using mps_arena_commit_limit_set. It returns MPS_RES_RESOURCE if it has run outof swap space; Free something or terminate other processes on the same machine.

    +

    mps_sac_alloc returns +MPS_RES_MEMORY when it +fails to find enough memory; see the documentation for this return +code for recovery options. It returns MPS_RES_COMMIT_LIMIT if it +can't allocate without exceeding the arena commit limit; Free +something to make more space or increase the limit using mps_arena_commit_limit_set. It +returns MPS_RES_RESOURCE +if it has run out of swap space; Free something or terminate other +processes on the same machine.

    -

    See Also

    +

    See Also

    -

    MPS_SAC_ALLOC_FAST, mps_sac_free, MPS_SAC_FREE_FAST, mps_sac_t, mps_reservoir_limit_set, mps_arena_commit_limit_set, MPS_RES_MEMORY, MPS_RES_COMMIT_LIMIT, MPS_RES_RESOURCE

    +

    + +MPS_SAC_ALLOC_FAST, + +mps_sac_free, + +MPS_SAC_FREE_FAST, + +mps_sac_t, + +mps_reservoir_limit_set, + +mps_arena_commit_limit_set, + +MPS_RES_MEMORY, + +MPS_RES_COMMIT_LIMIT, + +MPS_RES_RESOURCE

    -

    Notes

    +

    Notes

    -

    There's also a macro called MPS_SAC_ALLOC_FAST, that does the same thing. Themacro is faster, but generates more code and does less checking.

    +

    There's also a macro called MPS_SAC_ALLOC_FAST, that does +the same thing. The macro is faster, but generates more code and does +less checking.

    -

    The block allocated can be larger than requested. Blocks not matching any class size areallocated from the next largest class, and blocks larger than the largest class size are simplyallocated at the requested size (rounded up to alignment, as usual).

    +

    The block allocated can be larger than requested. Blocks not +matching any class size are allocated from the next largest class, and +blocks larger than the largest class size are simply allocated at the +requested size (rounded up to alignment, as usual).

    -

    Objects allocated through a segregated allocation cache should only be freed through a segregated allocation cache with the same class structure. Using mps_free on them can cause memory leaks, because the size of the block might be larger than you think. Naturally, the cache must also be attached to the same pool.

    +

    Objects allocated through a segregated allocation cache should only +be freed through a segregated allocation cache with the same class +structure. Using mps_free on +them can cause memory leaks, because the size of the block might be +larger than you think. Naturally, the cache must also be attached to +the same pool.

    -

    macro MPS_SAC_ALLOC_FAST

    +

    macro MPS_SAC_ALLOC_FAST

    -

    Name

    +

    Name

    -

    MPS_SAC_ALLOC_FAST

    +

    MPS_SAC_ALLOC_FAST

    -

    Summary

    +

    Summary

    -

    This macro allocates a block using the segregated allocation cache given.

    +

    This macro allocates a block using the segregated allocation cache +given.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Allocation cache

    +

    Allocation cache

    -

    Syntax

    +

    Syntax

    -

    MPS_SAC_ALLOC_FAST(res_o, p_o, sac, size, has_reservoir_permit)

    +

    MPS_SAC_ALLOC_FAST(res_o, p_o, sac, size, has_reservoir_permit)

    -

    Arguments

    +

    Arguments

    @@ -1236,26 +1650,36 @@ res = mps_root_create_table(&mmRoot, arena, mps_rank_exact(),
    -

    Returned Values

    +

    Returned Values

    -

    res_o will be set to the return code. If this is MPS_RES_OK, the address of the new block is in p_o.

    +

    res_o will be set to the return code. If this is +MPS_RES_OK, the address of the +new block is in p_o.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This macro allocates a block using the cache given. If no suitable block exists in the cache, it will ask for more memory from the associated pool. size does not have to be one of the class sizes of the cache; it does not have to be aligned.

    +

    This macro allocates a block using the cache given. If no suitable +block exists in the cache, it will ask for more memory from the +associated pool. size does not have to be one of the +class sizes of the cache; it does not have to be aligned.

    -

    The client is responsible for synchronizing the access to the cache, but if the cache decides to access the pool, the MPS will properly synchronize with any other threads that might be accessing the same pool.

    +

    The client is responsible for synchronizing the access to the +cache, but if the cache decides to access the pool, the MPS will +properly synchronize with any other threads that might be accessing +the same pool.

    -

    has_reservoir_permit regulates whether the pool has permission to get more memory from the reservoir to satisfy this request.

    +

    has_reservoir_permit regulates whether the pool has +permission to get more memory from the reservoir to satisfy this +request.

    -

    Example

    +

    Example

       void *p;
@@ -1275,67 +1699,108 @@ res = mps_root_create_table(&mmRoot, arena, mps_rank_exact(),
    -

    Error Handling

    +

    Error Handling

    -

    MPS_SAC_ALLOC_FAST returns MPS_RES_MEMORY when it fails to find enoughmemory; see the documentation for this return code for recovery options. It returns MPS_RES_COMMIT_LIMIT if it can't allocate without exceeding the arena commit limit;Free something to make more space or increase the limit using mps_arena_commit_limit_set. It returns MPS_RES_RESOURCE if it has run out of swap space; Free something or terminate other processes on the same machine.

    +

    MPS_SAC_ALLOC_FAST +returns MPS_RES_MEMORY when +it fails to find enough memory; see the documentation for this return +code for recovery options. It returns MPS_RES_COMMIT_LIMIT if it +can't allocate without exceeding the arena commit limit; free something +to make more space or increase the limit using mps_arena_commit_limit_set. It +returns MPS_RES_RESOURCE +if it has run out of swap space; free something or terminate other +processes on the same machine.

    -

    See Also

    +

    See Also

    -

    mps_sac_alloc, MPS_SAC_FREE_FAST, mps_sac_free, mps_sac_t, mps_reservoir_limit_set,mps_arena_commit_limit_set, MPS_RES_MEMORY, MPS_RES_COMMIT_LIMIT, MPS_RES_RESOURCE

    +

    + +mps_sac_alloc, + +MPS_SAC_FREE_FAST, + +mps_sac_free, + +mps_sac_t, + +mps_reservoir_limit_set, + +mps_arena_commit_limit_set, + +MPS_RES_MEMORY, + +MPS_RES_COMMIT_LIMIT, + +MPS_RES_RESOURCE

    -

    Notes

    +

    Notes

    -

    There's also a function called mps_sac_alloc, that does the same thing.

    +

    There's also a function called mps_sac_alloc, that does the same +thing.

    -

    The block allocated can be larger than requested. Blocks not matching any class size areallocated from the next largest class, and blocks larger than the largest class size are simplyallocated at the requested size (rounded up to alignment, as usual).

    +

    The block allocated can be larger than requested. Blocks not +matching any class size are allocated from the next largest class, and +blocks larger than the largest class size are simply allocated at the +requested size (rounded up to alignment, as usual).

    -

    Objects allocated through a segregated allocation cache should only be freed through asegregated allocation cache with the same class structure. Using mps_free on them cancause memory leaks or assertions, because the size of the block might be larger than you think.Naturally, the cache must also be attached to the same pool.

    +

    Objects allocated through a segregated allocation cache should only +be freed through a segregated allocation cache with the same class +structure. Using mps_free on them +can cause memory leaks or assertions, because the size of the block +might be larger than you think. Naturally, the cache must also be +attached to the same pool.

    -

    The macro doesn't evaluate has_reservoir_permit, unless it decides to accessthe pool.

    +

    The macro doesn't evaluate has_reservoir_permit, +unless it decides to access the pool.

    -

    constant MPS_SAC_CLASS_LIMIT

    +

    constant MPS_SAC_CLASS_LIMIT

    -

    Name

    +

    Name

    -

    MPS_SAC_CLASS_LIMIT

    +

    MPS_SAC_CLASS_LIMIT

    -

    Summary

    +

    Summary

    -

    MPS_SAC_CLASS_LIMIT specifies how many classes mps_sac_create is guaranteed to accept.

    +

    MPS_SAC_CLASS_LIMIT specifies how many classes mps_sac_create is guaranteed to accept.

    -

    Type

    +

    Type

    -

    size_t

    +

    size_t

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Allocation cache

    +

    Allocation cache

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    MPS_SAC_CLASS_LIMIT specifies a lower limit on the maximum number of classesthat can be described in a call to mps_sac_create, i.e., the MPS guarantees to acceptat least this many classes. More might be accepted -- in fact, there might not be any limit in theimplementation on the maximum number of classes, but if you specify more than this, you should beprepared to handle the error.

    +

    MPS_SAC_CLASS_LIMIT specifies a lower limit on the maximum number of classesthat can be described in a call to mps_sac_create, i.e., the MPS guarantees to acceptat least this many classes. More might be accepted -- in fact, there might not be any limit in theimplementation on the maximum number of classes, but if you specify more than this, you should beprepared to handle the error.

    -

    MPS_SAC_CLASS_LIMIT is a macro suitable for use in a constant expression, bothin a #if directive and wherever else constant expressions may be used.

    +

    MPS_SAC_CLASS_LIMIT is a macro suitable for use in a constant expression, bothin a #if directive and wherever else constant expressions may be used.

    -

    Example

    +

    Example

       mps_sac_t sac;
-  mps_sac_classes_s classes[3] = { {8, 38, 1}, {136, 19, 3}, {512, 4, 1} };
+  mps_sac_class_s classes[3] = { {8, 38, 1}, {136, 19, 3}, {512, 4, 1} };
 
 #if (MPS_SAC_CLASS_LIMIT < 3)
 #  error "Too many classes!"
@@ -1349,59 +1814,61 @@ res = mps_root_create_table(&mmRoot, arena, mps_rank_exact(),
    -

    See Also

    +

    See Also

    -

    mps_sac_create

    +

    + +mps_sac_create

    -

    Notes

    +

    Notes

    -

    If you ask for too many size classes, mps_sac_create returns MPS_RES_LIMIT; you can recover by combining some small adjacent classes.

    +

    If you ask for too many size classes, mps_sac_create returns MPS_RES_LIMIT; you can recover by combining some small adjacent classes.

    -

    function mps_sac_free

    +

    function mps_sac_free

    -

    Name

    +

    Name

    -

    mps_sac_free

    +

    mps_sac_free

    -

    Summary

    +

    Summary

    -

    This function frees an object using the segregated allocation cache given.

    +

    This function frees an object using the segregated allocation cache given.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Allocation cache

    +

    Allocation cache

    -

    Type

    +

    Type

    -

    void mps_sac_free(mps_sac_t sac, mps_addr_t p, size_t size);

    +

    void mps_sac_free(mps_sac_t sac, mps_addr_t p, size_t size);

    -

    Arguments

    +

    Arguments

    -

    sac the segregated allocation cache

    +

    sac the segregated allocation cache

    -

    p a pointer to the block being freed

    +

    p a pointer to the block being freed

    -

    size the size of the block being freed

    +

    size the size of the block being freed

    -

    Returned Values

    +

    Returned Values

    -

    None.

    +

    None.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    This function frees an object using the cache given. If the cache would become too full,some blocks are returned to the associated pool. @@ -1409,10 +1876,10 @@ res = mps_root_create_table(&mmRoot, arena, mps_rank_exact(), should be the size that wasspecified when the object was allocated (the cache knows what the real size of the block is). Theobject must have been allocated through a segregated allocation cache with the same class structure,attached to the same pool.

    -

    The client is responsible for synchronising the access to the cache, but if the cachedecides to access the pool, the MPS will properly synchronize with any other threads that might beaccessing the same pool.

    +

    The client is responsible for synchronising the access to the cache, but if the cachedecides to access the pool, the MPS will properly synchronize with any other threads that might beaccessing the same pool.

    -

    Example

    +

    Example

       void *p;
@@ -1431,44 +1898,52 @@ res = mps_root_create_table(&mmRoot, arena, mps_rank_exact(),
    -

    See Also

    +

    See Also

    -

    MPS_SAC_FREE_FAST, mps_sac_alloc, MPS_SAC_ALLOC_FAST, mps_sac_t

    +

    + +MPS_SAC_FREE_FAST, + +mps_sac_alloc, + +MPS_SAC_ALLOC_FAST, + +mps_sac_t

    -

    Notes

    +

    Notes

    -

    Usually, you'd use the same cache to allocate and deallocate an object.

    +

    Usually, you'd use the same cache to allocate and deallocate an object.

    -

    There's also a macro called MPS_SAC_FREE_FAST, that does the same thing. The macro is faster, but generates more code and does no checking.

    +

    There's also a macro called MPS_SAC_FREE_FAST, that does the same thing. The macro is faster, but generates more code and does no checking.

    -

    Note that mps_sac_free does very little checking; it's optimized for speed.Double frees and other mistakes will only be detected when the cache is flushed (which can happen bydemand through mps_sac_flush or automatically), unless intervening operations have obscured symptom.

    +

    Note that mps_sac_free does very little checking; it's optimized for speed.Double frees and other mistakes will only be detected when the cache is flushed (which can happen bydemand through mps_sac_flush or automatically), unless intervening operations have obscured symptom.

    -

    macro MPS_SAC_FREE_FAST

    +

    macro MPS_SAC_FREE_FAST

    -

    Name

    +

    Name

    -

    MPS_SAC_FREE_FAST

    +

    MPS_SAC_FREE_FAST

    -

    Summary

    +

    Summary

    -

    MPS_SAC_FREE_FAST frees an object using the segregated allocation cache given.

    +

    MPS_SAC_FREE_FAST frees an object using the segregated allocation cache given.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Allocation cache

    +

    Allocation cache

    -

    Syntax

    +

    Syntax

    -

    MPS_SAC_FREE_FAST(sac, p, size)

    +

    MPS_SAC_FREE_FAST(sac, p, size)

    -

    Arguments

    +

    Arguments

    @@ -1507,17 +1982,17 @@ res = mps_root_create_table(&mmRoot, arena, mps_rank_exact(),
    -

    Returned Values

    +

    Returned Values

    -

    None.

    +

    None.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    This macro frees an object using the cache given. If the cache would become too full, someblocks are returned to the associated pool. @@ -1525,10 +2000,10 @@ res = mps_root_create_table(&mmRoot, arena, mps_rank_exact(), should be the size that was specifiedwhen the object was allocated (the cache knows what the real size of the block is). The objects musthave been allocated through a segregated allocation cache with the same class structure, attachedto the same pool.

    -

    The client is responsible for synchronizing the access to the cache, but if the cachedecides to access the pool, the MPS will properly synchronize with any other threads that might beaccessing the same pool.

    +

    The client is responsible for synchronizing the access to the cache, but if the cachedecides to access the pool, the MPS will properly synchronize with any other threads that might beaccessing the same pool.

    -

    Example

    +

    Example

       void *p;
@@ -1548,59 +2023,67 @@ res = mps_root_create_table(&mmRoot, arena, mps_rank_exact(),
    -

    See Also

    +

    See Also

    -

    mps_sac_free, MPS_SAC_ALLOC_FAST, mps_sac_alloc, mps_sac_t

    +

    + +mps_sac_free, + +MPS_SAC_ALLOC_FAST, + +mps_sac_alloc, + +mps_sac_t

    -

    Notes

    +

    Notes

    -

    Usually, you'd use the same cache to allocate and deallocate an object.

    +

    Usually, you'd use the same cache to allocate and deallocate an object.

    -

    There's also a function called mps_sac_free, that does the same thing. Themacro is faster, but generates more code and does no checking.

    +

    There's also a function called mps_sac_free, that does the same thing. Themacro is faster, but generates more code and does no checking.

    -

    Note that MPS_SAC_FREE_FAST doesn't do any checking; it's optimized for speed. Double frees and other mistakes will only be detected when the cache is flushed (which can happen by demand through mps_sac_flush or automatically), unless intervening operations have obscured symptom.

    +

    Note that MPS_SAC_FREE_FAST doesn't do any checking; it's optimized for speed. Double frees and other mistakes will only be detected when the cache is flushed (which can happen by demand through mps_sac_flush or automatically), unless intervening operations have obscured symptom.

    -

    macro MPS_SCAN_BEGIN

    +

    macro MPS_SCAN_BEGIN

    -

    Name

    +

    Name

    -

    MPS_SCAN_BEGIN

    +

    MPS_SCAN_BEGIN

    -

    Summary

    +

    Summary

    -

    The macro MPS_SCAN_BEGIN is part of the scanning protocol; together with MPS_SCAN_END, it sets up local information used by MPS_FIX*.

    +

    The macro MPS_SCAN_BEGIN is part of the scanning protocol; together with MPS_SCAN_END, it sets up local information used by MPS_FIX*.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Scanning.

    +

    Scanning.

    -

    Syntax

    +

    Syntax

    -

    MPS_SCAN_BEGIN(ss)

    +

    MPS_SCAN_BEGIN(ss)

    -

    Arguments

    +

    Arguments

    -

    ss the scan state argument that was passed to the scanning function

    +

    ss the scan state argument that was passed to the scanning function

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This macro is used in the scanning protocol. Together with MPS_SCAN_END, it sets up local information used by the fast MPS_FIX* macros.

    +

    This macro is used in the scanning protocol. Together with MPS_SCAN_END, it sets up local information used by the fast MPS_FIX* macros.

    -

    Example

    +

    Example

     mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length)
@@ -1622,55 +2105,65 @@ mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length)
    -

    See Also

    +

    See Also

    -

    MPS_SCAN_END, MPS_FIX12, MPS_FIX1, MPS_FIX2, MPS_FIX_CALL

    +

    + +MPS_SCAN_END, + +MPS_FIX12, + +MPS_FIX1, + +MPS_FIX2, + +MPS_FIX_CALL

    -

    Notes

    +

    Notes

    -

    Between MPS_SCAN_BEGIN and MPS_SCAN_END, you may not call another scanning functiondirectly, because the scan state parameter is in a strange state, so you shouldn't pass it as anargument to a function. However, you can pass the scan state using MPS_FIX_CALL. You also cannotnest MPS_SCAN_BEGIN textually within another MPS_SCAN_BEGIN -- MPS_SCAN_END pair.

    +

    Between MPS_SCAN_BEGIN and MPS_SCAN_END, you may not call another scanning functiondirectly, because the scan state parameter is in a strange state, so you shouldn't pass it as anargument to a function. However, you can pass the scan state using MPS_FIX_CALL. You also cannotnest MPS_SCAN_BEGIN textually within another MPS_SCAN_BEGIN -- MPS_SCAN_END pair.

    -

    macro MPS_SCAN_END

    +

    macro MPS_SCAN_END

    -

    Name

    +

    Name

    -

    MPS_SCAN_END

    +

    MPS_SCAN_END

    -

    Summary

    +

    Summary

    -

    The macro MPS_SCAN_END is part of the scanning protocol; it terminates a blockstarted by MPS_SCAN_BEGIN.

    +

    The macro MPS_SCAN_END is part of the scanning protocol; it terminates a blockstarted by MPS_SCAN_BEGIN.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Scanning.

    +

    Scanning.

    -

    Syntax

    +

    Syntax

    -

    MPS_SCAN_END(ss);

    +

    MPS_SCAN_END(ss);

    -

    Arguments

    +

    Arguments

    -

    ss the scan state argument that was passed to the scanning function

    +

    ss the scan state argument that was passed to the scanning function

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This macro is used in the scanning protocol. Together with MPS_SCAN_BEGIN, itsets up local information used by the fast MPS_FIX* macros. Note that MPS_SCAN_END completes the scanning, so successful termination of the scanning mustinvoke it (error branches can return without passing through).

    +

    This macro is used in the scanning protocol. Together with MPS_SCAN_BEGIN, itsets up local information used by the fast MPS_FIX* macros. Note that MPS_SCAN_END completes the scanning, so successful termination of the scanning mustinvoke it (error branches can return without passing through).

    -

    Example

    +

    Example

     mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length) {
@@ -1691,162 +2184,183 @@ mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length) {
    -

    See Also

    +

    See Also

    -

    MPS_SCAN_BEGIN, MPS_FIX12, MPS_FIX1, MPS_FIX2, MPS_FIX_CALL

    +

    +MPS_SCAN_BEGIN, -

    Notes

    +MPS_FIX12, -

    Between MPS_SCAN_BEGIN and MPS_SCAN_END, you may not call another scanning functiondirectly, because the scan state parameter is in a strange state, so you shouldn't pass it as anargument to a function. However, you can pass the scan state using MPS_FIX_CALL.

    +MPS_FIX1, +MPS_FIX2, -

    type MPS_T_WORD

    +MPS_FIX_CALL

    -

    Name

    +

    Notes

    -

    MPS_T_WORD

    +

    Between MPS_SCAN_BEGIN and MPS_SCAN_END, you may not call another scanning functiondirectly, because the scan state parameter is in a strange state, so you shouldn't pass it as anargument to a function. However, you can pass the scan state using MPS_FIX_CALL.

    -

    Summary

    +

    type MPS_T_WORD

    -

    MPS_T_WORD an unsigned integral type that is the same size as an object pointer.

    +

    Name

    -

    Resources

    +

    MPS_T_WORD

    -

    mpstd.h.

    +

    Summary

    -

    Description

    +

    MPS_T_WORD an unsigned integral type that is the same size as an object pointer.

    -

    MPS_T_WORD is a preprocessor macro defined in "mpstd.h". It is the name of an unsignedintegral type that is the same size as an object pointer (so sizeof(MPS_T_WORD) == sizeof(void*)).The exact identity of the type is platform-dependent.

    +

    Resources

    -

    Example

    +

    mpstd.h.

    -

    See Also

    +

    Description

    -

    MPS_WORD_SHIFT, MPS_WORD_WIDTH

    +

    MPS_T_WORD is a preprocessor macro defined in "mpstd.h". It is the name of an unsignedintegral type that is the same size as an object pointer (so sizeof(MPS_T_WORD) == sizeof(void*)).The exact identity of the type is platform-dependent.

    -

    constant MPS_WORD_SHIFT

    +

    Example

    -

    Name

    +

    See Also

    -

    MPS_WORD_SHIFT

    +

    +MPS_WORD_SHIFT, -

    Summary

    +MPS_WORD_WIDTH

    -

    MPS_WORD_SHIFT is log base 2 of MPS_WORD_WIDTH.

    +

    constant MPS_WORD_SHIFT

    -

    Type

    -

    Integral constant.

    +

    Name

    +

    MPS_WORD_SHIFT

    -

    Resources

    -

    mpstd.h.

    +

    Summary

    +

    MPS_WORD_SHIFT is log base 2 of MPS_WORD_WIDTH.

    -

    Description

    -

    MPS_WORD_SHIFT is a preprocessor macro defined in "mpstd.h". It is the logarithm in base 2 of MPS_WORD_WIDTH (so 1 << MPS_WORD_SHIFT == MPS_WORD_WIDTH). The value of MPS_WORD_SHIFT is platform-dependent. Typical values are 5 and 6.

    +

    Type

    +

    Integral constant.

    -

    Example

    +

    Resources

    +

    mpstd.h.

    -

    See Also

    -

    MPS_T_WORD, MPS_WORD_WIDTH

    +

    Description

    +

    MPS_WORD_SHIFT is a preprocessor macro defined in "mpstd.h". It is the logarithm in base 2 of MPS_WORD_WIDTH (so 1 << MPS_WORD_SHIFT == MPS_WORD_WIDTH). The value of MPS_WORD_SHIFT is platform-dependent. Typical values are 5 and 6.

    -

    constant MPS_WORD_WIDTH

    +

    Example

    -

    Name

    -

    MPS_WORD_WIDTH

    +

    See Also

    +

    -

    Summary

    +MPS_T_WORD, -

    MPS_WORD_WIDTH is the width in bits of the type MPS_T_WORD.

    +MPS_WORD_WIDTH

    -

    Type

    +

    constant MPS_WORD_WIDTH

    -

    Integral constant.

    +

    Name

    -

    Resources

    +

    MPS_WORD_WIDTH

    -

    mpstd.h.

    +

    Summary

    -

    Description

    +

    MPS_WORD_WIDTH is the width in bits of the type MPS_T_WORD.

    -

    MPS_WORD_WIDTH is a preprocessor macro defined in "mpstd.h" to be the width in bits of the type MPS_T_WORD (so MPS_WORD_WIDTH == sizeof(MPS_T_WORD) * CHAR_BIT).

    -

    This value is required for the use of the MPS C interface and the interpretation of "mps.h".It is platform-dependent. It is a power of 2; typical values are 32 and 64. It may be defined byincluding "mpstd.h" on a supported platform, or by defining it to be the width of MPS_T_WORD inbits.

    +

    Type

    +

    Integral constant.

    -

    Example

    + +

    Resources

    + +

    mpstd.h.

    + + +

    Description

    + +

    MPS_WORD_WIDTH is a preprocessor macro defined in "mpstd.h" to be the width in bits of the type MPS_T_WORD (so MPS_WORD_WIDTH == sizeof(MPS_T_WORD) * CHAR_BIT).

    + +

    This value is required for the use of the MPS C interface and the interpretation of "mps.h".It is platform-dependent. It is a power of 2; typical values are 32 and 64. It may be defined byincluding "mpstd.h" on a supported platform, or by defining it to be the width of MPS_T_WORD inbits.

    + + +

    Example

     #define MPS_WORD_WIDTH 32
    -

    See Also

    +

    See Also

    -

    MPS_T_WORD, MPS_WORD_SHIFT

    +

    + +MPS_T_WORD, + +MPS_WORD_SHIFT

    -

    type mps_addr_t

    +

    type mps_addr_t

    -

    Name

    +

    Name

    -

    mps_addr_t

    +

    mps_addr_t

    -

    Summary

    +

    Summary

    -

    mps_addr_t is the type of addresses managed by the MPS, and also the type of references too bjects.

    +

    mps_addr_t is the type of addresses managed by the MPS, and also the type of references too bjects.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Allocation, allocation point, format, root, location dependency.

    +

    Allocation, allocation point, format, root, location dependency.

    -

    Type

    +

    Type

    -

    typedef void *mps_addr_t;

    +

    typedef void *mps_addr_t;

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_addr_t is the type of addresses managed by the MPS, and also the type of referencesto objects. It is used in the MPS C interface where the MPS needs to pass a pointer to memory thatis under the control of the MPS.

    +

    mps_addr_t is the type of addresses managed by the MPS, and also the type of referencesto objects. It is used in the MPS C interface where the MPS needs to pass a pointer to memory thatis under the control of the MPS.

    -

    In accordance with standard C practice, the value NULL of type mps_addr_t will never beused to represent the address of an object.

    +

    In accordance with standard C practice, the value NULL of type mps_addr_t will never beused to represent the address of an object.

    -

    Example

    +

    Example

     {
@@ -1863,54 +2377,56 @@ mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length) {
    -

    Error Handling

    +

    Error Handling

    -

    Not applicable.

    +

    Not applicable.

    -

    See Also

    +

    See Also

    -

    mps_align_t

    +

    + +mps_align_t

    -

    type mps_align_t

    +

    type mps_align_t

    -

    Name

    +

    Name

    -

    mps_align_t

    +

    mps_align_t

    -

    Summary

    +

    Summary

    -

    mps_align_t is the type of an alignment.

    +

    mps_align_t is the type of an alignment.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format, pool, allocation.

    +

    Format, pool, allocation.

    -

    Type

    +

    Type

    -

    typedef size_t mps_align_t;

    +

    typedef size_t mps_align_t;

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    An alignment specifies the address modulus to which all objects in an object format must bealigned. That is, if an alignment of 4 is specified, then the address of any object in that formatmodulo 4 will always be 0.

    +

    An alignment specifies the address modulus to which all objects in an object format must bealigned. That is, if an alignment of 4 is specified, then the address of any object in that formatmodulo 4 will always be 0.

    -

    mps_align_t is a transparent type equivalent to the C type "size_t" and must be a positivepower of 2.

    +

    mps_align_t is a transparent type equivalent to the C type "size_t" and must be a positivepower of 2.

    -

    Some pools and allocation protocols accept an alignment as an option that can be used toensure that objects in the pool or objects allocated observe a stricter alignment than that of theobject format.

    +

    Some pools and allocation protocols accept an alignment as an option that can be used toensure that objects in the pool or objects allocated observe a stricter alignment than that of theobject format.

    -

    Example

    +

    Example

     mps_align_t floatAlign = 4;
@@ -1918,61 +2434,65 @@ mps_align_t doubleFloatAlign = 8;
    -

    See Also

    +

    See Also

    -

    mps_fmt_A_t, mps_addr_t

    +

    + +mps_fmt_A_t, + +mps_addr_t

    -

    function mps_alloc

    +

    function mps_alloc

    -

    Name

    +

    Name

    -

    mps_alloc

    +

    mps_alloc

    -

    Summary

    +

    Summary

    -

    mps_alloc allocates a block of memory in a pool.

    +

    mps_alloc allocates a block of memory in a pool.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Allocation.

    +

    Allocation.

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_alloc(mps_addr_t *p, mps_pool_t pool, size_t size, ...);

    +

    mps_res_t mps_alloc(mps_addr_t *p, mps_pool_t pool, size_t size, ...);

    -

    Arguments

    +

    Arguments

    -

    p output parameter for a pointer to the block allocated

    +

    p output parameter for a pointer to the block allocated

    -

    pool the pool to allocate in

    +

    pool the pool to allocate in

    -

    size the size of the block to allocate in bytes

    +

    size the size of the block to allocate in bytes

    -

    ... (some pools can take additional arguments)

    +

    ... (some pools can take additional arguments)

    -

    Returned Values

    +

    Returned Values

    -

    A return code.

    +

    A return code.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_alloc allocates a block of memory in the given pool.

    +

    mps_alloc allocates a block of memory in the given pool.

    -

    Example

    +

    Example

       mps_res_t res;
@@ -1989,55 +2509,57 @@ mps_align_t doubleFloatAlign = 8;
    -

    Error Handling

    +

    Error Handling

    -

    See Also

    +

    See Also

    -

    mps_free

    +

    + +mps_free

    -

    mps_alloc_pattern_ramp

    +

    mps_alloc_pattern_ramp

    -

    Name

    +

    Name

    -

    mps_alloc_pattern_ramp

    +

    mps_alloc_pattern_ramp

    -

    Summary

    +

    Summary

    -

    Returns a allocation pattern type indicating that allocation will follow a ramp pattern.

    +

    Returns a allocation pattern type indicating that allocation will follow a ramp pattern.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    alloc-pattern-ramp

    +

    alloc-pattern-ramp

    -

    Syntax

    +

    Syntax

    -

    mps_alloc_pattern_t mps_alloc_pattern_ramp();

    +

    mps_alloc_pattern_t mps_alloc_pattern_ramp();

    -

    Arguments

    +

    Arguments

    -

    none

    +

    none

    -

    Returned Values

    +

    Returned Values

    -

    Returns the allocation pattern type for ramps.

    +

    Returns the allocation pattern type for ramps.

    -

    Description

    +

    Description

    -

    When declaring an allocation pattern for an AP, if the calls to mps_ap_alloc_pattern_begin use ramp allocation patterns (such as the result of mps_alloc_pattern_ramp), then the MPS willtake this as an indication that most of the objects allocated after the call to mps_ap_alloc_pattern_begin are likely to be dead by the corresponding call to mps_ap_alloc_pattern_end.

    +

    When declaring an allocation pattern for an AP, if the calls to mps_ap_alloc_pattern_begin use ramp allocation patterns (such as the result of mps_alloc_pattern_ramp), then the MPS willtake this as an indication that most of the objects allocated after the call to mps_ap_alloc_pattern_begin are likely to be dead by the corresponding call to mps_ap_alloc_pattern_end.

    -

    This permits the client to indicate useful points for GC with minimal perturbation of the GCstrategy.

    +

    This permits the client to indicate useful points for GC with minimal perturbation of the GCstrategy.

    -

    Example

    +

    Example

     {
@@ -2048,62 +2570,68 @@ mps_align_t doubleFloatAlign = 8;
    -

    Error Handling

    +

    Error Handling

    -

    Cannot fail.

    +

    Cannot fail.

    -

    See Also

    +

    See Also

    -

    mps_alloc_pattern_ramp_collect_all, mps_ap_alloc_pattern_begin

    +

    + +mps_alloc_pattern_ramp_collect_all, + +mps_ap_alloc_pattern_begin

    -

    Notes

    +

    Notes

    -

    mps_alloc_pattern_ramp_collect_all

    +

    mps_alloc_pattern_ramp_collect_all

    -

    Name

    +

    Name

    -

    mps_alloc_pattern_ramp_collect_all

    +

    mps_alloc_pattern_ramp_collect_all

    -

    Summary

    +

    Summary

    -

    Returns a ramp allocation pattern type indicating that a full GC should be done.

    +

    Returns a ramp allocation pattern type indicating that a full GC should be done.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    GC, AP, ramps

    +

    GC, AP, ramps

    -

    Syntax

    +

    Syntax

    -

    mps_alloc_pattern_t mps_alloc_pattern_ramp_collect_all();

    +

    mps_alloc_pattern_t mps_alloc_pattern_ramp_collect_all();

    -

    Arguments

    +

    Arguments

    -

    none

    +

    none

    -

    Returned Values

    +

    Returned Values

    -

    Returns the allocation pattern type for full collection ramps.

    +

    Returns the allocation pattern type for full collection ramps.

    -

    Description

    +

    Description

    -

    This yields an allocation pattern for an AP that is similar to that returned by mps_alloc_pattern_ramp, in that it declares a ramp allocation pattern, but additionally indicates tothe MPS that the next collection following the ramp should be a full GC.

    +

    This yields an allocation pattern for an AP that is similar to that returned by mps_alloc_pattern_ramp, in that it declares a ramp allocation pattern, but additionally indicates tothe MPS that the next collection following the ramp should be a full GC.

    -

    This permits the client to indicate useful points for a full GC, either because most of theheap is likely to be dead, or because accurate statistics are required, with minimal perturbation ofthe GC strategy.

    +

    This permits the client to indicate useful points for a full GC, either because most of theheap is likely to be dead, or because accurate statistics are required, with minimal perturbation ofthe GC strategy.

    -

    As usual, this allocation pattern should be used in matching mps_ap_alloc_pattern_begin and mps_ap_alloc_pattern_end pairs. It may nest with, but should not otherwise overlap with allocationpatterns of type mps_alloc_pattern_ramp. In this case, the MPS may defer the full GC until after allramp allocation patterns have ended.

    +

    As usual, this allocation pattern should be used in matching mps_ap_alloc_pattern_begin and mps_ap_alloc_pattern_end pairs. It may nest with, but should not otherwise overlap with allocationpatterns of type mps_alloc_pattern_ramp. In this case, the MPS may defer the full GC until after allramp allocation patterns have ended.

    -

    Example

    +

    Example

     {
@@ -2115,152 +2643,164 @@ mps_align_t doubleFloatAlign = 8;
    +

    Error Handling

    -

    Error Handling

    +

    Cannot fail.

    -

    Cannot fail.

    +

    See Also

    -

    See Also

    +

    -

    mps_alloc_pattern_ramp, mps_ap_alloc_pattern_begin

    +mps_alloc_pattern_ramp, +mps_ap_alloc_pattern_begin

    -

    Notes

    +

    Notes

    -

    Internal Notes

    +

    Internal Notes

    -

    mps_amc_apply

    +

    mps_amc_apply

    -

    Name

    +

    Name

    -

    mps_amc_apply

    +

    mps_amc_apply

    -

    Summary

    +

    Summary

    -

    mps_amc_apply is used to inspect objects in an AMC pool. You may only call it when thearena is parked (for example, after mps_arena_collect).

    +

    mps_amc_apply is used to inspect objects in an AMC pool. You may only call it when thearena is parked (for example, after mps_arena_collect).

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Arena.

    +

    Arena.

    -

    Syntax

    +

    Syntax

    -

    extern void mps_amc_apply(mps_pool_t, void(*f)(mps_addr_t, void *, size_t), void *, size_t);

    +

    extern void mps_amc_apply(mps_pool_t, void(*f)(mps_addr_t, void *, size_t), void *, size_t);

    -

    Arguments

    +

    Arguments

    -

    mps_pool_t the pool whose objects you want to inpect

    +

    mps_pool_t the pool whose objects you want to inpect

    -

    f a supplied function

    +

    f a supplied function

    -

    mps_addr_t the address of the object you want to inspect

    +

    mps_addr_t the address of the object you want to inspect

    -

    *

    +

    *

    -

    size_t

    +

    size_t

    -

    Returned Values

    +

    Returned Values

    -

    Not applicable.

    +

    Not applicable.

    -

    Resources

    +

    Resources

    -

    Not applicable.

    +

    Not applicable.

    -

    Description

    +

    Description

    -

    mps_amc_apply is used to inspect objects in an AMC pool. You may only call it when thearena is parked (for example, after mps_arena_collect). When called, mps_amc_apply calls thesupplied function "f" once for each object in the pool, with the address of the object as its firstargument. "f" is given as its second and third arguments whatever values were given as the third andfourth arguments to mps_amc_apply. (This is intended to make it easy to pass, for example, anarray and its size as parameters.)

    +

    mps_amc_apply is used to inspect objects in an AMC pool. You may only call it when thearena is parked (for example, after mps_arena_collect). When called, mps_amc_apply calls thesupplied function "f" once for each object in the pool, with the address of the object as its firstargument. "f" is given as its second and third arguments whatever values were given as the third andfourth arguments to mps_amc_apply. (This is intended to make it easy to pass, for example, anarray and its size as parameters.)

    -

    "f" will be called on both data and pad objects, and it is "f"'s job to distinguish, ifrequired, between the two. Note (c.f. mps_arena_collect, above) that it may be called onunreachable objects that the collector has not recycled or has not been able to recycle.

    +

    "f" will be called on both data and pad objects, and it is "f"'s job to distinguish, ifrequired, between the two. Note (c.f. mps_arena_collect, above) that it may be called onunreachable objects that the collector has not recycled or has not been able to recycle.

    -

    The function "f" may not allocate memory or access any automatically-managed memory exceptthe object at which it is pointed and, in the case of objects in Dylan Container Format, thatobject's wrapper.

    +

    The function "f" may not allocate memory or access any automatically-managed memory exceptthe object at which it is pointed and, in the case of objects in Dylan Container Format, thatobject's wrapper.

    -

    Example

    +

    Example

    -

    Error Handling

    +

    Error Handling

    -

    See Also

    +

    See Also

    -

    Functions that park the arena: mps_arena_park, mps_arena_collect.

    +

    Functions that park the arena: -

    A more general heap walker which inspects all formatted objects in the arena: mps_arena_formatted_objects_walk

    +mps_arena_park, +mps_arena_collect.

    -

    Notes

    +

    A more general heap walker which inspects all formatted objects in +the arena: -

    There is no equivalent function for other pool classes, but there is a more general heapwalker: mps_arena_formatted_objects_walk.

    +mps_arena_formatted_objects_walk

    -

    Internal Notes

    +

    Notes

    -

    Does "You must call it when the arena is parked" mean that (a) parking an arena requiresthat you call this function, or (b) you can only call this function when the arena is in the parkedstate? LMB

    +

    There is no equivalent function for other pool classes, but there is a more general heapwalker: mps_arena_formatted_objects_walk.

    -

    (b). Changed "must call" to "may only call" drj 1998-08-25

    +

    Internal Notes

    -

    mps_ap_alloc_pattern_begin

    +

    Does "You must call it when the arena is parked" mean that (a) parking an arena requiresthat you call this function, or (b) you can only call this function when the arena is in the parkedstate? LMB

    +

    (b). Changed "must call" to "may only call" drj 1998-08-25

    -

    Name

    -

    mps_ap_alloc_pattern_begin

    +

    mps_ap_alloc_pattern_begin

    -

    Summary

    +

    Name

    -

    Indicates the start of allocation following a particular pattern.

    +

    mps_ap_alloc_pattern_begin

    -

    Associated Protocols

    +

    Summary

    -

    AP, Allocation, Alloc-pattern-ramp.

    +

    Indicates the start of allocation following a particular pattern.

    -

    Syntax

    +

    Associated Protocols

    -

    mps_res_t mps_ap_alloc_pattern_begin(mps_ap_t ap, mps_alloc_pattern_t alloc_pattern)

    +

    AP, Allocation, Alloc-pattern-ramp.

    -

    Arguments

    +

    Syntax

    -

    ap The allocation point in which the patterned allocation will occur

    +

    mps_res_t mps_ap_alloc_pattern_begin(mps_ap_t ap, mps_alloc_pattern_t alloc_pattern)

    -

    alloc_pattern The pattern of the allocation

    +

    Arguments

    -

    Returned Values

    +

    ap The allocation point in which the patterned allocation will occur

    -

    Result code indicating whether start of the allocation pattern was successfully registered.

    +

    alloc_pattern The pattern of the allocation

    -

    Resources

    +

    Returned Values

    -

    mps.h

    +

    Result code indicating whether start of the allocation pattern was successfully registered.

    -

    Description

    +

    Resources

    -

    This function is used, together with mps_ap_alloc_pattern_end, to indicate periods ofallocation in an allocation point that follow some pattern of lifetime.

    +

    mps.h

    -

    The nesting/overlapping restrictions on allocation patterns may vary depending on theparticular allocation pattern type, but in general, if mps_ap_alloc_pattern_begin is used multipletimes on the same allocation point without intervening calls to mps_ap_alloc_pattern_end, the callsmatch in a stack-like way, outermost and innermost; that is, allocation patterns may nest, but nototherwise overlap.

    +

    Description

    -

    Example

    +

    This function is used, together with mps_ap_alloc_pattern_end, to indicate periods ofallocation in an allocation point that follow some pattern of lifetime.

    + +

    The nesting/overlapping restrictions on allocation patterns may vary depending on theparticular allocation pattern type, but in general, if mps_ap_alloc_pattern_begin is used multipletimes on the same allocation point without intervening calls to mps_ap_alloc_pattern_end, the callsmatch in a stack-like way, outermost and innermost; that is, allocation patterns may nest, but nototherwise overlap.

    + + +

    Example

     {
@@ -2285,57 +2825,69 @@ mps_align_t doubleFloatAlign = 8;
    -

    Error Handling

    +

    Error Handling

    -

    Currently doesn't fail, but may in future if certain allocation patterns are inappropriatefor that allocation point at that point in time.

    +

    Currently doesn't fail, but may in future if certain allocation patterns are inappropriatefor that allocation point at that point in time.

    -

    See Also

    +

    See Also

    -

    mps_alloc_pattern_ramp, mps_alloc_pattern_ramp_collect_all, mps_ap_alloc_pattern_end, mps_ap_alloc_pattern_reset

    +

    + +mps_alloc_pattern_ramp, + +mps_alloc_pattern_ramp_collect_all, + +mps_ap_alloc_pattern_end, + +mps_ap_alloc_pattern_reset

    -

    mps_ap_alloc_pattern_end

    +

    mps_ap_alloc_pattern_end

    -

    Name

    +

    Name

    -

    mps_ap_alloc_pattern_end

    +

    mps_ap_alloc_pattern_end

    -

    Summary

    +

    Summary

    -

    Indicates the end of allocation following a particular pattern.

    +

    Indicates the end of allocation following a particular pattern.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    AP, Allocation, Alloc-pattern-ramp.

    +

    AP, Allocation, Alloc-pattern-ramp.

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_ap_alloc_pattern_end(mps_ap_t ap, mps_alloc_pattern_t alloc_pattern)

    +

    mps_res_t mps_ap_alloc_pattern_end(mps_ap_t ap, mps_alloc_pattern_t alloc_pattern)

    -

    Arguments

    +

    Arguments

    -

    ap The allocation point in which the patterned allocation occurred

    +

    ap The allocation point in which the patterned allocation occurred

    -

    alloc_pattern The pattern of the allocation

    +

    alloc_pattern The pattern of the allocation

    -

    Returned Values

    +

    Returned Values

    -

    Result code indicating whether end of the allocation pattern was successfully registered.

    +

    Result code indicating whether end of the allocation pattern was successfully registered.

    -

    Description

    +

    Description

    -

    This function is used, together with mps_ap_alloc_pattern_begin, to indicate periods of allocation in an allocation point that follow some pattern of lifetime.

    +

    This function is used, together with mps_ap_alloc_pattern_begin, to indicate periods of allocation in an allocation point that follow some pattern of lifetime.

    -

    Example

    +

    Example

     {
@@ -2360,55 +2912,67 @@ mps_align_t doubleFloatAlign = 8;
    -

    Error Handling

    +

    Error Handling

    -

    Will fail if there is no extant allocation pattern of that type. May fail in future ifcertain allocation patterns are inappropriate for that allocation point at that point in time.

    +

    Will fail if there is no extant allocation pattern of that type. May fail in future ifcertain allocation patterns are inappropriate for that allocation point at that point in time.

    -

    See Also

    +

    See Also

    -

    mps_alloc_pattern_ramp, mps_alloc_pattern_ramp_collect_all, mps_ap_alloc_pattern_begin, mps_ap_alloc_pattern_reset

    +

    + +mps_alloc_pattern_ramp, + +mps_alloc_pattern_ramp_collect_all, + +mps_ap_alloc_pattern_begin, + +mps_ap_alloc_pattern_reset

    -

    function mps_ap_alloc_pattern_reset

    +

    function mps_ap_alloc_pattern_reset

    -

    Name

    +

    Name

    -

    mps_ap_alloc_pattern_reset

    +

    mps_ap_alloc_pattern_reset

    -

    Summary

    +

    Summary

    -

    Indicates the end of allocation pattern on an allocation point.

    +

    Indicates the end of allocation pattern on an allocation point.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    AP, Alloc-pattern-ramp

    +

    AP, Alloc-pattern-ramp

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_ap_alloc_pattern_reset(mps_ap_t ap);

    +

    mps_res_t mps_ap_alloc_pattern_reset(mps_ap_t ap);

    -

    Arguments

    +

    Arguments

    -

    ap The allocation point in which the patterned allocation occurred

    +

    ap The allocation point in which the patterned allocation occurred

    -

    Returned Values

    +

    Returned Values

    -

    Result code indicating whether end of the allocation patterns was successfully registered.

    +

    Result code indicating whether end of the allocation patterns was successfully registered.

    -

    Description

    +

    Description

    -

    This function may be used in place of mps_ap_alloc_pattern_end to end all extant allocationpatterns on an allocation point. It is anticipated that this may be used to recover from errorconditions.

    +

    This function may be used in place of mps_ap_alloc_pattern_end to end all extant allocationpatterns on an allocation point. It is anticipated that this may be used to recover from errorconditions.

    -

    Example

    +

    Example

     {
@@ -2438,247 +3002,268 @@ mps_align_t doubleFloatAlign = 8;
    -

    Error Handling

    +

    Error Handling

    -

    Cannot fail at present. May fail in future if certain allocation patterns cannot be endedfor that allocation point at that point in time.

    +

    Cannot fail at present. May fail in future if certain allocation patterns cannot be endedfor that allocation point at that point in time.

    -

    See Also

    +

    See Also

    -

    mps_alloc_pattern_ramp, mps_alloc_pattern_ramp_collect_all, mps_ap_alloc_pattern_begin, mps_ap_alloc_pattern_end

    +

    +mps_alloc_pattern_ramp, -

    function mps_ap_frame_pop

    +mps_alloc_pattern_ramp_collect_all, +mps_ap_alloc_pattern_begin, -

    Name

    +mps_ap_alloc_pattern_end

    -

    mps_ap_frame_pop

    +

    function mps_ap_frame_pop

    -

    Summary

    -

    Declares that a set of objects in a particular frame are dead or likely to be dead.

    +

    Name

    +

    mps_ap_frame_pop

    -

    Associated Protocols

    -

    AP Stack Protocol

    +

    Summary

    +

    Declares that a set of objects in a particular frame are dead or likely to be dead.

    -

    Type

    -

    mps_res_t (mps_ap_frame_pop)(mps_ap_t /* ap */, mps_frame_t /* frame */)

    +

    Associated Protocols

    +

    AP Stack Protocol

    -

    Arguments

    -

    mps_ap_t ap

    +

    Type

    -

    The allocation point in which the frame was pushed.

    +

    mps_res_t (mps_ap_frame_pop)(mps_ap_t /* ap */, mps_frame_t /* frame */)

    -

    frame

    -

    The frame.

    +

    Arguments

    +

    mps_ap_t ap

    -

    Returned Values

    +

    The allocation point in which the frame was pushed.

    -

    A result code in the usual way.

    +

    frame

    +

    The frame.

    -

    Description

    -

    This function pops the specified frame making its parent the current frame (frames areimplicitly created using the push operation, see mps_ap_frame_push). Poppinginvalidates the specified frame and all frames pushed since the specified frame. Popping the framemakes a declaration about the set of objects which were allocated in the specified frame and alsoall frames which were pushed since the specified frame. It can be used to declare a set of objectsdead or likely to be mostly dead; the exact interpretation of the declaration depends on pool classthat the allocation point is in (the same pool class that that objects are in). Typically poolclasses which are mostly manually managed will use this declaration to mean that the objects aredead and their space can be reclaimed immediately, whereas pool classes which are mostlyautomatically managed will use this declaration to mean that the objects are likely to be mostlydead (the pool class may use this declaration to alter its collection decisions). Consult the poolclass documentation for details.

    +

    Returned Values

    -

    In general a frame other than the current frame can be popped (all frames pushed morerecently will be invalidated as well, as described above), but a particular pool class may imposethe restriction that only the current frame may be popped. This restriction means that every pushmust have a corresponding pop. Consult the pool class documentation for details.

    +

    A result code in the usual way.

    -

    It is illegal to pass invalid frames to any MPS function. In particular it is not possibleto pop frames out of order (so the sequence "A = push, B = push, pop A, pop B" is illegal) or to popto the same frame twice (so the sequence "A = push, pop A, pop A" is illegal).

    -

    More comprehensive documentation is available in the protocol document (AP Stack Protocol).

    +

    Description

    +

    This function pops the specified frame making its parent the current frame (frames areimplicitly created using the push operation, see mps_ap_frame_push). Poppinginvalidates the specified frame and all frames pushed since the specified frame. Popping the framemakes a declaration about the set of objects which were allocated in the specified frame and alsoall frames which were pushed since the specified frame. It can be used to declare a set of objectsdead or likely to be mostly dead; the exact interpretation of the declaration depends on pool classthat the allocation point is in (the same pool class that that objects are in). Typically poolclasses which are mostly manually managed will use this declaration to mean that the objects aredead and their space can be reclaimed immediately, whereas pool classes which are mostlyautomatically managed will use this declaration to mean that the objects are likely to be mostlydead (the pool class may use this declaration to alter its collection decisions). Consult the poolclass documentation for details.

    -

    Example

    +

    In general a frame other than the current frame can be popped (all frames pushed morerecently will be invalidated as well, as described above), but a particular pool class may imposethe restriction that only the current frame may be popped. This restriction means that every pushmust have a corresponding pop. Consult the pool class documentation for details.

    -

    <example of how to use the symbol>

    +

    It is illegal to pass invalid frames to any MPS function. In particular it is not possibleto pop frames out of order (so the sequence "A = push, B = push, pop A, pop B" is illegal) or to popto the same frame twice (so the sequence "A = push, pop A, pop A" is illegal).

    +

    More comprehensive documentation is available in the protocol document (AP Stack Protocol).

    -

    Error Handling

    -

    <how the client program should handle errors that the symbol returns, if applicable>

    +

    Example

    +

    <example of how to use the symbol>

    -

    See Also

    -

    mps.protocol.alloc-point.stack, mps_ap_frame_push

    +

    Error Handling

    +

    <how the client program should handle errors that the symbol returns, if applicable>

    -

    Notes

    -

    None.

    +

    See Also

    +

    mps.protocol.alloc-point.stack, -

    function mps_ap_frame_push

    +mps_ap_frame_push

    -

    Name

    +

    Notes

    -

    mps_ap_frame_push

    +

    None.

    -

    Summary

    +

    function mps_ap_frame_push

    -

    Declares a new frame as part of the AP stack protocol.

    +

    Name

    -

    Associated Protocols

    +

    mps_ap_frame_push

    -

    AP Stack Protocol

    +

    Summary

    -

    Type

    +

    Declares a new frame as part of the AP stack protocol.

    -

    mps_res_t (mps_ap_frame_push)(mps_frame_t * /* frameReturn */, mps_ap_t /* ap */);

    +

    Associated Protocols

    -

    Arguments

    +

    AP Stack Protocol

    -

    mps_frame_t *frameReturn The frame return parameter. A new frame (declared by this function) is stored in thislocation if this function is successful.

    -

    mps_ap_t ap The allocation point in which the new frame is declared.

    +

    Type

    +

    mps_res_t (mps_ap_frame_push)(mps_frame_t * /* frameReturn */, mps_ap_t /* ap */);

    -

    Returned Values

    -

    A result code in the usual way. The creation of new frame objects (which is implicit in theaction of this function) can consume resources, so this function can fail because there areinsufficient resources. This function may fail if the correct protocol is not followed by theclient.

    +

    Arguments

    +

    mps_frame_t *frameReturn The frame return parameter. A new frame (declared by this function) is stored in thislocation if this function is successful.

    -

    Description

    +

    mps_ap_t ap The allocation point in which the new frame is declared.

    -

    This function declares a new frame in the specified allocation point, makes that new frame achild of the current frame, changes the current frame to be the newly created frame, and returns ahandle to the frame. Frames have two important features: A single frame identifies a set of objects(those objects that are "allocated in the frame") which can be destroyed (or declared dead) in a popoperation (see mps_ap_frame_pop); They are arranged in a partially ordered sequence (this isimportant when the pop operation is used). A fuller and more useful description is found in the APstack protocol document (protocol.mps.alloc-point.stack).

    +

    Returned Values

    -

    Example

    +

    A result code in the usual way. The creation of new frame objects (which is implicit in theaction of this function) can consume resources, so this function can fail because there areinsufficient resources. This function may fail if the correct protocol is not followed by theclient.

    -

    [missing]

    +

    Description

    -

    Error Handling

    +

    This function declares a new frame in the specified allocation point, makes that new frame achild of the current frame, changes the current frame to be the newly created frame, and returns ahandle to the frame. Frames have two important features: A single frame identifies a set of objects(those objects that are "allocated in the frame") which can be destroyed (or declared dead) in a popoperation (see mps_ap_frame_pop); They are arranged in a partially ordered sequence (this isimportant when the pop operation is used). A fuller and more useful description is found in the APstack protocol document (protocol.mps.alloc-point.stack).

    -

    Errors can either be because the client hasn't followed the correct protocol in which casethere isn't much that we can recommend or else because some needed resource isn't available. Theusual course of actions when short of resources is recommended.

    +

    Example

    -

    See Also

    +

    [missing]

    -

    mps_ap_frame_pop, protocol.mps.alloc-point.stack

    +

    Error Handling

    -

    Notes

    +

    Errors can either be because the client hasn't followed the correct protocol in which casethere isn't much that we can recommend or else because some needed resource isn't available. Theusual course of actions when short of resources is recommended.

    -

    function mps_arena_clamp

    +

    See Also

    +

    -

    Name

    +mps_ap_frame_pop, +protocol.mps.alloc-point.stack

    -

    mps_arena_clamp

    +

    Notes

    -

    Summary

    -

    mps_arena_clamp puts the specified arena into the clamped state.

    +

    function mps_arena_clamp

    -

    Associated Protocols

    +

    Name

    -

    Arena.

    +

    mps_arena_clamp

    -

    Syntax

    +

    Summary

    -

    extern void mps_arena_clamp(mps_arena_t);

    +

    mps_arena_clamp puts the specified arena into the clamped state.

    -

    Arguments

    +

    Associated Protocols

    -

    arena -- the arena to be put i nto the clamped state

    +

    Arena.

    -

    Returned Values

    +

    Syntax

    -

    None.

    +

    extern void mps_arena_clamp(mps_arena_t);

    -

    Resources

    +

    Arguments

    -

    mps.h

    +

    arena -- the arena to be put i nto the clamped state

    -

    Description

    +

    Returned Values

    -

    mps_arena_clamp puts the specified arena into the clamped state. In the clamped state, noobject motion will occur and the staleness of location dependencies will not change. All referencesto objects loaded while the arena is clamped will keep the same binary representation until after itis released.

    +

    None.

    -

    In a clamped arena, incremental collection may still occur, but it will not be visible tothe mutator and no new collections will begin. Space used by unreachable objects will not berecycled until the arena becomes unclamped.

    +

    Resources

    -

    Example

    +

    mps.h

    -

    Error Handling

    +

    Description

    +

    mps_arena_clamp puts the specified arena into the clamped state. In the clamped state, noobject motion will occur and the staleness of location dependencies will not change. All referencesto objects loaded while the arena is clamped will keep the same binary representation until after itis released.

    -

    See Also

    +

    In a clamped arena, incremental collection may still occur, but it will not be visible tothe mutator and no new collections will begin. Space used by unreachable objects will not berecycled until the arena becomes unclamped.

    -

    mps_arena_park, mps_arena_release

    +

    Example

    -

    Notes

    +

    Error Handling

    -

    function mps_arena_class_cl

    +

    See Also

    -

    Name

    +

    -

    mps_arena_class_cl

    +mps_arena_park, +mps_arena_release

    -

    Summary

    -

    mps_arena_class_cl returns the client arena class.

    +

    Notes

    -

    Associated Protocols

    +

    function mps_arena_class_cl

    -

    Arena.

    +

    Name

    -

    Type

    +

    mps_arena_class_cl

    -

    mps_arena_class_t mps_arena_class_cl(void)

    +

    Summary

    -

    Arguments

    +

    mps_arena_class_cl returns the client arena class.

    -

    None.

    +

    Associated Protocols

    -

    Returned Values

    +

    Arena.

    -

    Returns the client arena class.

    +

    Type

    -

    Resources

    +

    mps_arena_class_t mps_arena_class_cl(void)

    -

    mpsacl.h

    +

    Arguments

    -

    Description

    +

    None.

    -

    This function is used to get hold of the client arena class, for the purpose of passing itto mps_arena_create.

    +

    Returned Values

    -

    Example

    +

    Returns the client arena class.

    + + +

    Resources

    + +

    mpsacl.h

    + + +

    Description

    + +

    This function is used to get hold of the client arena class, for the purpose of passing itto mps_arena_create.

    + + +

    Example

     mps_arena_t arena;
@@ -2705,121 +3290,123 @@ int main(void)
    -

    Error Handling

    +

    Error Handling

    -

    None.

    +

    None.

    -

    See Also

    +

    See Also

    -

    mps_arena_create

    +

    +mps_arena_create

    -

    Notes

    -

    A client arena gets its managed memory from the client. This memory block is passed when thearena is created. When creating a client arena, mps_arena_create takes two extraarguments:

    +

    Notes

    -

    mps_res_t mps_arena_create(mps_arena_t *mps_arena_o, mps_arena_class_t mps_arena_class_cl,size_t size, void *block)

    +

    A client arena gets its managed memory from the client. This memory block is passed when thearena is created. When creating a client arena, mps_arena_create takes two extraarguments:

    -

    block is the address of the memory block managed by the arena, andsize is its size in bytes. If mps_arena_create returnsMPS_RES_MEMORY, then the block was too small to hold the internal arena structures.Allocate a (much) larger one, and try again. mps_arena_create returnsMPS_RES_FAIL, if the MPS library is copy-protected by a security device, such as adongle, and a valid security device cannot be found.

    +

    mps_res_t mps_arena_create(mps_arena_t *mps_arena_o, mps_arena_class_t mps_arena_class_cl,size_t size, void *block)

    +

    block is the address of the memory block managed by the arena, andsize is its size in bytes. If mps_arena_create returnsMPS_RES_MEMORY, then the block was too small to hold the internal arena structures.Allocate a (much) larger one, and try again. mps_arena_create returnsMPS_RES_FAIL, if the MPS library is copy-protected by a security device, such as adongle, and a valid security device cannot be found.

    -

    type mps_arena_class_t

    +

    type mps_arena_class_t

    -

    Name

    -

    mps_arena_class_t

    +

    Name

    +

    mps_arena_class_t

    -

    Summary

    -

    "m ps_arena_class_t " is the type of arena classes.

    +

    Summary

    +

    "m ps_arena_class_t " is the type of arena classes.

    -

    Associated Protocols

    -

    Arena.

    +

    Associated Protocols

    +

    Arena.

    -

    Type

    -

    typedef struct mps_arena_s *mps_arena_t;

    +

    Type

    -

    mps_arena_class_s is an incomplete structure type used only to declare the opaque type mps_arena_class_t.

    +

    typedef struct mps_arena_s *mps_arena_t;

    +

    mps_arena_class_s is an incomplete structure type used only to declare the opaque type mps_arena_class_t.

    -

    Resources

    -

    mps.h

    +

    Resources

    +

    mps.h

    -

    Description

    -

    mps_arena_class_t is the type of arena classes. It is opaque.

    +

    Description

    +

    mps_arena_class_t is the type of arena classes. It is opaque.

    -

    Example

    -

    The definition of the client arena class in the "mpsacl.h" header:

    +

    Example

    -

    extern mps_arena_class_t mps_arena_class_cl(void);

    +

    The definition of the client arena class in the "mpsacl.h" header:

    +

    extern mps_arena_class_t mps_arena_class_cl(void);

    -

    See Also

    +

    See Also

    -

    Notes

    -

    None.

    +

    Notes

    +

    None.

    -

    function mps_arena_class_vm

    +

    function mps_arena_class_vm

    -

    Name

    -

    mps_arena_class_vm

    +

    Name

    +

    mps_arena_class_vm

    -

    Summary

    -

    mps_arena_class_vm returns the virtual memory arena class.

    +

    Summary

    +

    mps_arena_class_vm returns the virtual memory arena class.

    -

    Associated Protocols

    -

    Arena.

    +

    Associated Protocols

    +

    Arena.

    -

    Syntax

    -

    mps_arena_class_t mps_arena_class_vm(void)

    +

    Syntax

    +

    mps_arena_class_t mps_arena_class_vm(void)

    -

    Arguments

    -

    None.

    +

    Arguments

    +

    None.

    -

    Returned Values

    -

    Returns the virtual memory arena class.

    +

    Returned Values

    +

    Returns the virtual memory arena class.

    -

    Resources

    -

    mpsavm.h

    +

    Resources

    +

    mpsavm.h

    -

    Description

    -

    This function is used to get hold of the virtual memory arena class, for the purpose ofpassing it to mps_arena_create. The VM arenas use the OS virtual memory interfaces toallocate memory. The chief consequence of this is that the arena can manage many more virtualaddresses than it needs to commit memory to. This gives it flexibility as to where to place objects,which reduces fragmentation and helps make garbage collection more efficient.

    +

    Description

    -

    This class is similar to mps_arena_class_vmnz but uses a more complex placementpolicy, which is more suited to copying garbage collection.

    +

    This function is used to get hold of the virtual memory arena class, for the purpose ofpassing it to mps_arena_create. The VM arenas use the OS virtual memory interfaces toallocate memory. The chief consequence of this is that the arena can manage many more virtualaddresses than it needs to commit memory to. This gives it flexibility as to where to place objects,which reduces fragmentation and helps make garbage collection more efficient.

    +

    This class is similar to mps_arena_class_vmnz but uses a more complex placementpolicy, which is more suited to copying garbage collection.

    -

    Example

    + +

    Example

     mps_arena_t arena;
@@ -2840,19 +3427,24 @@ int main(void)
    -

    Error Handling

    +

    Error Handling

    -

    None.

    +

    None.

    -

    See Also

    +

    See Also

    -

    mps_arena_create, mps_arena_class_vmnz

    +

    + +mps_arena_create, + +mps_arena_class_vmnz

    -

    Notes

    +

    Notes

    -

    A virtual memory arena gets its managed memory from the operating system's virtual memoryservices. An initial address space size is passed when the arena is created. When creating a virtualmemory arena, mps_arena_create takes one extra argument:

    +

    A virtual memory arena gets its managed memory from the operating system's virtual memoryservices. An initial address space size is passed when the arena is created. When creating a virtualmemory arena, mps_arena_create takes one extra argument:

    mps_res_t mps_arena_create(mps_arena_t *arena_o,
 
@@ -2860,59 +3452,59 @@ int main(void)
 
                            size_t size)
    -

    size is the initial amount of virtual address space, in bytes, that the arenawill reserve (this space is initially reserved so that the arena can subsequently use it withoutinterference from other parts of the program, but most of it is not committed, so it don't requireany RAM or backing store). The arena may allocate more virtual address space beyond this initialreservation as and when it deems it necessary. The MPS is most efficient if you reserve an addressspace that is several times larger than your peak memory usage.

    +

    size is the initial amount of virtual address space, in bytes, that the arenawill reserve (this space is initially reserved so that the arena can subsequently use it withoutinterference from other parts of the program, but most of it is not committed, so it don't requireany RAM or backing store). The arena may allocate more virtual address space beyond this initialreservation as and when it deems it necessary. The MPS is most efficient if you reserve an addressspace that is several times larger than your peak memory usage.

    -

    mps_arena_create returns MPS_RES_RESOURCE if it fails to reserveadequate address space to place the arena in; possibly other parts of the program are reserving toomuch virtual memory. It returns MPS_RES_MEMORY when it fails to allocate memory for theinternal arena structures; either size was far too small or you ran out of swap space.It returns MPS_RES_FAIL, if the library is copy-protected by a security device, suchas a dongle, and a valid security device cannot be found.

    +

    mps_arena_create returns MPS_RES_RESOURCE if it fails to reserveadequate address space to place the arena in; possibly other parts of the program are reserving toomuch virtual memory. It returns MPS_RES_MEMORY when it fails to allocate memory for theinternal arena structures; either size was far too small or you ran out of swap space.It returns MPS_RES_FAIL, if the library is copy-protected by a security device, suchas a dongle, and a valid security device cannot be found.

    -

    Virtual memory arenas are not available on the Mac platforms, other than MacOS X. You willget a linking error, if you attempt to use this function.

    +

    Virtual memory arenas are not available on the Mac platforms, other than MacOS X. You willget a linking error, if you attempt to use this function.

    -

    function mps_arena_class_vmnz

    +

    function mps_arena_class_vmnz

    -

    Name

    +

    Name

    -

    mps_arena_class_vmnz

    +

    mps_arena_class_vmnz

    -

    Summary

    +

    Summary

    -

    An arena class like mps_arena_class_vm but with a different placement policy.

    +

    An arena class like mps_arena_class_vm but with a different placement policy.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Arena.

    +

    Arena.

    -

    Syntax

    +

    Syntax

    -

    mps_arena_class_t mps_arena_class_vmnz(void);

    +

    mps_arena_class_t mps_arena_class_vmnz(void);

    -

    Arguments

    +

    Arguments

    -

    None.

    +

    None.

    -

    Returned Values

    +

    Returned Values

    -

    Returns the VMNZ arena class.

    +

    Returns the VMNZ arena class.

    -

    Resources

    +

    Resources

    -

    mpsavm.h

    +

    mpsavm.h

    -

    Description

    +

    Description

    -

    Returns the VMNZ arena class (stands for Virtual Memory No Zones, if you really care.) Thisclass can be passed to mps_arena_create in order to create a VMNZ arena. The VMNZarenas use the OS virtual memory interfaces to allocate memory. The chief consequence of this isthat the arena can manage many more virtual addresses than it needs to commit memory to. This givesit flexibility as to where to place objects.

    +

    Returns the VMNZ arena class (stands for Virtual Memory No Zones, if you really care.) Thisclass can be passed to mps_arena_create in order to create a VMNZ arena. The VMNZarenas use the OS virtual memory interfaces to allocate memory. The chief consequence of this isthat the arena can manage many more virtual addresses than it needs to commit memory to. This givesit flexibility as to where to place objects.

    -

    This class is similar to mps_arena_class_vm but uses a simpler placementpolicy, that makes it slightly faster.

    +

    This class is similar to mps_arena_class_vm but uses a simpler placementpolicy, that makes it slightly faster.

    -

    Example

    +

    Example

     mps_arena_t arena;
@@ -2932,197 +3524,210 @@ int main(void)
 }
    -

    +

    -

    Error Handling

    +

    Error Handling

    -

    No errors.

    +

    No errors.

    -

    See Also

    +

    See Also

    -

    mps_arena_create, mps_arena_class_vm

    +

    +mps_arena_create, -

    Notes

    +mps_arena_class_vm

    -

    This class takes an extra argument when used in mps_arena_create (see example).The extra parameter should be of type size_t. It specifies the amount of virtualaddress space, in bytes, that this arena should use. The arena will reserve this amount of virtualaddress space from the OS during initialization. It will not subsequently use any more address space(compare with mps_arena_class_vm which can grow).

    -

    mps_arena_create returns MPS_RES_RESOURCE if it fails to reserveadequate address space to place the arena in; possibly other parts of the program are reserving toomuch virtual memory. It returns MPS_RES_MEMORY when it fails to allocate memory for theinternal arena structures; either size was far too small or you ran out of swap space.It returns MPS_RES_FAIL, if the library is copy-protected by a security device, suchas a dongle, and a valid security device cannot be found.

    +

    Notes

    -

    Virtual memory arenas are not available on the Mac platforms, other than MacOS X. You willget a linking error, if you attempt to use this function.

    +

    This class takes an extra argument when used in mps_arena_create (see example).The extra parameter should be of type size_t. It specifies the amount of virtualaddress space, in bytes, that this arena should use. The arena will reserve this amount of virtualaddress space from the OS during initialization. It will not subsequently use any more address space(compare with mps_arena_class_vm which can grow).

    +

    mps_arena_create returns MPS_RES_RESOURCE if it fails to reserveadequate address space to place the arena in; possibly other parts of the program are reserving toomuch virtual memory. It returns MPS_RES_MEMORY when it fails to allocate memory for theinternal arena structures; either size was far too small or you ran out of swap space.It returns MPS_RES_FAIL, if the library is copy-protected by a security device, suchas a dongle, and a valid security device cannot be found.

    -

    function mps_arena_collect

    +

    Virtual memory arenas are not available on the Mac platforms, other than MacOS X. You willget a linking error, if you attempt to use this function.

    -

    Name

    +

    function mps_arena_collect

    -

    mps_arena_collect

    +

    Name

    -

    Summary

    +

    mps_arena_collect

    -

    mps_arena_collect collects the arena and puts it in the parked state.

    +

    Summary

    -

    Associated Protocols

    +

    mps_arena_collect collects the arena and puts it in the parked state.

    -

    Arena.

    +

    Associated Protocols

    -

    Syntax

    +

    Arena.

    -

    void mps_arena_collect(mps_arena_t arena);

    +

    Syntax

    -

    Arguments

    +

    void mps_arena_collect(mps_arena_t arena);

    -

    arena the arena to collect

    +

    Arguments

    -

    Resources

    +

    arena the arena to collect

    -

    mps.h

    +

    Resources

    -

    Description

    +

    mps.h

    -

    mps_arena_collect collects the arena and puts it in the parked state. Collecting the arenaattempts to recycle as many unreachable objects as possible and reduce the size of the arena as muchas possible (though in some cases it may increase because it becomes more fragmented). If you do notwant the arena to be in the parked state, you must explicitly call mps_arena_release aftermps_arena_collect.

    -

    Note that the collector may not be able to recycle some objects (such as those near thedestination of ambiguous references) even though they are not reachable.

    +

    Description

    +

    mps_arena_collect collects the arena and puts it in the parked state. Collecting the arenaattempts to recycle as many unreachable objects as possible and reduce the size of the arena as muchas possible (though in some cases it may increase because it becomes more fragmented). If you do notwant the arena to be in the parked state, you must explicitly call mps_arena_release aftermps_arena_collect.

    -

    Example

    +

    Note that the collector may not be able to recycle some objects (such as those near thedestination of ambiguous references) even though they are not reachable.

    -

    [missing]

    +

    Example

    -

    Error Handling

    +

    [missing]

    -

    No errors.

    +

    Error Handling

    -

    See Also

    +

    No errors.

    -

    mps_arena_park, mps_arena_release

    +

    See Also

    -

    Notes

    +

    -

    None.

    +mps_arena_park, +mps_arena_release

    -

    function mps_arena_commit_limit

    +

    Notes

    -

    Name

    +

    None.

    -

    mps_arena_commit_limit

    +

    function mps_arena_commit_limit

    -

    Summary

    -

    Returns the current commit limit associated with the arena in bytes.

    +

    Name

    +

    mps_arena_commit_limit

    -

    Associated Protocols

    -

    Arena

    +

    Summary

    +

    Returns the current commit limit associated with the arena in bytes.

    -

    Type

    -

    size_t mps_arena_commit_limit(mps_arena_t arena)

    +

    Associated Protocols

    +

    Arena

    -

    Arguments

    -

    arena -- the arena

    +

    Type

    +

    size_t mps_arena_commit_limit(mps_arena_t arena)

    -

    Returned Values

    -

    Returns the current commit limit as a number of bytes in a size_t

    +

    Arguments

    +

    arena -- the arena

    -

    Resources

    -

    mps.h

    +

    Returned Values

    +

    Returns the current commit limit as a number of bytes in a size_t

    -

    Description

    -

    Returns the current commit limit associated with the arena in bytes. The commit limit can bechanged using the function mps_commit_limit_set. The commit limit is used to control how much memorythe MPS can obtain from the OS. See Arena Protocol for details.

    +

    Resources

    +

    mps.h

    -

    Example

    -

    limit = mps_arena_commit_limit(arena);

    +

    Description

    +

    Returns the current commit limit associated with the arena in bytes. The commit limit can bechanged using the function mps_commit_limit_set. The commit limit is used to control how much memorythe MPS can obtain from the OS. See Arena Protocol for details.

    -

    Error Handling

    -

    No errors.

    +

    Example

    +

    limit = mps_arena_commit_limit(arena);

    -

    See Also

    -

    mps_arena_committed, mps_arena_commit_limit_set

    +

    Error Handling

    +

    No errors.

    -

    Notes

    -

    None.

    +

    See Also

    +

    -

    function mps_arena_commit_limit_set

    +mps_arena_committed, +mps_arena_commit_limit_set

    -

    Name

    -

    mps_arena_commit_limit_set

    +

    Notes

    +

    None.

    -

    Summary

    -

    Changes the current commit limit associated with the arena.

    +

    function mps_arena_commit_limit_set

    -

    Associated Protocols

    +

    Name

    -

    Arena

    +

    mps_arena_commit_limit_set

    -

    Type

    +

    Summary

    -

    mps_res_t mps_arena_commit_limit_set(mps_arena_t arena, size_t limit)

    +

    Changes the current commit limit associated with the arena.

    -

    Arguments

    +

    Associated Protocols

    -

    arena -- the arena

    +

    Arena

    -

    limit -- the new commit limit in bytes

    +

    Type

    -

    Returned Values

    +

    mps_res_t mps_arena_commit_limit_set(mps_arena_t arena, size_t limit)

    -

    Returns a result code.

    +

    Arguments

    -

    Resources

    +

    arena -- the arena

    -

    mps.h

    +

    limit -- the new commit limit in bytes

    -

    Description

    +

    Returned Values

    -

    The commit limit of the arena is set to the limit given. The commit limit controls how muchmemory the MPS will obtain from the OS. See Arena Protocol for details. The commit limit cannot beset to a value that is lower than the number of bytes that the MPS is using. If an attempt is madeto set the commit limit to a value greater than or equal to that returned bymps_arena_committed then it will succeed. If an attempt is made to set the commit limitto a value less than that returned by mps_arena_committed then it will succeed only ifthe amount committed by the MPS can be reduced by reducing the amount of spare committed memory; insuch a case the spare committed memory will be reduced appropriately and the attempt will succeed.

    +

    Returns a result code.

    -

    Example

    +

    Resources

    + +

    mps.h

    + + +

    Description

    + +

    The commit limit of the arena is set to the limit given. The commit limit controls how muchmemory the MPS will obtain from the OS. See Arena Protocol for details. The commit limit cannot beset to a value that is lower than the number of bytes that the MPS is using. If an attempt is madeto set the commit limit to a value greater than or equal to that returned bymps_arena_committed then it will succeed. If an attempt is made to set the commit limitto a value less than that returned by mps_arena_committed then it will succeed only ifthe amount committed by the MPS can be reduced by reducing the amount of spare committed memory; insuch a case the spare committed memory will be reduced appropriately and the attempt will succeed.

    + + +

    Example

     do {
@@ -3133,155 +3738,171 @@ do {
    -

    Error Handling

    +

    Error Handling

    -

    Returns MPS_RES_OK when successful, and some other result code when not.

    +

    Returns MPS_RES_OK when successful, and some other result code when not.

    -

    See Also

    +

    See Also

    -

    mps_arena_committed, mps_arena_commit_limit, mps_arena_spare_commit_limit_set

    +

    + +mps_arena_committed, + +mps_arena_commit_limit, + +mps_arena_spare_commit_limit_set

    -

    Notes

    +

    Notes

    -

    mps_arena_commit_limit_set puts a limit on all memory committed by the MPS. The"spare committed" memory can be limited separately with mps_arena_spare_commit_limit_set. Note that "spare committed" memory is subject toboth limits; there cannot be more spare committed memory than the spare commit limit, and therecan't be so much spare committed memory that there is more committed memory than the commit limit.

    +

    mps_arena_commit_limit_set puts a limit on all memory committed by the MPS. The"spare committed" memory can be limited separately with mps_arena_spare_commit_limit_set. Note that "spare committed" memory is subject toboth limits; there cannot be more spare committed memory than the spare commit limit, and therecan't be so much spare committed memory that there is more committed memory than the commit limit.

    -

    Function mps_arena_committed

    +

    Function mps_arena_committed

    -

    Name

    +

    Name

    -

    mps_arena_committed

    +

    mps_arena_committed

    -

    Summary

    +

    Summary

    -

    mps_arena_committed returns the amount of memory (backing store) in use by the arena, bothfor storing client objects and for its own data structures.

    +

    mps_arena_committed returns the amount of memory (backing store) in use by the arena, bothfor storing client objects and for its own data structures.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Arena.

    +

    Arena.

    -

    Syntax

    +

    Syntax

    -

    extern size_t mps_arena_committed(mps_arena_t arena)

    +

    extern size_t mps_arena_committed(mps_arena_t arena)

    -

    Arguments

    +

    Arguments

    -

    arena -- the arena

    +

    arena -- the arena

    -

    Returned Values

    +

    Returned Values

    -

    Returns a number of bytes (the amount of committed memory) as a size_t.

    +

    Returns a number of bytes (the amount of committed memory) as a size_t.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_arena_committed returns the amount of memory (backing store) in use by the arena (alsoknown as "committed memory"). The value returned is a number of bytes.

    +

    mps_arena_committed returns the amount of memory (backing store) in use by the arena (alsoknown as "committed memory"). The value returned is a number of bytes.

    -

    Committed memory may be used both for storing client objects and for storing MPS datastructures. In addition the MPS maintains committed memory which is not being used (for either ofthe above purposes). This memory is known as "spare committed" memory (see mps_arena_spare_committed). The amount of "spare committed" memory can change atany time, in particular in will be reduced as appropriate in order meet client requests.

    +

    Committed memory may be used both for storing client objects and for storing MPS datastructures. In addition the MPS maintains committed memory which is not being used (for either ofthe above purposes). This memory is known as "spare committed" memory (see mps_arena_spare_committed). The amount of "spare committed" memory can change atany time, in particular in will be reduced as appropriate in order meet client requests.

    -

    The reasons that the committed memory (as return by this function) might be large than thesum of the sizes of client allocated objects are:

    +

    The reasons that the committed memory (as return by this function) might be large than thesum of the sizes of client allocated objects are:

      -

    • some memory is used internally by the MPS to manage its own data structures and to recordinformation about client objects (such as free lists, page tables, colour tables, statistics, etc).

      • +

    • some memory is used internally by the MPS to manage its own data structures and to recordinformation about client objects (such as free lists, page tables, colour tables, statistics, etc).

      • -

    • operating systems (and hardware) typically restrict programs to requesting and releasingmemory with a certain granularity (for example, pages), so extra memory is committed when thisrounding is necessary.

      • +

    • operating systems (and hardware) typically restrict programs to requesting and releasingmemory with a certain granularity (for example, pages), so extra memory is committed when thisrounding is necessary.

      • -

    • there might be "spare committed" memory.

      • +

    • there might be "spare committed" memory.

    -

    The amount of committed memory is a good measure of how much virtual memory resource ("swapspace") the MPS is using from the OS.

    +

    The amount of committed memory is a good measure of how much virtual memory resource ("swapspace") the MPS is using from the OS.

    -

    This function may be called whether the arena is unclamped, clamped or parked, if calledwhen the arena in unclamped then the value may change after this function returns. A possible usemight be to call it just after mps_arena_collect to (over-)estimate the size of the heap.

    +

    This function may be called whether the arena is unclamped, clamped or parked, if calledwhen the arena in unclamped then the value may change after this function returns. A possible usemight be to call it just after mps_arena_collect to (over-)estimate the size of the heap.

    -

    If you want to know how much memory the MPS is using then you're probably interested in the value mps_arena_committed() - mps_arena_spare_committed().

    +

    If you want to know how much memory the MPS is using then you're probably interested in the value mps_arena_committed() - mps_arena_spare_committed().

    -

    The amount of committed memory can be limited with the function mps_arena_commit_limit.

    +

    The amount of committed memory can be limited with the function mps_arena_commit_limit.

    -

    Example

    +

    Example

    -

    Error Handling

    +

    Error Handling

    -

    See Also

    +

    See Also

    -

    mps_arena_collect, mps_arena_clamp, mps_arena_park, mps_arena_release

    +

    + +mps_arena_collect, + +mps_arena_clamp, + +mps_arena_park, + +mps_arena_release

    -

    Notes

    +

    Notes

    -

    -

    +

    -

    -

    function mps_arena_create

    +

    function mps_arena_create

    -

    Name

    +

    Name

    -

    mps_arena_create

    +

    mps_arena_create

    -

    Summary

    +

    Summary

    -

    mps_arena_create is used to create an arena.

    +

    mps_arena_create is used to create an arena.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Arena.

    +

    Arena.

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_arena_create(mps_arena_t *mps_arena_o, mps_arena_class_t mps_arena_class, ...)

    +

    mps_res_t mps_arena_create(mps_arena_t *mps_arena_o, mps_arena_class_t mps_arena_class, ...)

    -

    Arguments

    +

    Arguments

    -

    mps_arena_o pointer to a variable to store the new arena in

    +

    mps_arena_o pointer to a variable to store the new arena in

    -

    mps_arena_class the arena class

    +

    mps_arena_class the arena class

    -

    ... initialization arguments for the arena class

    +

    ... initialization arguments for the arena class

    Initial/Default Values

    -

    Different for each arena class. See mps_arena_class_*.

    +

    Different for each arena class. See mps_arena_class_*.

    -

    Returned Values

    +

    Returned Values

    -

    If the return value is MPS_RES_OK, the new arena is in *mps_arena_o.

    +

    If the return value is MPS_RES_OK, the new arena is in *mps_arena_o.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_arena_create is used to create an arena.

    +

    mps_arena_create is used to create an arena.

    -

    Example

    +

    Example

     mps_arena_t arena;
@@ -3301,102 +3922,114 @@ int main(void)
    -

    Error Handling

    +

    Error Handling

    -

    mps_arena_create returns MPS_RES_FAIL, if the MPS library iscopy-protected by a security device, such as a dongle, and a valid security device cannot be found.Other error codes are specific to each arena class. See mps_arena_class_*.

    +

    mps_arena_create returns MPS_RES_FAIL, if the MPS library iscopy-protected by a security device, such as a dongle, and a valid security device cannot be found.Other error codes are specific to each arena class. See mps_arena_class_*.

    -

    See Also

    +

    See Also

    -

    mps_arena_create_v, mps_arena_class_*, mps_arena_destroy

    +

    + +mps_arena_create_v, + +mps_arena_class_*, + +mps_arena_destroy

    -

    function mps_arena_create_v

    +

    function mps_arena_create_v

    -

    Name

    +

    Name

    -

    mps_arena_create_v

    +

    mps_arena_create_v

    -

    Summary

    +

    Summary

    -

    mps_arena_create_v is used to create an arena.

    +

    mps_arena_create_v is used to create an arena.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Arena.

    +

    Arena.

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_arena_create_v(mps_arena_t *mps_arena_o, mps_arena_class_t mps_arena_class, va_list args)

    +

    mps_res_t mps_arena_create_v(mps_arena_t *mps_arena_o, mps_arena_class_t mps_arena_class, va_list args)

    -

    Arguments

    +

    Arguments

    -

    mps_arena_o pointer to a variable to store the new arena in

    +

    mps_arena_o pointer to a variable to store the new arena in

    -

    mps_arena_class the arena class

    +

    mps_arena_class the arena class

    -

    args initialization arguments for the arena class

    +

    args initialization arguments for the arena class

    Initial/Default Values

    -

    Different for each arena class. See mps_arena_class_*.

    +

    Different for each arena class. See mps_arena_class_*.

    -

    Returned Values

    +

    Returned Values

    -

    If the return value is MPS_RES_OK, the new arena is in *mps_arena_o.

    +

    If the return value is MPS_RES_OK, the new arena is in *mps_arena_o.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_arena_create_v is used to create an arena. It is exactly the same as mps_arena_create, except that it takes the arena class initialization arguments in a va_list .

    +

    mps_arena_create_v is used to create an arena. It is exactly the same as mps_arena_create, except that it takes the arena class initialization arguments in a va_list .

    -

    Error Handling

    +

    Error Handling

    -

    mps_arena_create_v returns MPS_RES_FAIL, if the MPS library is copy-protected by a security device, such as a dongle, and a valid security device cannot be found. Other error codes are specific to each arena class. See mps_arena_class_*.

    +

    mps_arena_create_v returns MPS_RES_FAIL, if the MPS library is copy-protected by a security device, such as a dongle, and a valid security device cannot be found. Other error codes are specific to each arena class. See mps_arena_class_*.

    -

    See Also

    +

    See Also

    -

    mps_arena_create, mps_arena_class_*, mps_arena_destroy

    +

    + +mps_arena_create, + +mps_arena_class_*, + +mps_arena_destroy

    -

    function mps_arena_formatted_objects_walk

    +

    function mps_arena_formatted_objects_walk

    -

    Name

    +

    Name

    -

    mps_arena_formatted_objects_walk

    +

    mps_arena_formatted_objects_walk

    -

    Summary

    +

    Summary

    -

    mps_arena_formatted_objects_walk is used to iterate over all formatted objects in the MPS heap.

    +

    mps_arena_formatted_objects_walk is used to iterate over all formatted objects in the MPS heap.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    None.

    +

    None.

    -

    Syntax

    +

    Syntax

    -

    mps_arena_formatted_objects_walk(mps_arena, client_step_function, client_step_closure_p,client_step_closure_s);

    +

    mps_arena_formatted_objects_walk(mps_arena, client_step_function, client_step_closure_p,client_step_closure_s);

    -

    Type

    +

    Type

     extern void mps_arena_formatted_objects_walk(mps_arena_t,
@@ -3405,198 +4038,212 @@ extern void mps_arena_formatted_objects_walk(mps_arena_t,
    -

    Arguments

    +

    Arguments

    -

    (mps_arena_t mps_arena, mps_formatted_objects_stepper_t stepper, void *p, size_t s)

    +

    (mps_arena_t mps_arena, mps_formatted_objects_stepper_t stepper, void *p, size_t s)

    -

    mps_arena in an MPS arena object.

    +

    mps_arena in an MPS arena object.

    -

    stepper is a client-supplied function (pointer) of the right type (see mps_formatted_objects_stepper_t). This function is applied to every object in allformatted pools. This function should take the argument list (mps_addr_t object, mps_fmt_t format,mps_pool_t pool, void *p, size_t s). object is the object to which the function is being applied. format is the format (an MPS format object) of the object, pool is the pool in which the object resides, p and s are copies of the corresponding values that the client passed into mps_arena_formatted_objects_walk originally.

    +

    stepper is a client-supplied function (pointer) of the right type (see mps_formatted_objects_stepper_t). This function is applied to every object in allformatted pools. This function should take the argument list (mps_addr_t object, mps_fmt_t format,mps_pool_t pool, void *p, size_t s). object is the object to which the function is being applied. format is the format (an MPS format object) of the object, pool is the pool in which the object resides, p and s are copies of the corresponding values that the client passed into mps_arena_formatted_objects_walk originally.

    -

    p and s are passed into the function specified by the stepper argument whenever the MPS calls that function. See mps_formatted_objects_stepper_t.

    +

    p and s are passed into the function specified by the stepper argument whenever the MPS calls that function. See mps_formatted_objects_stepper_t.

    -

    Returned Values

    +

    Returned Values

    -

    None.

    +

    None.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_arena_formatted_objects_walk is used to iterate over all formatted objects in the MPSheap. A client-supplied function is called for every object in all formatted pools; the object, theformat, and the pool are passed to the user supplied function, as well as some closure variables.

    +

    mps_arena_formatted_objects_walk is used to iterate over all formatted objects in the MPSheap. A client-supplied function is called for every object in all formatted pools; the object, theformat, and the pool are passed to the user supplied function, as well as some closure variables.

    -

    Applies stepper function to a pool-class-specific collection of objects (that is, the poolclass determines which objects in its instances get walked). Typically pool classes will arrangethat all validly formatted objects are walked. During a trace this will in general be only the blackobjects, though the leaf pool class (LO), for example, will walk all objects since they are validlyformatted whether they are black or white. Padding objects may be walked at the pool classesdiscretion, the client should handle this case.

    +

    Applies stepper function to a pool-class-specific collection of objects (that is, the poolclass determines which objects in its instances get walked). Typically pool classes will arrangethat all validly formatted objects are walked. During a trace this will in general be only the blackobjects, though the leaf pool class (LO), for example, will walk all objects since they are validlyformatted whether they are black or white. Padding objects may be walked at the pool classesdiscretion, the client should handle this case.

    -

    Example

    +

    Example

    -

    [not yet]

    +

    [not yet]

    -

    Error Handling

    +

    Error Handling

    -

    There are none.

    +

    There are none.

    -

    See Also

    +

    See Also

    -

    mps_amc_apply (the historical walker), mps_formatted_objects_stepper_t

    +

    +mps_amc_apply (the +historical walker), -

    Notes

    +mps_formatted_objects_stepper_t

    -

    function mps_arena_park

    +

    Notes

    -

    Name

    +

    function mps_arena_park

    -

    mps_arena_park

    +

    Name

    -

    Summary

    +

    mps_arena_park

    -

    mps_arena_park puts the specified arena into the parked state.

    +

    Summary

    -

    Associated Protocols

    +

    mps_arena_park puts the specified arena into the parked state.

    -

    Arena.

    +

    Associated Protocols

    -

    Syntax

    +

    Arena.

    -

    extern void mps_arena_park(mps_arena_t arena);

    +

    Syntax

    -

    Arguments

    +

    extern void mps_arena_park(mps_arena_t arena);

    -

    arena the arena to park

    +

    Arguments

    -

    Returned Values

    +

    arena the arena to park

    -

    None.

    +

    Returned Values

    -

    Resources

    +

    None.

    -

    mps.h

    +

    Resources

    -

    Description

    +

    mps.h

    -

    mps_arena_park puts the specified arena into the parked state. While an arena is parked,no object motion will occur and the staleness of location dependencies will not change. Allreferences to objects loaded while the arena is parked will keep the same binary representationuntil after it is released.

    -

    Any current collection is run to completion before the arena is parked, and no newcollections will start. When an arena is in the parked state, it is necessarily not in the middle ofa collection.

    +

    Description

    +

    mps_arena_park puts the specified arena into the parked state. While an arena is parked,no object motion will occur and the staleness of location dependencies will not change. Allreferences to objects loaded while the arena is parked will keep the same binary representationuntil after it is released.

    -

    Example

    +

    Any current collection is run to completion before the arena is parked, and no newcollections will start. When an arena is in the parked state, it is necessarily not in the middle ofa collection.

    -

    Error Handling

    +

    Example

    -

    Can't fail.

    +

    Error Handling

    -

    See Also

    +

    Can't fail.

    -

    mps_arena_clamp, mps_arena_release

    +

    See Also

    -

    Notes

    +

    -

    None.

    +mps_arena_clamp, +mps_arena_release

    -

    function mps_arena_release

    +

    Notes

    -

    Name

    +

    None.

    -

    mps_arena_release

    +

    function mps_arena_release

    -

    Summary

    -

    mps_arena_release puts the specified arena into the unclamped state.

    +

    Name

    +

    mps_arena_release

    -

    Associated Protocols

    -

    Arena.

    +

    Summary

    +

    mps_arena_release puts the specified arena into the unclamped state.

    -

    Syntax

    -

    extern void mps_arena_release(mps_arena_t);

    +

    Associated Protocols

    +

    Arena.

    -

    Arguments

    +

    Syntax

    -

    Returned Values

    +

    extern void mps_arena_release(mps_arena_t);

    -

    None.

    +

    Arguments

    -

    Resources

    -

    mps.h

    +

    Returned Values

    +

    None.

    -

    Description

    -

    mps_arena_release puts the specified arena into the unclamped state. While an arena isunclamped, garbage collection, object motion, and other background activity can take place.

    +

    Resources

    +

    mps.h

    -

    Example

    +

    Description

    -

    Error Handling

    +

    mps_arena_release puts the specified arena into the unclamped state. While an arena isunclamped, garbage collection, object motion, and other background activity can take place.

    -

    Can't fail.

    +

    Example

    -

    See Also

    -

    mps_arena_clamp, mps_arena_park

    +

    Error Handling

    +

    Can't fail.

    -

    Notes

    -

    None.

    +

    See Also

    +

    -

    function mps_arena_roots_walk

    +mps_arena_clamp, +mps_arena_park

    -

    Name

    -

    mps_arena_roots_walk

    +

    Notes

    +

    None.

    -

    Summary

    -

    mps_arena_roots_walk is used to iterate over all roots of the MPS heap.

    +

    function mps_arena_roots_walk

    -

    Associated Protocols

    +

    Name

    -

    None.

    +

    mps_arena_roots_walk

    -

    Syntax

    +

    Summary

    -

    mps_arena_roots_walk(mps_arena, client_step_function, client_step_closure_p,client_step_closure_s);

    +

    mps_arena_roots_walk is used to iterate over all roots of the MPS heap.

    -

    Type

    +

    Associated Protocols

    + +

    None.

    + + +

    Syntax

    + +

    mps_arena_roots_walk(mps_arena, client_step_function, client_step_closure_p,client_step_closure_s);

    + + +

    Type

       extern void mps_arena_roots_walk(mps_arena_t,
@@ -3605,378 +4252,398 @@ extern void mps_arena_formatted_objects_walk(mps_arena_t,
    -

    Arguments

    +

    Arguments

    -

    (mps_arena_t mps_arena, mps_roots_stepper_t stepper, void *p, size_t s)

    +

    (mps_arena_t mps_arena, mps_roots_stepper_t stepper, void *p, size_t s)

    -

    mps_arena in an MPS arena object.

    +

    mps_arena in an MPS arena object.

    -

    stepper is a client-supplied function (pointer) of the right type (see mps_roots_stepper_t). This function is applied to every reference to the heap fromevery root object registered with the arena. This function should take the argument list (mps_addr_t *ref, mps_root_t root, void *p, size_t s). ref is the address of a root which references an object in the arena. root is the registered root (an MPS root object) of which ref is a single reference, p and s are copies of the corresponding values that the client passed into mps_arena_roots_walk originally.

    +

    stepper is a client-supplied function (pointer) of the right type (see mps_roots_stepper_t). This function is applied to every reference to the heap fromevery root object registered with the arena. This function should take the argument list (mps_addr_t *ref, mps_root_t root, void *p, size_t s). ref is the address of a root which references an object in the arena. root is the registered root (an MPS root object) of which ref is a single reference, p and s are copies of the corresponding values that the client passed into mps_arena_roots_walk originally.

    -

    p and s are passed into the function specified by the stepper argument whenever the MPS calls that function. See mps_roots_stepper_t

    +

    p and s are passed into the function specified by the stepper argument whenever the MPS calls that function. See mps_roots_stepper_t

    -

    Returned Values

    +

    Returned Values

    -

    None.

    +

    None.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_arena_roots_walk is used to iterate over all roots of the MPS heap. A client-suppliedfunction is called for every root reference which points to an object in any automatically managedpools; the address of the root reference and the MPS root object are passed to the user suppliedfunction, as well as some closure variables.

    +

    mps_arena_roots_walk is used to iterate over all roots of the MPS heap. A client-suppliedfunction is called for every root reference which points to an object in any automatically managedpools; the address of the root reference and the MPS root object are passed to the user suppliedfunction, as well as some closure variables.

    -

    May only be called when the arena is in the parked state.

    +

    May only be called when the arena is in the parked state.

    -

    Applies stepper to each reference in any roots registered with the arena and which point toobjects in automatically managed pools. If the root has rank MPS_RANK_AMBIG then the reference mightnot be to the start of an object; the client should handle this case. There is no guarantee that thereference corresponds to the actual location that holds the pointer to the object (since this mightbe a register, for example) - but the actual location will be passed if possible. This may aidanalysis of roots via a debugger.

    +

    Applies stepper to each reference in any roots registered with the arena and which point toobjects in automatically managed pools. If the root has rank MPS_RANK_AMBIG then the reference mightnot be to the start of an object; the client should handle this case. There is no guarantee that thereference corresponds to the actual location that holds the pointer to the object (since this mightbe a register, for example) - but the actual location will be passed if possible. This may aidanalysis of roots via a debugger.

    -

    +

    -

    Example

    +

    Example

    -

    [not yet]

    +

    [not yet]

    -

    Error Handling

    +

    Error Handling

    -

    There are none.

    +

    There are none.

    -

    See Also

    +

    See Also

    -

    mps_roots_stepper_t

    +

    -

    mps_arena_formatted_objects_walk

    +mps_roots_stepper_t

    +

    -

    Notes

    +mps_arena_formatted_objects_walk

    -

    function mps_arena_spare_commit_limit

    +

    Notes

    -

    Name

    +

    function mps_arena_spare_commit_limit

    -

    mps_arena_spare_commit_limit

    +

    Name

    -

    Summary

    +

    mps_arena_spare_commit_limit

    -

    Retrieves the value of the spare commit limit (previously set with mps_arena_spare_commit_limit_set).

    +

    Summary

    -

    Associated Protocols

    +

    Retrieves the value of the spare commit limit (previously set with mps_arena_spare_commit_limit_set).

    -

    Arena.

    +

    Associated Protocols

    -

    Type

    +

    Arena.

    -

    extern size_t mps_arena_spare_commit_limit(mps_arena_t arena)

    +

    Type

    -

    Arguments

    +

    extern size_t mps_arena_spare_commit_limit(mps_arena_t arena)

    -

    mps_arena_t arena

    -

    Specifies the arena to retrieve the spare commit limit of.

    +

    Arguments

    +

    mps_arena_t arena

    -

    Returned Values

    +

    Specifies the arena to retrieve the spare commit limit of.

    -

    Returns, as a size_t, the value of the spare commit limit.

    +

    Returned Values

    -

    Resources

    +

    Returns, as a size_t, the value of the spare commit limit.

    -

    mps.h

    +

    Resources

    -

    Description

    +

    mps.h

    -

    Returns the current value of the spare commit limit which is the value most recently setwith mps_arena_spare_commit_limit_set. (See mps_arena_spare_commit_limit_set fordetails).

    +

    Description

    -

    Example

    +

    Returns the current value of the spare commit limit which is the value most recently setwith mps_arena_spare_commit_limit_set. (See mps_arena_spare_commit_limit_set fordetails).

    -

    [missing]

    +

    Example

    -

    Error Handling

    +

    [missing]

    -

    There are no errors.

    +

    Error Handling

    -

    See Also

    +

    There are no errors.

    -

    mps_arena_spare_commit_limit_set

    +

    See Also

    -

    Notes

    +

    -

    None.

    +mps_arena_spare_commit_limit_set

    -

    function mps_arena_spare_commit_limit_set

    +

    Notes

    +

    None.

    -

    Name

    -

    mps_arena_spare_commit_limit_set

    +

    function mps_arena_spare_commit_limit_set

    -

    Summary

    +

    Name

    -

    Sets the limit of the amount of spare committed memory.

    +

    mps_arena_spare_commit_limit_set

    -

    Associated Protocols

    +

    Summary

    -

    Arena.

    +

    Sets the limit of the amount of spare committed memory.

    -

    Type

    +

    Associated Protocols

    -

    extern void mps_arena_spare_commit_limit_set(mps_arena_t arena, size_t limit)

    +

    Arena.

    -

    Arguments

    +

    Type

    -

    mps_arena_t arena

    +

    extern void mps_arena_spare_commit_limit_set(mps_arena_t arena, size_t limit)

    -

    The arena to which the new limit should apply.

    -

    size_t limit

    +

    Arguments

    -

    The value of the new limit (specified in bytes).

    +

    mps_arena_t arena

    +

    The arena to which the new limit should apply.

    -

    Resources

    +

    size_t limit

    -

    mps.h

    +

    The value of the new limit (specified in bytes).

    -

    +

    Resources

    -

    Description

    +

    mps.h

    -

    The limit argument specifies a new "spare commit limit". The spare commit limit specifiesthe maximum amount of bytes of "spare committed" memory the MPS is allowed to have. Setting it to avalue lower than the current amount of spare committed memory would immediately cause sufficientspare committed memory to be uncommitted so as to bring the value under the limit. In particularsetting to 0 will mean that the MPS will have no "spare committed" memory.

    +

    -

    "spare committed" memory is the term for describing memory which the arena is managing asfree memory (so not in use by any pool and not otherwise in use for obscure internal reasons) butwhich remains committed (mapped from the OS). It is used by the arena to (attempt to) avoid callingthe OS to repeatedly unmap and map areas of VM. "spare committed" memory is counted as committedmemory as counted by mps_arena_committed and restricted by mps_arena_commit_limit.

    -

    Non-VM arenas do not have this concept, but they support the two functions mps_arena_spare_commit_limit and mps_arena_spare_commit_limit_set. The functions simply get andretrieve a value but do nothing else in that case.

    +

    Description

    -

    Initially the value is some configuration-dependent value.

    +

    The limit argument specifies a new "spare commit limit". The spare commit limit specifiesthe maximum amount of bytes of "spare committed" memory the MPS is allowed to have. Setting it to avalue lower than the current amount of spare committed memory would immediately cause sufficientspare committed memory to be uncommitted so as to bring the value under the limit. In particularsetting to 0 will mean that the MPS will have no "spare committed" memory.

    -

    The value of the limit can be retrieved with mps_arena_spare_commit_limit.

    +

    "spare committed" memory is the term for describing memory which the arena is managing asfree memory (so not in use by any pool and not otherwise in use for obscure internal reasons) butwhich remains committed (mapped from the OS). It is used by the arena to (attempt to) avoid callingthe OS to repeatedly unmap and map areas of VM. "spare committed" memory is counted as committedmemory as counted by mps_arena_committed and restricted by mps_arena_commit_limit.

    +

    Non-VM arenas do not have this concept, but they support the two functions mps_arena_spare_commit_limit and mps_arena_spare_commit_limit_set. The functions simply get andretrieve a value but do nothing else in that case.

    -

    Example

    +

    Initially the value is some configuration-dependent value.

    -

    [missing]

    +

    The value of the limit can be retrieved with mps_arena_spare_commit_limit.

    -

    Error Handling

    +

    Example

    -

    There are no errors.

    +

    [missing]

    -

    See Also

    +

    Error Handling

    -

    mps_arena_spare_commit_limit

    +

    There are no errors.

    -

    Notes

    +

    See Also

    -

    None.

    +

    +mps_arena_spare_commit_limit

    -

    function mps_arena_spare_committed

    +

    Notes

    -

    Name

    +

    None.

    -

    mps_arena_spare_committed

    +

    function mps_arena_spare_committed

    -

    Summary

    -

    Returns the number of bytes of spare committed memory.

    +

    Name

    +

    mps_arena_spare_committed

    -

    Associated Protocols

    -

    Memory

    +

    Summary

    +

    Returns the number of bytes of spare committed memory.

    -

    Type

    -

    size_t mps_arena_spare_committed(mps_arena_t);

    +

    Associated Protocols

    +

    Memory

    -

    Arguments

    -

    mps_arena_t mps_arena

    +

    Type

    -

    The arena to which the query applies.

    +

    size_t mps_arena_spare_committed(mps_arena_t);

    -

    Returned Values

    +

    Arguments

    -

    Returns the number of bytes of spare committed memory.

    +

    mps_arena_t mps_arena

    +

    The arena to which the query applies.

    -

    Resources

    -

    mps.h

    +

    Returned Values

    +

    Returns the number of bytes of spare committed memory.

    -

    Description

    -

    "Spare committed" memory is the term for describing memory which the arena is committed fromthe OS but which is free (so not in use by any pool and not otherwise in use for obscure internalreasons). It is used by the arena to (attempt to) avoid calling the OS to repeatedly uncommit andcommit areas of VM (because calling the OS to commit and uncommit memory is typically expensive)."Spare committed" memory can be used for grant client requests; if this is done when the MPS wouldotherwise have had to call the OS to commit more memory then the MPS has avoid some OS calls.

    +

    Resources

    -

    "spare committed" memory is counted as part of committed memory. The amount of committedmemory can be retrieved with mps_arena_committed (see mps_arena_committed).

    +

    mps.h

    -

    The amount of "spare committed" memory can be limited by using mps_arena_spare_commit_limit_set (see mps_arena_spare_commit_limit_set ), and the valueof that limit can be retrieved with mps_arena_spare_commit_limit (see mps_arena_spare_commit_limit ). This is analogous to the functions for limiting theamount of committed memory.

    +

    Description

    -

    Example

    +

    "Spare committed" memory is the term for describing memory which the arena is committed fromthe OS but which is free (so not in use by any pool and not otherwise in use for obscure internalreasons). It is used by the arena to (attempt to) avoid calling the OS to repeatedly uncommit andcommit areas of VM (because calling the OS to commit and uncommit memory is typically expensive)."Spare committed" memory can be used for grant client requests; if this is done when the MPS wouldotherwise have had to call the OS to commit more memory then the MPS has avoid some OS calls.

    -

    [missing]

    +

    "spare committed" memory is counted as part of committed memory. The amount of committedmemory can be retrieved with mps_arena_committed (see mps_arena_committed).

    +

    The amount of "spare committed" memory can be limited by using mps_arena_spare_commit_limit_set (see mps_arena_spare_commit_limit_set ), and the valueof that limit can be retrieved with mps_arena_spare_commit_limit (see mps_arena_spare_commit_limit ). This is analogous to the functions for limiting theamount of committed memory.

    -

    Error Handling

    -

    [missing]

    +

    Example

    +

    [missing]

    -

    See Also

    -

    mps_arena_spare_commit_limit_set, mps_arena_spare_commit_limit

    +

    Error Handling

    +

    [missing]

    -

    Notes

    -

    None.

    +

    See Also

    +

    -

    function mps_assert_default

    +mps_arena_spare_commit_limit_set, +mps_arena_spare_commit_limit

    -

    Name

    -

    mps_assert_default

    +

    Notes

    +

    None.

    -

    Summary

    -

    mps_assert_default returns a pointer to the default assertion handler.

    +

    function mps_assert_default

    -

    Associated Protocols

    +

    Name

    -

    Assertion.

    +

    mps_assert_default

    -

    Syntax

    +

    Summary

    +

    mps_assert_default returns a pointer to the default assertion handler.

    -

    Arguments

    -

    None.

    +

    Associated Protocols

    +

    Assertion.

    -

    Initial/Default Values

    -

    None.

    +

    Syntax

    -

    Returned Values

    +

    Arguments

    -

    A pointer to the default assertion handler.

    +

    None.

    -

    Resources

    +

    Initial/Default Values

    -

    mps.h

    +

    None.

    -

    Description

    +

    Returned Values

    -

    mps_assert_default returns a pointer to the default assertion handler. It is intended tobe used in conjunction with mps_assert_install.

    +

    A pointer to the default assertion handler.

    -

    You may also call the default assertion handler directly, in which case the first, second,and third arguments must be non-NULL pointers to zero-terminated strings.

    +

    Resources

    -

    Example

    +

    mps.h

    -

    Error Handling

    +

    Description

    -

    Can't fail.

    +

    mps_assert_default returns a pointer to the default assertion handler. It is intended tobe used in conjunction with mps_assert_install.

    +

    You may also call the default assertion handler directly, in which case the first, second,and third arguments must be non-NULL pointers to zero-terminated strings.

    -

    See Also

    -

    mps_assert_install

    +

    Example

    -

    "Assertion Protocol"

    +

    Error Handling

    -

    Notes

    +

    Can't fail.

    -

    None.

    +

    See Also

    -

    function mps_assert_install

    +

    +mps_assert_install

    -

    Name

    +

    "Assertion Protocol"

    -

    mps_assert_install

    +

    Notes

    -

    Summary

    +

    None.

    -

    mps_assert_install installs the specified assertion handler as the current assertionhandler.

    +

    function mps_assert_install

    -

    Associated Protocols

    -

    Assertion.

    +

    Name

    +

    mps_assert_install

    -

    Syntax

    -

    mps_assert_t mps_assert_install(void my_assertion_handler);

    +

    Summary

    +

    mps_assert_install installs the specified assertion handler as the current assertionhandler.

    -

    Arguments

    -

    my_assertion_handler the handler that you want to install

    +

    Associated Protocols

    +

    Assertion.

    -

    Returned Values

    -

    A pointer to the previously installed assertion handler.

    +

    Syntax

    +

    mps_assert_t mps_assert_install(void my_assertion_handler);

    -

    Resources

    -

    mps.h

    +

    Arguments

    +

    my_assertion_handler the handler that you want to install

    -

    Description

    -

    mps_assert_install installs the specified assertion handler as the current assertionhandler. It returns a pointer to the previously installed assertion handler. Note that there is oneMPS assertion handler for the entire process (in particular it is not per arena).

    +

    Returned Values

    +

    A pointer to the previously installed assertion handler.

    -

    Example

    + +

    Resources

    + +

    mps.h

    + + +

    Description

    + +

    mps_assert_install installs the specified assertion handler as the current assertionhandler. It returns a pointer to the previously installed assertion handler. Note that there is oneMPS assertion handler for the entire process (in particular it is not per arena).

    + + +

    Example

     mps_assert_t old_handler;
@@ -4004,110 +4671,112 @@ const char *file, unsigned int line)
    -

    Error Handling

    +

    Error Handling

    -

    See Also

    +

    See Also

    -

    mps_assert_default

    +

    + +mps_assert_default

    -

    Notes

    +

    Notes

    -

    None.

    +

    None.

    -

    type mps_assert_t

    +

    type mps_assert_t

    -

    Name

    +

    Name

    -

    mps_assert_t

    +

    mps_assert_t

    -

    Summary

    +

    Summary

    -

    mps_assert_t is the type of assertion handlers in the MPS.

    +

    mps_assert_t is the type of assertion handlers in the MPS.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Assertion.

    +

    Assertion.

    -

    Syntax

    +

    Syntax

    -

    typedef void (*mps_assert_t)(const char *, const char *, const char *, unsigned); -

    +

    typedef void (*mps_assert_t)(const char *, const char *, const char *, unsigned); +

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_assert_t is the type of assertion handlers in the MPS.

    +

    mps_assert_t is the type of assertion handlers in the MPS.

    -

    +

    -

    Example

    +

    Example

    -

    See Also

    +

    See Also

    -

    Notes

    +

    Notes

    -

    None.

    +

    None.

    -

    function mps_bool_t

    +

    function mps_bool_t

    -

    Name

    +

    Name

    -

    mps_bool_t

    +

    mps_bool_t

    -

    Summary

    +

    Summary

    -

    mps_bool_t is a transparent type, equivalent to int, that is used in the MPS C interfaceto indicate that a boolean value is intended.

    +

    mps_bool_t is a transparent type, equivalent to int, that is used in the MPS C interfaceto indicate that a boolean value is intended.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Not applicable.

    +

    Not applicable.

    -

    Syntax

    +

    Syntax

    -

    Not applicable.

    +

    Not applicable.

    -

    Structure

    +

    Structure

    -

    Not applicable.

    +

    Not applicable.

    -

    Type

    +

    Type

    -

    typedef int mps_bool_t;

    +

    typedef int mps_bool_t;

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    When used as an input parameter to the MPS, a value of 0 indicates "false" and any othervalue indicates "true". As an output parameter or function return from the MPS, 0 indicates "false",and 1 indicates "true". Note that an mps_bool_t value can be used in a conditional context, suchas in an "if" statement.

    +

    When used as an input parameter to the MPS, a value of 0 indicates "false" and any othervalue indicates "true". As an output parameter or function return from the MPS, 0 indicates "false",and 1 indicates "true". Note that an mps_bool_t value can be used in a conditional context, suchas in an "if" statement.

    -

    Example

    +

    Example

       if(mps_ld_isstale(&ld, space, obj)) {
@@ -4117,447 +4786,153 @@ const char *file, unsigned int line)
    -

    See Also

    +

    See Also

    -

    Notes

    +

    Notes

    -

    None.

    +

    None.

    -

    function mps_class_amc

    +

    function mps_class_amc

    -

    Name

    +

    Name

    -

    mps_class_amc

    +

    mps_class_amc

    -

    +

    -

    Summary

    +

    Summary

    -

    mps_class_amc returns the pool class object for the Automatic Mostly Copying pool class.

    +

    mps_class_amc returns the pool class object for the Automatic Mostly Copying pool class.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Pool

    +

    Pool

    -

    Syntax

    +

    Syntax

    -

    mps_class_t mps_class_amc(void)

    +

    mps_class_t mps_class_amc(void)

    -

    Arguments

    +

    Arguments

    -

    No arguments.

    +

    No arguments.

    -

    Returned Values

    +

    Returned Values

    -

    Returns a pool class object.

    +

    Returns a pool class object.

    -

    Resources

    +

    Resources

    -

    mpscamc.h

    +

    mpscamc.h

    -

    Description

    +

    Description

    -

    This function returns an object of type mps_class_t which represents the Automatic MostlyCopying pool class.

    +

    This function returns an object of type mps_class_t which represents the Automatic MostlyCopying pool class.

    -

    This pool class requires an extra argument when used in mps_pool_create:

    +

    This pool class requires an extra argument when used in mps_pool_create:

      res = mps_pool_create(&pool, arena, mps_class_amc(), format);
    -

    The extra argument, format, should be of type mps_fmt_t and specifies the format of theobjects allocated in the pool.

    +

    The extra argument, format, should be of type mps_fmt_t and specifies the format of theobjects allocated in the pool.

    -

    An AMC pool is both scannable and collectable. Objects may contain exact references to otherobjects that will preserve such other objects. Objects may be reclaimed if they are not reachablefrom a root. Objects may move during collection, unless reachable via a (direct) ambiguousreference. Objects in an AMC pool may be registered for finalization. Exact (that is, non-ambiguous)references into an object in an AMC pool must be to the start of the object.

    +

    An AMC pool is both scannable and collectable. Objects may contain exact references to otherobjects that will preserve such other objects. Objects may be reclaimed if they are not reachablefrom a root. Objects may move during collection, unless reachable via a (direct) ambiguousreference. Objects in an AMC pool may be registered for finalization. Exact (that is, non-ambiguous)references into an object in an AMC pool must be to the start of the object.

    -

    The AMC pool class exploits assumptions about object lifetimes and inter-connectionvariously referred to as "the generational hypothesis". In particular, the following tendencies willbe efficiently exploited by such a pool:

    +

    The AMC pool class exploits assumptions about object lifetimes and inter-connectionvariously referred to as "the generational hypothesis". In particular, the following tendencies willbe efficiently exploited by such a pool:

    -

    - Most objects die young;

    +

    - Most objects die young;

    -

    - Objects that don't die young will live a long time;

    +

    - Objects that don't die young will live a long time;

    -

    - Most references are backwards in time.

    +

    - Most references are backwards in time.

    -

    mps_ap_frame_push and mps_ap_frame_pop may be used on an allocation point in an AMC pool.They do not declare the affected objects to be definitely dead (compare with the SNC pool class),but have an undefined effect on the collection strategy.

    +

    mps_ap_frame_push and mps_ap_frame_pop may be used on an allocation point in an AMC pool.They do not declare the affected objects to be definitely dead (compare with the SNC pool class),but have an undefined effect on the collection strategy.

    -

    If an allocation point is created in an AMC pool, the call to mps_ap_create will take noadditional parameters.

    +

    If an allocation point is created in an AMC pool, the call to mps_ap_create will take noadditional parameters.

    -

    +

    -

    Example

    +

    Example

    -

    See Also

    - -

    mps_ap_frame_pop, mps_ap_frame_push, mps_ap_create

    - - -

    mps_class_epdl_debug

    - - -

    Name

    - -

    mps_class_epdl_debug

    - - -

    Summary

    - -

    Returns the EPDLDebug pool class.

    - - -

    Associated Protocols

    - -

    Debug.

    - - -

    Syntax

    - -

    mps_class_t mps_class_epdl_debug(void)

    - - -

    Returned Values

    - -

    Returns the EPDLDebug pool class.

    - - -

    Resources

    - -

    mpscepdl.h

    - - -

    Description

    - -

    This function is used to get hold of the EPDLDebug pool class, for the purpose of passing itto mps_pool_create.

    - -

    The EPDLDebug pool class is just like an EPDL pool class, except with debug featuresenabled.

    - - -

    Example

    - -
    -static mps_pool_debug_option_s debugOptions = { (void *)"postpost", 8 };
-
-if(mps_pool_create(&pool, arena, mps_class_epdl_debug(),
-                   &debugOptions, 8192, 135, 8)
-   != MPS_RES_OK) {
-  printf("Error creating pool!");
-  exit(2);
-}
-
    - - -

    Error Handling

    - -

    Never fails.

    - - -

    See Also

    - -

    mps_class_epdl, mps_pool_debug_option_s

    - - -

    Notes

    - -

    This pool class has four extra parameters to mps_pool_create: the first one is an mps_pool_debug_option_s structure (q.v.) for the debug options, and the rest are asfor EPDL, see mps_class_epdl for a description of those.

    - -

    Apart from the debug features, the behaviour of this pool class is like EPDL. Usingfenceposts will, naturally, increase the size of objects, which might have an effect on theirplacement.

    - - -

    mps_class_epdr_debug

    - - -

    Name

    - -

    mps_class_epdr_debug

    - - -

    Summary

    - -

    Returns the EPDRDebug pool class.

    - - -

    Associated Protocols

    - -

    Debug.

    - - -

    Syntax

    - -

    mps_class_t mps_class_epdr_debug(void)

    - - -

    Returned Values

    - -

    Returns the EPDRDebug pool class.

    - - -

    Resources

    - -

    mpscepdl.h

    - - -

    Description

    - -

    This function is used to get hold of the EPDRDebug pool class, for the purpose of passing itto mps_pool_create.

    - -

    The EPDRDebug pool class is just like an EPDR pool class, except with debug featuresenabled.

    - - -

    Example

    - -
    -static mps_pool_debug_option_s debugOptions = { (void *)"postpost", 8 };
-
-if(mps_pool_create(&pool, arena, mps_class_epdr_debug(),
-                   &debugOptions, 8192, 135, 8)
-   != MPS_RES_OK) {
-  printf("Error creating pool!");
-  exit(2);
-}
-
    - - -

    Error Handling

    - -

    Never fails.

    - - -

    See Also

    - -

    mps_class_epdr, mps_pool_debug_option_s

    - - -

    Notes

    - -

    This pool class has four extra parameters to mps_pool_create: the first one is an mps_pool_debug_option_s structure (q.v.) for the debug options, and the rest are asfor EPDR, see mps_class_epdr for a description of those.

    - -

    Apart from the debug features, the behaviour of this pool class is like EPDR. Usingfenceposts will, naturally, increase the size of objects, which might have an effect on theirplacement.

    - - -

    mps_class_mv2

    - - -

    Name

    - -

    mps_class_mv2

    - - -

    Summary

    - -

    mps_class_mv2 is a function that returns the MV2 pool class object.

    - - -

    Associated Protocols

    - -

    Allocation point.

    - - -

    Syntax

    - -

    mps_class_t mps_class_mv2(void);

    - - -

    Type

    - -

    C function

    - - -

    Arguments

    - -

    None.

    - - -

    Returned Values

    - -

    The MV2 pool class object.

    - - -

    Resources

    - -

    mpscmv2.h

    - - -

    Description

    - -

    The function mps_class_mv2 returns the MV2 pool class object, which can be used to create anMV2 pool instance by passing the class object as the mps_class_t (third) argument to mps_pool_create.

    - -

    The MV2 pool class manually manages variable-sized, unformatted objects. The MV2 pool usesan allocation policy termed "temporal fit". Temporal fit attempts to place consecutive allocationsnext to each other. It relies on delaying reuse as long as possible to permit freed blocks tocoalesce, thus maximizing the number of consecutive allocations that can be co-located. Temporal fitpermits a very fast allocator and a deallocator competitive in speed with all other known policies.

    +

    See Also

    - Temporal fit is intended to take advantage of knowledge of object lifetimes, either - - apriori - - knowledge or knowledge acquired by profiling. The best performance of the MV2 poolwill be achieved by allocating objects with similar expected deathtimes together. -

    -

    A simple policy can be implemented to take advantage of MV2: Object size is typicallywell-correlated with object life-expectancy, and birthtime plus lifetime gives deathtime, soallocating objects of similar size sequentially from the same pool instance should result in objectsallocated close to each other dying at about the same time.

    +mps_ap_frame_pop, -

    An application that has several classes of objects of widely differing life expectancy willbest be served by creating a different MV2 pool instance for each life-expectancy class. A moresophisticated policy can use either the programmer's knowledge of the expected lifetime of an objector any characteristic of objects that correlates with lifetime to choose an appropriate poolinstance to allocate in.

    +mps_ap_frame_push, -

    Allocating objects with unknown or very different deathtimes together will pessimize thespace performance of MV2.

    +mps_ap_create

    -

    Example

    +

    function mps_class_mvff

    -
    -  if(mps_pool_create(&pool, arena, mps_class_mv2(), 8, 32, 256, 70, 20)
-     != MPS_RES_OK) {
-   printf("Error creating pool!");
-   exit(2);
- }
-
    -

    Error Handling

    +

    Name

    -

    mps_class_mv2 cannot result in an error.

    +

    mps_class_mvff

    +

    -

    See Also

    -

    mps_pool_create

    +

    Summary

    +

    Used as a parameter to mps_pool_create to create an MVFF pool.

    -

    Notes

    -

    - - Creation - -

    +

    Associated Protocols

    -

    The MV2 pool class has five creation parameters:

    +

    Pool, Allocation Points.

    -
    -  mps_res_t mps_pool_create(mps_pool_t * pool, mps_arena_t arena,
-  mps_class_t mv2_class, size_t minimum_size,
-  size_t mean_size, size_t maximum_size,
-  mps_count_t reserve_depth mps_count_t fragmentation_limit);
-
    -

    Sizes

    +

    Type

    -

    minimum_size, mean_size, and maximum_size are the minimum, mean, and maximum (typical) sizein bytes of objects expected to be allocated in the pool. Objects smaller than minimum size may beallocated, but the pool is not guaranteed to manage them space-efficiently. Objects larger thanmaximum_size may be allocated, but the pool is not guaranteed to manage them space-efficiently.Furthermore, partial freeing is not supported for objects larger than maximum size; doing so willresult in the storage of the object never being reused. Mean_size need not be an accurate mean,although the pool will manage mean_size objects more efficiently.

    +

    mps_class_t mps_class_mvff(void)

    -

    Reserve Depth

    -

    reserve_depth is the expected hysteresis of the object population. When pool objects arefreed, the pool will retain sufficient storage to allocate reserve_depth objects of mean_size fornear term allocations (rather than immediately making that storage available to other pools).

    +

    Arguments

    -

    If a pool has a stable object population, one which only grows over the lifetime of thepool, or one which grows steadily and then shrinks steadily, use a reserve_depth of 0.

    +

    None.

    -

    It is always safe to use a reserve depth of 0, but if the object population typicallyfluctuates in a range (e.g., the client program may repeatedly create and destroy a subset ofobjects in a loop), it is more efficient for the pool to retain enough storage to satisfy thatfluctuation. For example, if a pool has an object population that typically fluctuates between 8,000and 10,000, use a reserve_depth of 2,000.

    -

    The reserve will not normally be available to other pools for allocation, even when it isnot used by the pool. If this is undesirable, a reserve depth of 0 may be used for a pool whoseobject population does vary, at a slight cost in efficiency. The reserve does not guarantee anyparticular amount of allocation.

    +

    Returned Values

    -

    Fragmentation Limit

    +

    The function returns a class object that can be passed to mps_pool_create.

    -

    fragmentation_limit is a percentage in (0, 100] that can be used to set an upper limit onthe space overhead of MV2 in case object deathtimes and allocations do not correlate well.

    -

    If the free space managed by the pool as a ratio of all the space managed by the poolexceeds the specified percentage, the pool will fall back to a first fit allocation policy,exploiting space more efficiently at a cost in time efficiency.

    +

    Resources

    -

    A fragmentation_limit of 0 would cause the pool to operate as a first-fit pool, at asignificant cost in time-efficiency, therefore is not permitted.

    +

    mpscmvff.h

    -

    A fragmentation_limit of 100 will cause the pool to use temporal fit (unless resources areexhausted). If the objects allocated in the pool have similar lifetime expectancies, this mode willhave the best time- and space-efficiency. If the objects have widely varying lifetime expectancies,this mode will be time-efficient, but may be space-inefficient. An intermediate setting can be usedto limit the space-inefficiency of temporal fit due to varying object life expectancies.

    -

    - - Allocation - -

    +

    Description

    -

    The MV2 pool class only supports allocation through allocation points. See mps_ap_create.

    - -

    - - Deallocation - -

    - -

    The MV2 pool class supports explicit freeing. See mps_pool_free.

    - - -

    Internal Notes

    - -

    Need a life-expectancy parameter! How else will different instances choose their Loci?

    - -

    Need an alignment parameter. Perhaps this is embedded in a format parameter (when all poolshave at least a null format).

    - -

    It is conceivable that a client would want to mix manual and automatic pools with the manualpool being able to be a root for the automatic. To do so, MV2 would need to support formattedobjects and scanning. This may be added someday.

    - -

    Eventually the MM product will include profiling tools that will help determine objectcharacteristics that correlate with object lifetime and suggest how to configure the appropriatenumber of MV2 pool instances and what characteritics to dispatch on when choosing which instance toallocate from.

    - -

    [From mail.ptw.1998-08-19.02-33(0) ]

    - -

    Remember Wilson's statement that the goal of a memory manager is to exploit the regularitiesin allocation patterns? My intent in the interface parameters is to accept measurable regularitiesin object populations, then the implementation can exploit them.

    - -

    Perhaps the pool should accept some description of the mean and deviation of the objectsizes, object population, and object lifetimes. Is that what you are getting at? [Reserve_depth isin some sense a deviation.]

    - - -

    function mps_class_mvff

    - - -

    Name

    - -

    mps_class_mvff

    - -

    - - -

    Summary

    - -

    Used as a parameter to mps_pool_create to create an MVFF pool.

    - - -

    Associated Protocols

    - -

    Pool, Allocation Points.

    - - -

    Type

    - -

    mps_class_t mps_class_mvff(void)

    - - -

    Arguments

    - -

    None.

    - - -

    Returned Values

    - -

    The function returns a class object that can be passed to mps_pool_create.

    - - -

    Resources

    - -

    mpscmvff.h

    - - -

    Description

    - -

    MVFF pools implement a first-fit policy, and can be configured to be functionally equivalentto an EPDL or EPDR pool, but with better overall performance. The pool requires six parameters topool creation:

    +

    MVFF pools implement a first-fit policy. The pool requires six +parameters to pool creation:

    @@ -4567,14 +4942,14 @@ if(mps_pool_create(&pool, arena, mps_class_epdr_debug(), sizeof(void *).

    -

    The three boolean parameters should be set to (0, 0, 1) to emulate EPDL, and (1, 1, 1) toemulate EPDR. No other settings of these parameters is currently recommended.

    +

    The three boolean parameters may be set to (0, 0, 1) or (1, 1, 1). No other settings of these parameters is currently recommended.

    -

    Buffered allocation (mps_reserve and mps_commit) is also supported, but in that case, thepolicy is rather different: buffers are filled worst-fit, and allocation is always upwards from thebase. The arenaHigh parameter regulates whether new segments are acquired at high or low addresses;the slotHigh and firstFit parameters do not affect buffered allocation. Buffered and unbufferedallocation can be used at the same time, but in that case, the first allocation point must becreated before any call to mps_alloc.

    +

    Buffered allocation (mps_reserve and mps_commit) is also supported, but in that case, thepolicy is rather different: buffers are filled worst-fit, and allocation is always upwards from thebase. The arenaHigh parameter regulates whether new segments are acquired at high or low addresses;the slotHigh and firstFit parameters do not affect buffered allocation. Buffered and unbufferedallocation can be used at the same time, but in that case, the first allocation point must becreated before any call to mps_alloc.

    -

    Cached allocation ( MPS_SAC_ALLOC and MPS_SAC_FREE ) is also supported, but in that case,the policy is a little different: allocation from the cache follows its own policy (typicallyfirst-fit), and only when the cache needs to acquire more blocks from the underlying MVFF pool doesit use the usual algorithm to choose blocks for the cache.

    +

    Cached allocation ( MPS_SAC_ALLOC and MPS_SAC_FREE ) is also supported, but in that case,the policy is a little different: allocation from the cache follows its own policy (typicallyfirst-fit), and only when the cache needs to acquire more blocks from the underlying MVFF pool doesit use the usual algorithm to choose blocks for the cache.

    -

    Example

    +

    Example

       if(mps_pool_create(&pool, arena, mps_class_mvff(), 8 * 1024, 135, 4, 0, 0, 1)
@@ -4585,166 +4960,352 @@ if(mps_pool_create(&pool, arena, mps_class_epdr_debug(),
    -

    See Also

    +

    See Also

    -

    mps_pool_create, mps_class_epdr, mps_class_epdl, mps_reserve, mps_commit,

    +

    + +mps_pool_create, + +mps_reserve, + +mps_commit.

    -

    Notes

    +

    Notes

    -

    It is usually not advisable to use buffered and unbuffered allocationat the same time,because the worst-fit policy of buffer filling will grab all the large blocks, leading to severefragmentation. Use two separate pools instead.

    +

    It is usually not advisable to use buffered and unbuffered allocationat the same time,because the worst-fit policy of buffer filling will grab all the large blocks, leading to severefragmentation. Use two separate pools instead.

    -

    Note that using buffered allocation prevents (for obscure technical reasons) the pool fromallocating across segment boundaries. This can cause added external fragmentation if objects areallocated that are a significant fraction of the segment size. (This quirk will disappear in afuture version.)

    +

    Note that using buffered allocation prevents (for obscure technical reasons) the pool fromallocating across segment boundaries. This can cause added external fragmentation if objects areallocated that are a significant fraction of the segment size. (This quirk will disappear in afuture version.)

    -

    function mps_class_snc

    +

    function mps_class_snc

    -

    Name

    +

    Name

    -

    mps_class_snc

    +

    mps_class_snc

    -

    +

    -

    Summary

    +

    Summary

    -

    Returns the pool class object (of type mps_class_t) for the Stack No Check pool class.

    +

    Returns the pool class object (of type mps_class_t) for the Stack No Check pool class.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Pool.

    +

    Pool.

    -

    Syntax

    +

    Syntax

    -

    mps_class_t mps_class_snc(void)

    +

    mps_class_t mps_class_snc(void)

    -

    Arguments

    +

    Arguments

    -

    No arguments.

    +

    No arguments.

    -

    Returned Values

    +

    Returned Values

    -

    Returns a pool class object.

    +

    Returns a pool class object.

    -

    Resources

    +

    Resources

    -

    mpscsnc.h

    +

    mpscsnc.h

    -

    Description

    +

    Description

    -

    This function returns an object of type mps_class_t which represents the Stack No Check poolclass.

    +

    This function returns an object of type mps_class_t which represents the Stack No Check poolclass.

    -

    This pool class requires an extra argument when used in mps_pool_create:

    +

    This pool class requires an extra argument when used in mps_pool_create:

      res = mps_pool_create(&pool, arena, mps_class_snc(), format);
    -

    The extra argument, format, should be of type mps_fmt_t and specifies the format of theobjects allocated in the pool (in a similar way to mps_class_amc). The format should provide atleast the methods: scan, skip, pad.

    +

    The extra argument, format, should be of type mps_fmt_t and specifies the format of theobjects allocated in the pool (in a similar way to mps_class_amc). The format should provide atleast the methods: scan, skip, pad.

    -

    An SNC pool is scannable, in that objects may contain references to objects in other poolsthat will keep those objects alive (depending on rank). In this sense, an SNC pool is a de-factoroot.

    +

    An SNC pool is scannable, in that objects may contain references to objects in other poolsthat will keep those objects alive (depending on rank). In this sense, an SNC pool is a de-factoroot.

    -

    Exact references may point to (the start of) objects in an SNC pool, but will have no effecton whether those objects are either scanned or kept alive.

    +

    Exact references may point to (the start of) objects in an SNC pool, but will have no effecton whether those objects are either scanned or kept alive.

    -

    If mps_ap_frame_pop is used on an allocation point in an SNC pool (after a correspondingcall to mps_ap_frame_push), then the objects affected by the pop are effectively declared dead, andmay be reclaimed by the collector. Extant references to such objects from reachable or de factoalive objects are safe, but such other objects should be dead; that is, such references must neverbe used.

    +

    If mps_ap_frame_pop is used on an allocation point in an SNC pool (after a correspondingcall to mps_ap_frame_push), then the objects affected by the pop are effectively declared dead, andmay be reclaimed by the collector. Extant references to such objects from reachable or de factoalive objects are safe, but such other objects should be dead; that is, such references must neverbe used.

    -

    If an allocation point is created in an SNC pool, then the call to mps_ap_create will takeas an additional parameter the rank (of type mps_rank_t) of references in the objects to be createdin that allocation point. Currently, only rank exact (mps_rank_exact) is supported.

    +

    If an allocation point is created in an SNC pool, then the call to mps_ap_create will takeas an additional parameter the rank (of type mps_rank_t) of references in the objects to be createdin that allocation point. Currently, only rank exact (mps_rank_exact) is supported.

    -

    Objects in an SNC pool may not be registered for finalization.

    +

    Objects in an SNC pool may not be registered for finalization.

    -

    Objects in an SNC pool will not move.

    +

    Objects in an SNC pool will not move.

    -

    +

    -

    Example

    +

    Example

    -

    Nya

    +

    Nya

    -

    Error Handling

    +

    Error Handling

    -

    Cannot fail.

    +

    Cannot fail.

    -

    +

    -

    See Also

    +

    See Also

    -

    mps_class_amc, mps_ap_frame_pop, mps_ap_frame_push, mps_ap_create

    +

    + +mps_class_amc, + +mps_ap_frame_pop, + +mps_ap_frame_push, + +mps_ap_create

    -

    Type mps_class_t

    +

    mps_class_mvt

    -

    Name

    +

    Name

    -

    mps_class_t

    +

    mps_class_mvt

    -

    Summary

    +

    Summary

    -

    mps_class_t is the type of pool classes.

    +

    mps_class_mvt is a function that returns the MVT pool class object.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Pool.

    +

    Allocation point.

    -

    Resources

    +

    Syntax

    -

    mps.h

    +

    mps_class_t mps_class_mvt(void);

    -

    Description

    +

    Type

    -

    mps_class_t is the abstract type of pool classes. It is opaque. A pool class may beobtained by calling the class function for the appropriate class, such as mps_class_amc for theAMC class. A pool class is used when creating a pool with mps_pool_create or mps_pool_create_v.

    +

    C function

    -

    Example

    +

    Arguments

    + +

    None.

    -

    See Also

    +

    Returned Values

    -

    mps_pool_create, mps_pool_create_v

    +

    The MVT pool class object.

    -

    Notes

    +

    Resources

    -

    mps_class_s is an incomplete structure type used only to define mps_class_t.

    +

    mpscmv2.h

    -

    function mps_finalize

    +

    Description

    + +

    The function mps_class_mvt returns the MVT pool +class object, which can be used to create an MVT pool instance by +passing the class object as the mps_class_t (third) argument to +mps_pool_create.

    + +

    The MVT pool class manually manages variable-sized, unformatted objects. The MVT pool usesan allocation policy termed "temporal fit". Temporal fit attempts to place consecutive allocationsnext to each other. It relies on delaying reuse as long as possible to permit freed blocks tocoalesce, thus maximizing the number of consecutive allocations that can be co-located. Temporal fitpermits a very fast allocator and a deallocator competitive in speed with all other known policies.

    + +

    + Temporal fit is intended to take advantage of knowledge of object lifetimes, either + + apriori + + knowledge or knowledge acquired by profiling. The best performance of the MVT poolwill be achieved by allocating objects with similar expected deathtimes together. +

    + +

    A simple policy can be implemented to take advantage of MVT: Object size is typicallywell-correlated with object life-expectancy, and birthtime plus lifetime gives deathtime, soallocating objects of similar size sequentially from the same pool instance should result in objectsallocated close to each other dying at about the same time.

    + +

    An application that has several classes of objects of widely differing life expectancy willbest be served by creating a different MVT pool instance for each life-expectancy class. A moresophisticated policy can use either the programmer's knowledge of the expected lifetime of an objector any characteristic of objects that correlates with lifetime to choose an appropriate poolinstance to allocate in.

    + +

    Allocating objects with unknown or very different deathtimes together will pessimize thespace performance of MVT.

    -

    Name

    +

    Example

    -

    mps_finalize

    +
    +  if(mps_pool_create(&pool, arena, mps_class_mvt(), 8, 32, 256, 70, 20)
+     != MPS_RES_OK) {
+   printf("Error creating pool!");
+   exit(2);
+ }
+
    + +

    Error Handling

    + +

    mps_class_mvt cannot result in an error.

    -

    Summary

    +

    See Also

    -

    Registers an object for finalization.

    +

    + +mps_pool_create

    -

    Associated Protocols

    +

    Notes

    -

    Finalization, message.

    +

    + + Creation + +

    + +

    The MVT pool class has five creation parameters:

    + +
    +  mps_res_t mps_pool_create(mps_pool_t * pool, mps_arena_t arena,
+  mps_class_t mvt_class, size_t minimum_size,
+  size_t mean_size, size_t maximum_size,
+  mps_count_t reserve_depth mps_count_t fragmentation_limit);
+
    + +

    Sizes

    + +

    minimum_size, mean_size, and maximum_size are the minimum, mean, and maximum (typical) sizein bytes of objects expected to be allocated in the pool. Objects smaller than minimum size may beallocated, but the pool is not guaranteed to manage them space-efficiently. Objects larger thanmaximum_size may be allocated, but the pool is not guaranteed to manage them space-efficiently.Furthermore, partial freeing is not supported for objects larger than maximum size; doing so willresult in the storage of the object never being reused. Mean_size need not be an accurate mean,although the pool will manage mean_size objects more efficiently.

    + +

    Reserve Depth

    + +

    reserve_depth is the expected hysteresis of the object population. When pool objects arefreed, the pool will retain sufficient storage to allocate reserve_depth objects of mean_size fornear term allocations (rather than immediately making that storage available to other pools).

    + +

    If a pool has a stable object population, one which only grows over the lifetime of thepool, or one which grows steadily and then shrinks steadily, use a reserve_depth of 0.

    + +

    It is always safe to use a reserve depth of 0, but if the object population typicallyfluctuates in a range (e.g., the client program may repeatedly create and destroy a subset ofobjects in a loop), it is more efficient for the pool to retain enough storage to satisfy thatfluctuation. For example, if a pool has an object population that typically fluctuates between 8,000and 10,000, use a reserve_depth of 2,000.

    + +

    The reserve will not normally be available to other pools for allocation, even when it isnot used by the pool. If this is undesirable, a reserve depth of 0 may be used for a pool whoseobject population does vary, at a slight cost in efficiency. The reserve does not guarantee anyparticular amount of allocation.

    + +

    Fragmentation Limit

    + +

    fragmentation_limit is a percentage in (0, 100] that can be used to set an upper limit onthe space overhead of MVT in case object deathtimes and allocations do not correlate well.

    + +

    If the free space managed by the pool as a ratio of all the space managed by the poolexceeds the specified percentage, the pool will fall back to a first fit allocation policy,exploiting space more efficiently at a cost in time efficiency.

    + +

    A fragmentation_limit of 0 would cause the pool to operate as a first-fit pool, at asignificant cost in time-efficiency, therefore is not permitted.

    + +

    A fragmentation_limit of 100 will cause the pool to use temporal fit (unless resources areexhausted). If the objects allocated in the pool have similar lifetime expectancies, this mode willhave the best time- and space-efficiency. If the objects have widely varying lifetime expectancies,this mode will be time-efficient, but may be space-inefficient. An intermediate setting can be usedto limit the space-inefficiency of temporal fit due to varying object life expectancies.

    + +

    + + Allocation + +

    + +

    The MVT pool class only supports allocation through allocation points. See mps_ap_create.

    + +

    + + Deallocation + +

    + +

    The MVT pool class supports explicit freeing. See mps_pool_free.

    -

    Syntax

    +

    Internal Notes

    -

    mps_res_t mps_finalize(mps_arena_t arena, mps_addr_t *object_ref)

    +

    Need a life-expectancy parameter! How else will different instances choose their Loci?

    + +

    Need an alignment parameter. Perhaps this is embedded in a format parameter (when all poolshave at least a null format).

    + +

    It is conceivable that a client would want to mix manual and automatic pools with the manualpool being able to be a root for the automatic. To do so, MVT would need to support formattedobjects and scanning. This may be added someday.

    + +

    Eventually the MM product will include profiling tools that will help determine objectcharacteristics that correlate with object lifetime and suggest how to configure the appropriatenumber of MVT pool instances and what characteritics to dispatch on when choosing which instance toallocate from.

    + +

    [From mail.ptw.1998-08-19.02-33(0) ]

    + +

    Remember Wilson's statement that the goal of a memory manager is to exploit the regularitiesin allocation patterns? My intent in the interface parameters is to accept measurable regularitiesin object populations, then the implementation can exploit them.

    + +

    Perhaps the pool should accept some description of the mean and +deviation of the objectsizes, object population, and object +lifetimes. Is that what you are getting at? [Reserve_depth is in some sense a deviation.]

    -

    Arguments

    +

    Type mps_class_t

    + + +

    Name

    + +

    mps_class_t

    + + +

    Summary

    + +

    mps_class_t is the type of pool classes.

    + + +

    Associated Protocols

    + +

    Pool.

    + + +

    Resources

    + +

    mps.h

    + + +

    Description

    + +

    mps_class_t is the abstract type of pool classes. It is opaque. A pool class may beobtained by calling the class function for the appropriate class, such as mps_class_amc for theAMC class. A pool class is used when creating a pool with mps_pool_create or mps_pool_create_v.

    + + +

    Example

    + + +

    See Also

    + +

    + +mps_pool_create, + +mps_pool_create_v

    + + +

    Notes

    + +

    mps_class_s is an incomplete structure type used only to define mps_class_t.

    + + +

    function mps_finalize

    + + +

    Name

    + +

    mps_finalize

    + + +

    Summary

    + +

    Registers an object for finalization.

    + + +

    Associated Protocols

    + +

    Finalization, message.

    + + +

    Syntax

    + +

    mps_res_t mps_finalize(mps_arena_t arena, mps_addr_t *object_ref)

    + + +

    Arguments

    arena @@ -4754,77 +5315,83 @@ if(mps_pool_create(&pool, arena, mps_class_epdr_debug(),

    object_ref -- a pointer to a pointer to the object to be finalized -

    +

    -

    Returned Values

    +

    Returned Values

    -

    A result code.

    +

    A result code.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This function registers the specified object for finalization. This object must be an objectallocated from a pool in the specified arena.

    +

    This function registers the specified object for finalization. This object must be an objectallocated from a pool in the specified arena.

    -

    An object becomes finalizable if it is registered for finalization, and the collectorobserves that it would otherwise be reclaimable. Note that the subsequent creation of strongreferences to the object (from, say, weak references) may cause finalization to occur when an objectis not otherwise reclaimable.

    +

    An object becomes finalizable if it is registered for finalization, and the collectorobserves that it would otherwise be reclaimable. Note that the subsequent creation of strongreferences to the object (from, say, weak references) may cause finalization to occur when an objectis not otherwise reclaimable.

    -

    When an object is finalizable, it may be finalized up to N times, where N is the number oftimes it has been registered for finalization. When an object is finalized, it is also deregisteredfor finalization (so that it cannot be finalized again from the same registration).

    +

    When an object is finalizable, it may be finalized up to N times, where N is the number oftimes it has been registered for finalization. When an object is finalized, it is also deregisteredfor finalization (so that it cannot be finalized again from the same registration).

    -

    Finalization is performed by passing a finalization message to the client, containing anexact reference to the object. See the message protocol, mps_message_type_finalization, and mps_message_finalization_ref for details.

    +

    Finalization is performed by passing a finalization message to the client, containing anexact reference to the object. See the message protocol, mps_message_type_finalization, and mps_message_finalization_ref for details.

    -

    If an object is registered for finalization multiple times, then there may be multiplefinalization messages on the queue at the same time. It may also be necessary to discard previousfinalization messages for an object before all such messages are posted on the message queue.Clients performing multiple registrations must cope with both behaviors.

    +

    If an object is registered for finalization multiple times, then there may be multiplefinalization messages on the queue at the same time. It may also be necessary to discard previousfinalization messages for an object before all such messages are posted on the message queue.Clients performing multiple registrations must cope with both behaviors.

    -

    Note that there is no guarantee that finalization will be prompt, although the collectordoes attempt to do this.

    +

    Note that there is no guarantee that finalization will be prompt, although the collectordoes attempt to do this.

    -

    Note that there will be no attempt to finalize objects in the context of mps_arena_destroy or mps_pool_destroy. mps_pool_destroyshould therefore not be invoked on pools containing objects registered for finalization.

    +

    Note that there will be no attempt to finalize objects in the context of mps_arena_destroy or mps_pool_destroy. mps_pool_destroyshould therefore not be invoked on pools containing objects registered for finalization.

    -

    Not all pools support finalization of objects in those pools. For more information, see thePool Class Catalog.

    +

    Not all pools support finalization of objects in those pools. For more information, see thePool Class Catalog.

    -

    Example

    +

    Example

    -

    [missing]

    +

    [missing]

    -

    Error Handling

    +

    Error Handling

    -

    [missing]

    +

    [missing]

    -

    See Also

    +

    See Also

    -

    mps_message_*, mps_arena_destroy, mps_pool_destroy

    +

    + +mps_message_*, + +mps_arena_destroy, + +mps_pool_destroy

    -

    Notes

    +

    Notes

    -

    This function receives a pointer to a reference. This is to avoid placing the restriction onthe client that the C call stack be a root.

    +

    This function receives a pointer to a reference. This is to avoid placing the restriction onthe client that the C call stack be a root.

    -

    type mps_fmt_A_s

    +

    type mps_fmt_A_s

    -

    Name

    +

    Name

    -

    mps_fmt_A_s

    +

    mps_fmt_A_s

    -

    Summary

    +

    Summary

    -

    mps_fmt_A_s is a structure used to create object formats of variant A.

    +

    mps_fmt_A_s is a structure used to create object formats of variant A.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    Type

    +

    Type

     typedef struct mps_fmt_A_s {
@@ -4839,7 +5406,7 @@ typedef struct mps_fmt_A_s {
    -

    Resources

    +

    Resources

    @@ -4848,20 +5415,21 @@ typedef struct mps_fmt_A_s {

    -

    Description

    +

    Description

    -

    Objects of this type are intended to be used in the creation of object formats. Objectformats describe the layout of client objects.

    +

    Objects of this type are intended to be used in the creation of object formats. Objectformats describe the layout of client objects.

    -

    mps_fmt_A_s is a structure that represents the particular collection of methodsand values that describes an object format of variant A.

    +

    mps_fmt_A_s is a structure that represents the particular collection of methodsand values that describes an object format of variant A.

    -

    Broadly speaking, the object formats of this variant are suitable for use in copying ormoving memory managers.

    +

    Broadly speaking, the object formats of this variant are suitable for use in copying ormoving memory managers.

    -

    mps_fmt_A_s has the following methods: scan, skip,copy, fwd, isfwd, pad, and the following value:align.

    +

    mps_fmt_A_s has the +following methods: scan, skip, copy, fwd, isfwd, pad, and the following value:align.

    -

    align is an integer value defines the alignment of objects allocated with thisformat. It should be large enough to satisfy the alignment requirements of any field in the objects,and it cannot be larger than the arena alignment. For details of the methods, consult the reference pages for the type of each method.

    +

    align is an integer value defines the alignment of objects allocated with thisformat. It should be large enough to satisfy the alignment requirements of any field in the objects,and it cannot be larger than the arena alignment. For details of the methods, consult the reference pages for the type of each method.

    -

    Example

    +

    Example

     mps_fmt_t create_format(mps_arena_t arena)
@@ -4879,30 +5447,48 @@ mps_fmt_t create_format(mps_arena_t arena)
    -

    See Also

    +

    See Also

    -

    mps_fmt_create_A, mps_fmt_scan_t, mps_fmt_skip_t mps_fmt_copy_t, mps_fmt_fwd_t, mps_isfwd_t,mps_pad_t, mps_align_t, mps_fmt_B_s

    +

    + +mps_fmt_create_A, + +mps_fmt_scan_t, + +mps_fmt_skip_t + +mps_fmt_copy_t, + +mps_fmt_fwd_t, + +mps_isfwd_t, + +mps_pad_t, + +mps_align_t, + +mps_fmt_B_s

    -

    type mps_fmt_A_t

    +

    type mps_fmt_A_t

    -

    Name

    +

    Name

    -

    mps_fmt_A_t

    +

    mps_fmt_A_t

    -

    Summary

    +

    Summary

    -

    mps_fmt_A_t is the type pointer to mps_fmt_A_s.

    +

    mps_fmt_A_t is the type pointer to mps_fmt_A_s.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    Type

    +

    Type

     typedef struct mps_fmt_A_s {
@@ -4919,47 +5505,53 @@ typedef struct mps_fmt_A_s *mps_fmt_A_t;
    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_fmt_A_t is the type pointer to mps_fmt_A_s. A value of this type represents a collection of methods and values that can be used to create a format object of type mps_fmt_t.This type represents a particular collection of methods and values; other collections arerepresented by other types.

    +

    mps_fmt_A_t is the type pointer to mps_fmt_A_s. A value of this type represents a collection of methods and values that can be used to create a format object of type mps_fmt_t.This type represents a particular collection of methods and values; other collections arerepresented by other types.

    -

    Objects of type mps_fmt_A_t are intended to be used in the creation of object formats.Object formats describe the layout of client objects. The function mps_fmt_create_A takes an mps_fmt_A_t as one of its arguments and creates an object of type mps_fmt_t (an object format).

    +

    Objects of type mps_fmt_A_t are intended to be used in the creation of object formats.Object formats describe the layout of client objects. The function mps_fmt_create_A takes an mps_fmt_A_t as one of its arguments and creates an object of type mps_fmt_t (an object format).

    -

    See the documentation of mps_fmt_A_s for further details.

    +

    See the documentation of mps_fmt_A_s for further details.

    -

    Example

    +

    Example

    -

    See Also

    +

    See Also

    -

    mps_fmt_A_s, mps_fmt_t, mps_fmt_create_A

    +

    + +mps_fmt_A_s, + +mps_fmt_t, + +mps_fmt_create_A

    -

    type mps_fmt_B_s

    +

    type mps_fmt_B_s

    -

    Name

    +

    Name

    -

    mps_fmt_B_s

    +

    mps_fmt_B_s

    -

    Summary

    +

    Summary

    -

    mps_fmt_B_s is a transparent structure used to create object formats of variantB.

    +

    mps_fmt_B_s is a transparent structure used to create object formats of variantB.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    Type

    +

    Type

     typedef struct mps_fmt_B_s {
@@ -4975,23 +5567,23 @@ typedef struct mps_fmt_B_s {
    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    Objects of this type are intended to be used in the creation of object formats. Objectformats describe the layout of client objects. mps_fmt_B_s is a structure thatrepresents the particular collection of methods and values that describes an object format ofvariant B.

    +

    Objects of this type are intended to be used in the creation of object formats. Objectformats describe the layout of client objects. mps_fmt_B_s is a structure thatrepresents the particular collection of methods and values that describes an object format ofvariant B.

    -

    mps_fmt_B_s is the same as mps_fmt_A_s except for the addition ofthe mps_class method. Broadly speaking, the object formats of variety B are suitable for use incopying or moving memory managers (just like variety A); the addition of the class method allowsmore information to be passed to various support tools (such as graphical browsers).

    +

    mps_fmt_B_s is the same as mps_fmt_A_s except for the addition ofthe mps_class method. Broadly speaking, the object formats of variety B are suitable for use incopying or moving memory managers (just like variety A); the addition of the class method allowsmore information to be passed to various support tools (such as graphical browsers).

    -

    mps_fmt_B_s has the following methods: scan, skip, copy, fwd, isfwd, pad, mps_class, and the following value: align.

    +

    mps_fmt_B_s has the following methods: scan, skip, copy, fwd, isfwd, pad, mps_class, and the following value: align.

    -

    align is an integer value defines the alignment of objects allocated with this format. Itshould be large enough to satisfy the alignment requirements of any field in the objects, and itcannot be larger than the arena alignment. For details of the methods, consult the reference pagesfor the type of each method.

    +

    align is an integer value defines the alignment of objects allocated with this format. Itshould be large enough to satisfy the alignment requirements of any field in the objects, and itcannot be larger than the arena alignment. For details of the methods, consult the reference pagesfor the type of each method.

    -

    Example

    +

    Example

     mps_fmt_t create_format(mps_arena_t arena)
@@ -5009,35 +5601,55 @@ mps_fmt_t create_format(mps_arena_t arena)
    -

    See Also

    +

    See Also

    -

    mps_fmt_create_B, mps_fmt_scan_t, mps_fmt_skip_t, mps_fmt_copy_t, mps_fmt_fwd_t,mps_isfwd_t, mps_pad_t, mps_align_t, mps_class_t, mps_fmt_A_s

    +

    + +mps_fmt_create_B, + +mps_fmt_scan_t, + +mps_fmt_skip_t, + +mps_fmt_copy_t, + +mps_fmt_fwd_t, + +mps_isfwd_t, + +mps_pad_t, + +mps_align_t, + +mps_class_t, + +mps_fmt_A_s

    -

    Notes

    +

    Notes

    -

    The mps_class field used to be called "class", but that was problematic forC++, so we changed it.

    +

    The mps_class field used to be called "class", but that was problematic forC++, so we changed it.

    -

    Type mps_fmt_B_t

    +

    Type mps_fmt_B_t

    -

    Name

    +

    Name

    -

    mps_fmt_B_t

    +

    mps_fmt_B_t

    -

    Summary

    +

    Summary

    -

    mps_fmt_B_t is a type passed to mps_fmt_create_B. It represents the collection of methodsand values used to create a mps_fmt_t. You are expected to declare and create structures of thistype if you require an object of type mps_fmt_B_t.

    +

    mps_fmt_B_t is a type passed to mps_fmt_create_B. It represents the collection of methodsand values used to create a mps_fmt_t. You are expected to declare and create structures of thistype if you require an object of type mps_fmt_B_t.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format

    +

    Format

    -

    Structure

    +

    Structure

     typedef struct mps_fmt_B_s {
@@ -5053,55 +5665,63 @@ typedef struct mps_fmt_B_s {
    -

    Type

    +

    Type

    -

    typedef struct mps_fmt_B_s *mps_fmt_B_t;

    +

    typedef struct mps_fmt_B_s *mps_fmt_B_t;

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_fmt_B_t is the equivalent to mps_fmt_A_t that should be passed tomps_fmt_create_B. It is suitable for format variety A collectors that need to use tools that useclass information.

    +

    mps_fmt_B_t is the equivalent to mps_fmt_A_t that should be passed tomps_fmt_create_B. It is suitable for format variety A collectors that need to use tools that useclass information.

    -

    See the documentation for the symbol mps_fmt_B_s for further details.

    +

    See the documentation for the symbol mps_fmt_B_s for further details.

    -

    Example

    +

    Example

    -

    See Also

    +

    See Also

    -

    mps_fmt_B_s, mps_fmt_t, mps_fmt_create_B, mps_fmt_A_t

    +

    + +mps_fmt_B_s, + +mps_fmt_t, + +mps_fmt_create_B, + +mps_fmt_A_t

    -

    Notes

    +

    Notes

    -

    None.

    +

    None.

    -

    type mps_fmt_auto_header_s

    +

    type mps_fmt_auto_header_s

    -

    Name

    +

    Name

    -

    mps_fmt_auto_header_s

    +

    mps_fmt_auto_header_s

    -

    Summary

    +

    Summary

    -

    mps_fmt_auto_header_s is a structure used to create objectformats of variant auto_header.

    +

    mps_fmt_auto_header_s is a structure used to create objectformats of variant auto_header.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    Type

    +

    Type

    @@ -5118,7 +5738,7 @@ typedef struct mps_fmt_auto_header_s {
    -

    Resources

    +

    Resources

    @@ -5127,13 +5747,15 @@ typedef struct mps_fmt_auto_header_s {

    -

    Description

    +

    Description

    -

    Objects of this type are intended to be used in the creation of object formats. Objectformats describe the layout of client objects. mps_fmt_auto_header_s isa structure that represents the particular collection of methods and values that describes an objectformat of variant auto_header.

    +

    Objects of this type are intended to be used in the creation of object formats. Objectformats describe the layout of client objects. mps_fmt_auto_header_s isa structure that represents the particular collection of methods and values that describes an objectformat of variant auto_header.

    -

    Broadly speaking, the object formats of this variant are suitable for use in automaticmemory management for objects with headers (hence the name). More precisely, this variant isintended for formats where the client's pointers point some distance into the memory blockcontaining the object. This typically happens when the objects have a common header used for memorymanagement or class system purposes, but this situation also arises when the low bits of a pointerare used for a tag. The MPS does not care what the reason is, only about the offset of the pointerin relation to the memory block.

    +

    Broadly speaking, the object formats of this variant are suitable +for use in automaticmemory management for objects with headers (hence +the name). More precisely, this variant is intended for formats where the client's pointers point some distance into the memory blockcontaining the object. This typically happens when the objects have a common header used for memorymanagement or class system purposes, but this situation also arises when the low bits of a pointerare used for a tag. The MPS does not care what the reason is, only about the offset of the pointerin relation to the memory block.

    -

    mps_fmt_auto_header_shas the following methods: scan, skip, fwd, isfwd, pad, and the following values: align and mps_headerSize.

    +

    mps_fmt_auto_header_shas the following methods: scan, skip, fwd, isfwd, pad, and the following values: align and mps_headerSize.

    @@ -5142,10 +5764,10 @@ typedef struct mps_fmt_auto_header_s { is an integer value defines the alignment of objectsallocated with this format. It should be large enough to satisfy the alignment requirements of anyfield in the objects, and it cannot be larger than the arena alignment.

    -

    mps_headerSize is the size of the header, i.e., the offset of aclient pointer from the base the memory block. For details of the methods, consult the referencepages for the type of each method.

    +

    mps_headerSize is the size of the header, i.e., the offset of aclient pointer from the base the memory block. For details of the methods, consult the referencepages for the type of each method.

    -

    Example

    +

    Example

     mps_fmt_t create_format(mps_arena_t arena)
@@ -5163,66 +5785,83 @@ mps_fmt_t create_format(mps_arena_t arena)
    -

    See Also

    +

    See Also

    -

    mps_fmt_create_auto_header, mps_fmt_scan_t, mps_fmt_skip_t, mps_fmt_fwd_t, mps_isfwd_t,mps_pad_t, mps_align_t, mps_fmt_A_s

    +

    + +mps_fmt_create_auto_header, + +mps_fmt_scan_t, + +mps_fmt_skip_t, + +mps_fmt_fwd_t, + +mps_isfwd_t, + +mps_pad_t, + +mps_align_t, + +mps_fmt_A_s

    -

    Notes

    +

    Notes

    -

    For technical reasons, client objects must be longer than the header, i.e., objectsconsisting of only a header are not supported. However, if the header size is larger than or equalto alignment, the pad method must still be able to create padding objects down to alignment size.

    +

    For technical reasons, client objects must be longer than the header, i.e., objectsconsisting of only a header are not supported. However, if the header size is larger than or equalto alignment, the pad method must still be able to create padding objects down to alignment size.

    -

    At the moment, this format only works with pool classes AMC and AMCZ.

    +

    At the moment, this format only works with pool classes AMC and AMCZ.

    -

    type mps_fmt_class_t

    +

    type mps_fmt_class_t

    -

    Name

    +

    Name

    -

    mps_fmt_class_t

    +

    mps_fmt_class_t

    -

    Summary

    +

    Summary

    -

    mps_fmt_class_t is a function pointer type for the class method of a format.

    +

    mps_fmt_class_t is a function pointer type for the class method of a format.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format. Telemetry.

    +

    Format. Telemetry.

    -

    Type

    +

    Type

    -

    typedef mps_addr_t (*mps_fmt_class_t)(mps_addr_t addr);

    +

    typedef mps_addr_t (*mps_fmt_class_t)(mps_addr_t addr);

    -

    Arguments

    +

    Arguments

    -

    addr the address of the object whose class is of interest

    +

    addr the address of the object whose class is of interest

    -

    Returned Values

    +

    Returned Values

    -

    Returns an address that the client associates with the class or type of the object.

    +

    Returns an address that the client associates with the class or type of the object.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_fmt_class_t is t he type of a format's class method. A class methodreturns an address that is related to the class of the object, for passing on to various supporttools (such as graphical browsers).

    +

    mps_fmt_class_t is t he type of a format's class method. A class methodreturns an address that is related to the class of the object, for passing on to various supporttools (such as graphical browsers).

    -

    A class method is provided by the client as part of a format (see Format Protocol).

    +

    A class method is provided by the client as part of a format (see Format Protocol).

    -

    The exact meaning of the return value is up to the client, but it would typically bear somerelation to class or type in the client program. The client may have objects that represent classesor types. These may be associated with strings via mps_telemetry_intern and mps_telemetry_label.

    +

    The exact meaning of the return value is up to the client, but it would typically bear somerelation to class or type in the client program. The client may have objects that represent classesor types. These may be associated with strings via mps_telemetry_intern and mps_telemetry_label.

    -

    Example

    +

    Example

     mps_addr_t my_class_method(mps_addr_t object) {
@@ -5232,64 +5871,68 @@ mps_addr_t my_class_method(mps_addr_t object) {
    -

    Error Handling

    +

    Error Handling

    -

    A class method is not allowed to fail, but may return NULL.

    +

    A class method is not allowed to fail, but may return NULL.

    -

    See Also

    +

    See Also

    -

    mps_fmt_t, mps_fmt_create_B

    +

    + +mps_fmt_t, + +mps_fmt_create_B

    -

    Notes

    +

    Notes

    -

    It is recommended that NULL be returned for padding objects and forwarded objects.

    +

    It is recommended that NULL be returned for padding objects and forwarded objects.

    -

    type mps_fmt_copy_t

    +

    type mps_fmt_copy_t

    -

    Name

    +

    Name

    -

    mps_fmt_copy_t

    +

    mps_fmt_copy_t

    -

    Summary

    +

    Summary

    -

    mps_fmt_copy_t is a function pointer type for the copy method of a format.

    +

    mps_fmt_copy_t is a function pointer type for the copy method of a format.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    Type

    +

    Type

    -

    typedef void (*mps_fmt_copy_t)(mps_addr_t old, mps_addr_t new);

    +

    typedef void (*mps_fmt_copy_t)(mps_addr_t old, mps_addr_t new);

    -

    Arguments

    +

    Arguments

    -

    old -- the address of the object

    +

    old -- the address of the object

    -

    new -- the address to which the object should be copied

    +

    new -- the address to which the object should be copied

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_fmt_copy_t is a function pointer type for the copy method of a format. A copy methodcopies an object to a new location. It may be called by the MPS as part of copying garbagecollection, for example.

    +

    mps_fmt_copy_t is a function pointer type for the copy method of a format. A copy methodcopies an object to a new location. It may be called by the MPS as part of copying garbagecollection, for example.

    -

    A copy method is required in some formats (in particular formats A and B (see mps_fmt_A_t and mps_fmt_B_t)). A copy method takes the address of an object and another address, and copiesthe object to the new address. The new and the old locations are guaranteed not to overlap.

    +

    A copy method is required in some formats (in particular formats A and B (see mps_fmt_A_t and mps_fmt_B_t)). A copy method takes the address of an object and another address, and copiesthe object to the new address. The new and the old locations are guaranteed not to overlap.

    -

    Example

    +

    Example

     void my_copy_method(mps_addr_t old, mps_addr_t new)
@@ -5300,47 +5943,57 @@ void my_copy_method(mps_addr_t old, mps_addr_t new)
    -

    Error Handling

    +

    Error Handling

    -

    A copy method is not allowed to fail.

    +

    A copy method is not allowed to fail.

    -

    See Also

    +

    See Also

    -

    mps_fmt_t, mps_fmt_create_A, mps_fmt_A_t, mps_fmt_B_t, mps_fmt_create_B

    +

    + +mps_fmt_t, + +mps_fmt_create_A, + +mps_fmt_A_t, + +mps_fmt_B_t, + +mps_fmt_create_B

    -

    Notes

    +

    Notes

    -

    Most pools will just ignore Copy methods, and do the copy themselves.

    +

    Most pools will just ignore Copy methods, and do the copy themselves.

    -

    function mps_fmt_create_A

    +

    function mps_fmt_create_A

    -

    Name

    +

    Name

    -

    mps_fmt_create_A

    +

    mps_fmt_create_A

    -

    Summary

    +

    Summary

    -

    Function for create a format of variety A.

    +

    Function for create a format of variety A.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    +

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_fmt_create_A(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_A_s *fmt_A);

    +

    mps_res_t mps_fmt_create_A(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_A_s *fmt_A);

    -

    Arguments

    +

    Arguments

    fmt_o @@ -5355,25 +6008,25 @@ void my_copy_method(mps_addr_t old, mps_addr_t new)

    fmt_A - format description of variety A -

    +

    -

    Returned Values

    +

    Returned Values

    -

    Result status. If the return value is MPS_RES_OK, the new format is in *fmt_o .

    +

    Result status. If the return value is MPS_RES_OK, the new format is in *fmt_o .

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This function creates a format from a user format specification of variety A.

    +

    This function creates a format from a user format specification of variety A.

    -

    Example

    +

    Example

     mps_fmt_t create_format(mps_arena_t arena)
@@ -5394,66 +6047,72 @@ mps_fmt_t create_format(mps_arena_t arena)
    -

    Error Handling

    +

    Error Handling

    -

    The MPS may exhaust some resource in the course of mps_fmt_create_A and willreturn an appropriate error code in such circumstances.

    +

    The MPS may exhaust some resource in the course of mps_fmt_create_A and willreturn an appropriate error code in such circumstances.

    -

    See Also

    +

    See Also

    -

    mps_fmt_A_s, mps_fmt_t, mps_fmt_create_B

    +

    + +mps_fmt_A_s, + +mps_fmt_t, + +mps_fmt_create_B

    -

    function mps_fmt_create_B

    +

    function mps_fmt_create_B

    -

    Name

    +

    Name

    -

    mps_fmt_create_B

    +

    mps_fmt_create_B

    -

    Summary

    +

    Summary

    -

    Function for create a format of variety B.

    +

    Function for create a format of variety B.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    +

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_fmt_create_B(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_B_s *fmt_B);

    +

    mps_res_t mps_fmt_create_B(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_B_s *fmt_B);

    -

    Arguments

    +

    Arguments

    -

    arena - the arena in which to create the format

    +

    arena - the arena in which to create the format

    -

    fmt_B - format description of variety B

    +

    fmt_B - format description of variety B

    -

    Returned Values

    +

    Returned Values

    -

    Result status. If the return value is MPS_RES_OK, the new format is in*fmt_o .

    +

    Result status. If the return value is MPS_RES_OK, the new format is in*fmt_o .

    -

    +

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This function creates a format from a user format specification of variety B. It is verysimilar to mps_fmt_create_A.

    +

    This function creates a format from a user format specification of variety B. It is verysimilar to mps_fmt_create_A.

    -

    Example

    +

    Example

     mps_fmt_t create_format(mps_arena_t arena)
@@ -5471,40 +6130,46 @@ mps_fmt_t create_format(mps_arena_t arena)
    -

    Error Handling

    +

    Error Handling

    -

    The MPS may exhaust some resource in the course of mps_fmt_create_B and willreturn an appropriate error code in such circumstances.

    +

    The MPS may exhaust some resource in the course of mps_fmt_create_B and willreturn an appropriate error code in such circumstances.

    -

    See Also

    +

    See Also

    -

    mps_fmt_B_s, mps_fmt_t, mps_fmt_create_A

    +

    + +mps_fmt_B_s, + +mps_fmt_t, + +mps_fmt_create_A

    -

    function mps_fmt_create_auto_header

    +

    function mps_fmt_create_auto_header

    -

    Name

    +

    Name

    -

    mps_fmt_create_auto_header

    +

    mps_fmt_create_auto_header

    -

    Summary

    +

    Summary

    -

    Function for create a format of variety auto_header.

    +

    Function for create a format of variety auto_header.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    Syntax

    +

    Syntax

    mps_res_t mps_fmt_create_auto_header(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_auto_header_s *fmt_st);

    -

    Arguments

    +

    Arguments

    fmt_o @@ -5519,25 +6184,25 @@ mps_fmt_t create_format(mps_arena_t arena)

    fmt_st - format description of variety auto_header -

    +

    -

    Returned Values

    +

    Returned Values

    -

    Result status. If the return value is MPS_RES_OK, the new format is in *fmt_o .

    +

    Result status. If the return value is MPS_RES_OK, the new format is in *fmt_o .

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This function creates a format from a user format specification of variety auto_header.

    +

    This function creates a format from a user format specification of variety auto_header.

    -

    Example

    +

    Example

     mps_fmt_t create_format(mps_arena_t arena)
@@ -5555,73 +6220,80 @@ mps_fmt_t create_format(mps_arena_t arena)
    -

    Error Handling

    +

    Error Handling

    -

    The MPS may exhaust some resource in the course of mps_fmt_create_auto_headerand will return an appropriate error code in such circumstances.

    +

    The MPS may exhaust some resource in the course of mps_fmt_create_auto_headerand will return an appropriate error code in such circumstances.

    -

    See Also

    +

    See Also

    -

    mps_fmt_auto_header_s, mps_fmt_t, mps_fmt_create_A

    +

    + +mps_fmt_auto_header_s, + +mps_fmt_t, + +mps_fmt_create_A

    -

    type mps_fmt_fwd_t

    +

    type mps_fmt_fwd_t

    -

    Name

    +

    Name

    -

    mps_fmt_fwd_t

    +

    mps_fmt_fwd_t

    -

    Summary

    +

    Summary

    -

    The type of a format's forward method.

    +

    The type of a format's forward method.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    Type

    +

    Type

    -

    typedef void (*mps_fmt_fwd_t)(mps_addr_t old, mps_addr_t new);

    +

    typedef void (*mps_fmt_fwd_t)(mps_addr_t old, mps_addr_t new);

    -

    Arguments

    +

    Arguments

    -

    old

    +

    old

    -

    the address of an object

    +

    the address of an object

    -

    new

    +

    new

    -

    the address where the object has been moved

    +

    the address where the object has been moved

    -

    Returned Values

    +

    Returned Values

    -

    None.

    +

    None.

    -

    Description

    +

    Description

    -

    mps_fmt_fwd_t is the type of a format's forward method. A forward method isused to store relocation information in a heap. It may be called by the MPS as part of copyinggarbage collection.

    +

    mps_fmt_fwd_t is the type of a format's forward method. A forward method isused to store relocation information in a heap. It may be called by the MPS as part of copyinggarbage collection.

    -

    A forward method is provided by the client as part of a format (see Format Protocol ). TheMPS calls a forward method when it has relocated an object. The forward method when called mustreplace the object at 'old' with a forwarding marker that points to the address 'new'. Theforwarding marker must meet the following requirements:

    +

    A forward method is provided by the client as part of a format (see Format Protocol ). TheMPS calls a forward method when it has relocated an object. The forward method when called mustreplace the object at 'old' with a forwarding marker that points to the address 'new'. Theforwarding marker must meet the following requirements:

      -

    • it must be possible for the MPS to call other format methods with the address of aforwarding marker as the argument.

      • +

    • it must be possible for the MPS to call other format methods with the address of aforwarding marker as the argument.

      • -

    • he forwarding marker must not be bigger than the original object.

      • +

    • he forwarding marker must not be bigger than the original object.

      • -

    • t must be possible to distinguish the forwarding marker from ordinary objects using theisfwd method (see mps_fmt_isfwd_t ), and the isfwd method must return the address'new'.

      • +

    • t must be possible to distinguish the forwarding marker from ordinary objects using theisfwd method (see mps_fmt_isfwd_t ), and the isfwd method must return the address'new'.

    -

    Example

    +

    Example

     /* define the function */
@@ -5649,47 +6321,56 @@ struct mps_fmt_B_s example_fmt_B = {
    -

    See Also

    +

    See Also

    -

    mps_fmt_A_s, mps_fmt_B_s, mps_fmt_auto_header_s, mps_fmt_isfwd_t

    +

    + +mps_fmt_A_s, + +mps_fmt_B_s, + +mps_fmt_auto_header_s, + +mps_fmt_isfwd_t

    -

    Notes

    +

    Notes

    -

    This method is never invoked by the GC on an object in a non-moving pool.

    +

    This method is never invoked by the GC on an object in a non-moving pool.

    -

    type mps_fmt_isfwd_t

    +

    type mps_fmt_isfwd_t

    -

    Name

    +

    Name

    -

    mps_fmt_isfwd_t

    +

    mps_fmt_isfwd_t

    -

    Summary

    +

    Summary

    -

    The type of a format's isfwd ("is forwarded") method.

    +

    The type of a format's isfwd ("is forwarded") method.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    Type

    +

    Type

    -

    typedef mps_addr_t (*mps_fmt_isfwd_t)(mps_addr_t addr);

    +

    typedef mps_addr_t (*mps_fmt_isfwd_t)(mps_addr_t addr);

    -

    Arguments

    +

    Arguments

    -

    addr

    +

    addr

    -

    the address of a candidate object

    +

    the address of a candidate object

    -

    Returned Values

    +

    Returned Values

    Either a null pointer to indicate the object at @@ -5700,108 +6381,121 @@ struct mps_fmt_B_s example_fmt_B = {

    -

    Description

    +

    Description

    -

    The type of a format's isfwd ("is forwarded") method. An isfwd method is used to testwhether an object has been relocated using the format's forward method.

    +

    The type of a format's isfwd ("is forwarded") method. An isfwd method is used to testwhether an object has been relocated using the format's forward method.

    -

    An isfwd method is provided by the client as part of a format (see protocol.mps.format(0) ).The MPS calls the isfwd method to determine whether an object in the heap has been relocated or not.Objects in the heap are relocated using the format's forward method (see mps_fmt_fwd_t). When the isfwd method is called the parameter addr will be the address of either an object or aforwarding marker created with the forward method. If it is an object (so it has not been relocated)the method should return a null pointer; otherwise it is a forward marker indicating the address ofthe relocated object, the address of the relocated object should be returned (this should be thesame as the 'new' parameter that was passed to the forward method that created the forwardingmarker).

    +

    An isfwd method is provided by the client as part of a format (see protocol.mps.format(0) ).The MPS calls the isfwd method to determine whether an object in the heap has been relocated or not.Objects in the heap are relocated using the format's forward method (see mps_fmt_fwd_t). When the isfwd method is called the parameter addr will be the address of either an object or aforwarding marker created with the forward method. If it is an object (so it has not been relocated)the method should return a null pointer; otherwise it is a forward marker indicating the address ofthe relocated object, the address of the relocated object should be returned (this should be thesame as the 'new' parameter that was passed to the forward method that created the forwardingmarker).

    -

    Example

    +

    Example

    -

    <example of how to use the symbol>

    +

    <example of how to use the symbol>

    -

    See Also

    +

    See Also

    -

    mps_fmt_A_s, mps_fmt_B_s, mps_fmt_auto_header_s, mps_fmt_fwd_t

    +

    + +mps_fmt_A_s, + +mps_fmt_B_s, + +mps_fmt_auto_header_s, + +mps_fmt_fwd_t

    -

    Notes

    +

    Notes

    -

    This method is never invoked by the GC on an object in a non-moving pool.

    +

    This method is never invoked by the GC on an object in a non-moving pool.

    -

    type mps_fmt_pad_t

    +

    type mps_fmt_pad_t

    -

    Name

    +

    Name

    -

    mps_fmt_pad_t

    +

    mps_fmt_pad_t

    -

    Summary

    +

    Summary

    -

    The type of a format's pad method.

    +

    The type of a format's pad method.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    Type

    +

    Type

    -

    typedef void (*mps_fmt_pad_t)(mps_addr_t addr, size_t size);

    +

    typedef void (*mps_fmt_pad_t)(mps_addr_t addr, size_t size);

    -

    Arguments

    +

    Arguments

    -

    addr

    +

    addr

    -

    The address at which to create a padding object.

    +

    The address at which to create a padding object.

    -

    size

    +

    size

    -

    The size (in bytes) of the padding object to be created.

    +

    The size (in bytes) of the padding object to be created.

    -

    Returned Values

    +

    Returned Values

    -

    None.

    +

    None.

    -

    Description

    +

    Description

    -

    The type of a format's pad method. A pad method is used to create padding objects.

    +

    The type of a format's pad method. A pad method is used to create padding objects.

    -

    A pad method is provided by the client as part of a format (see Format Protocol ). The MPScalls a pad method when it wants to create a padding object. Typically the MPS creates paddingobjects to fill in otherwise unused gaps in memory; they allow the MPS to pack objects in fixed-sizeunits (such as OS pages). The pad method should create a padding object of the specified size at thespecified address. The size can be any aligned (to the format alignment) size. A padding objectshould be acceptable to other methods in the format (scan, skip, isfwd, etc.).

    +

    A pad method is provided by the client as part of a format (see Format Protocol ). The MPScalls a pad method when it wants to create a padding object. Typically the MPS creates paddingobjects to fill in otherwise unused gaps in memory; they allow the MPS to pack objects in fixed-sizeunits (such as OS pages). The pad method should create a padding object of the specified size at thespecified address. The size can be any aligned (to the format alignment) size. A padding objectshould be acceptable to other methods in the format (scan, skip, isfwd, etc.).

    -

    Example

    +

    Example

    -

    <example of how to use the symbol>

    +

    <example of how to use the symbol>

    -

    See Also

    +

    See Also

    -

    mps_fmt_A_s, mps_fmt_B_s

    +

    + +mps_fmt_A_s, + +mps_fmt_B_s

    -

    type mps_fmt_scan_t

    +

    type mps_fmt_scan_t

    -

    Name

    +

    Name

    -

    mps_fmt_scan_t

    +

    mps_fmt_scan_t

    -

    Summary

    +

    Summary

    -

    Type of the scan method of a format.

    +

    Type of the scan method of a format.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format, Scanning.

    +

    Format, Scanning.

    -

    Syntax

    +

    Syntax

    typedef mps_res_t (*mps_fmt_scan_t)(mps_ss_t scan_state, mps_addr_t base, mps_addr_t limit)

    -

    Arguments

    +

    Arguments

    scan_state @@ -5819,24 +6513,24 @@ struct mps_fmt_B_s example_fmt_B = {

    -

    Returned Values

    +

    Returned Values

    -

    A result code.

    +

    A result code.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This is the type of scanning functions provided by the client in some format variants and mps_root_create_fmt. When the MPS needs to scan objects in an area of memory that thisscanning function has been registered for, it will be called with a scan state and the limits of theblock of objects to scan. It must then indicate references within the objects by usingmps_fix or one of the alternatives.

    +

    This is the type of scanning functions provided by the client in some format variants and mps_root_create_fmt. When the MPS needs to scan objects in an area of memory that thisscanning function has been registered for, it will be called with a scan state and the limits of theblock of objects to scan. It must then indicate references within the objects by usingmps_fix or one of the alternatives.

    -

    The base and limit arguments are client pointers, as usual. Notethat there might not be any object at the location indicated by limit.

    +

    The base and limit arguments are client pointers, as usual. Notethat there might not be any object at the location indicated by limit.

    -

    Example

    +

    Example

     /* Scanner for a simple Scheme-like language with just two interesting types */
@@ -5890,40 +6584,69 @@ mps_res_t scan_objs(mps_ss_t ss, mps_addr_t base, mps_addr_t limit)
    -

    Error Handling

    +

    Error Handling

    -

    If a fixing operation returns a value other than MPS_RES_OK, the scanningfunction must return that value, and may return without scanning further references. Generally, itis better if it returns as soon as possible. If the scanning is completed successfully, the functionshould return MPS_RES_OK.

    +

    If a fixing operation returns a value other than MPS_RES_OK, the scanning function must +return that value, and may return without scanning further +references. Generally, itis better if it returns as soon as +possible. If the scanning is completed successfully, the +function should return MPS_RES_OK.

    -

    See Also

    +

    See Also

    -

    mps_fmt_A_s, mps_fmt_B_s, mps_fmt_auto_header_s, mps_root_create_fmt, mps_fix, MPS_FIX12,MPS_FIX1, MPS_FIX2, MPS_FIX_CALL, MPS_SCAN_BEGIN, MPS_SCAN_END

    +

    + +mps_fmt_A_s, + +mps_fmt_B_s, + +mps_fmt_auto_header_s, + +mps_root_create_fmt, + +mps_fix, + +MPS_FIX12, + +MPS_FIX1, + +MPS_FIX2, + +MPS_FIX_CALL, + +MPS_SCAN_BEGIN, + +MPS_SCAN_END

    -

    type mps_fmt_skip_t

    +

    type mps_fmt_skip_t

    -

    Name

    +

    Name

    -

    mps_fmt_skip_t

    +

    mps_fmt_skip_t

    -

    Summary

    +

    Summary

    -

    mps_fmt_skip_t is a function pointer type for the skip method of a format.

    +

    mps_fmt_skip_t is a function pointer type for the skip method of a format.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    Type

    +

    Type

    -

    typedef mps_addr_t (*mps_fmt_skip_t)(mps_addr_t obj);

    +

    typedef mps_addr_t (*mps_fmt_skip_t)(mps_addr_t obj);

    -

    Arguments

    +

    Arguments

    obj @@ -5931,24 +6654,24 @@ mps_res_t scan_objs(mps_ss_t ss, mps_addr_t base, mps_addr_t limit)

    -

    Returned Values

    +

    Returned Values

    -

    The skip method should return the address of the next object.

    +

    The skip method should return the address of the next object.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_fmt_skip_t is a function pointer type for the skip method of a format.

    +

    mps_fmt_skip_t is a function pointer type for the skip method of a format.

    -

    These methods are provided by the client as part of a format and invoked by the MPS (seeFormat Protocol). The skip method takes the client pointer to the object. The method should returnthe client pointer to the next object, whether there is one or not. With no headers, this is theaddress just past the end of this object; with headers, it's the address just past where the headerof next object would be. It is always the case that the difference between the argument and thereturn value is the size of the block containing the object.

    +

    These methods are provided by the client as part of a format and invoked by the MPS (seeFormat Protocol). The skip method takes the client pointer to the object. The method should returnthe client pointer to the next object, whether there is one or not. With no headers, this is theaddress just past the end of this object; with headers, it's the address just past where the headerof next object would be. It is always the case that the difference between the argument and thereturn value is the size of the block containing the object.

    -

    Example

    +

    Example

     mps_addr_t my_skip_method(mps_addr_t object)
@@ -5960,52 +6683,59 @@ mps_addr_t my_skip_method(mps_addr_t object)
    -

    Error Handling

    +

    Error Handling

    -

    A skip method is not allowed to fail.

    +

    A skip method is not allowed to fail.

    -

    See Also

    +

    See Also

    -

    mps_fmt_A_s, mps_fmt_B_s, mps_fmt_auto_header_s

    +

    + +mps_fmt_A_s, + +mps_fmt_B_s, + +mps_fmt_auto_header_s

    -

    type mps_fmt_t

    +

    type mps_fmt_t

    -

    Name

    +

    Name

    -

    mps_fmt_t

    +

    mps_fmt_t

    -

    Summary

    +

    Summary

    -

    mps_fmt_t is the type of object formats.

    +

    mps_fmt_t is the type of object formats.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Format.

    +

    Format.

    -

    Type

    +

    Type

    -

    typedef struct mps_fmt_s *mps_fmt_t;

    +

    typedef struct mps_fmt_s *mps_fmt_t;

    -

    mps_fmt_s is an incomplete structure type used only to declare the opaque type mps_fmt_t.

    +

    mps_fmt_s is an incomplete structure type used only to declare the opaque type mps_fmt_t.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_fmt_t is the opaque type of object formats. An object format is a way for the MPS andclient programs to communicate regarding the layout of client objects. For more information, seeFormat Protocol.

    +

    mps_fmt_t is the opaque type of object formats. An object format is a way for the MPS andclient programs to communicate regarding the layout of client objects. For more information, seeFormat Protocol.

    -

    Example

    +

    Example

     #include "mps.h"
@@ -6039,619 +6769,656 @@ void go(mps_space_t space)
    -

    See Also

    +

    See Also

    -

    mps_fmt_create_A, mps_fmt_create_B, mps_fmt_destroy, mps_fmt_A_t

    +

    + +mps_fmt_create_A, + +mps_fmt_create_B, + +mps_fmt_destroy, + +mps_fmt_A_t

    -

    type mps_formatted_objects_stepper_t

    +

    type mps_formatted_objects_stepper_t

    -

    Name

    +

    Name

    -

    mps_formatted_objects_stepper_t

    +

    mps_formatted_objects_stepper_t

    -

    Summary

    +

    Summary

    -

    Type of the client supplied heap walker component.

    +

    Type of the client supplied heap walker component.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    None.

    +

    None.

    -

    Type

    +

    Type

    typedef void (*mps_formatted_objects_stepper_t)(mps_addr_t, mps_fmt_t, mps_pool_t, void *,size_t )

    -

    Arguments

    +

    Arguments

    -

    The function pointed to by an object of type mps_formatted_objects_stepper_t takes thefollowing argument list:

    +

    The function pointed to by an object of type mps_formatted_objects_stepper_t takes thefollowing argument list:

    -

    (mps_addr_t object, mps_fmt_t format, mps_pool_t pool, void *p, size_t s)

    +

    (mps_addr_t object, mps_fmt_t format, mps_pool_t pool, void *p, size_t s)

    -

    object is a pointer to the (client) object.

    +

    object is a pointer to the (client) object.

    -

    format is the MPS format of the client object.

    +

    format is the MPS format of the client object.

    -

    pool in the MPS pool in which the client object resides.

    +

    pool in the MPS pool in which the client object resides.

    -

    p and s are two closure values which are copies of the corresponding values which the clientpassed into mps_arena_formatted_objects_walk.

    +

    p and s are two closure values which are copies of the corresponding values which the clientpassed into mps_arena_formatted_objects_walk.

    -

    Returned Values

    +

    Returned Values

    -

    The function pointed to by an object of type mps_formatted_objects_stepper_t returns noarguments.

    +

    The function pointed to by an object of type mps_formatted_objects_stepper_t returns noarguments.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    A pointer to a function is passed into the function mps_arena_formatted_objects_walk; the pointer has this type. The heap walker arranges to apply this function to all objects on the heap.

    +

    A pointer to a function is passed into the function mps_arena_formatted_objects_walk; the pointer has this type. The heap walker arranges to apply this function to all objects on the heap.

    -

    Example

    +

    Example

    -

    <example of how to use the symbol>

    +

    <example of how to use the symbol>

    -

    Error Handling

    +

    Error Handling

    -

    The function pointed to by an object of type mps_formatted_objects_stepper_t have no way toreturn an error code to the caller.

    +

    The function pointed to by an object of type mps_formatted_objects_stepper_t have no way toreturn an error code to the caller.

    -

    See Also

    +

    See Also

    -

    mps_arena_formatted_objects_arena_walk

    +

    +mps_arena_formatted_objects_arena_walk

    -

    Notes

    +

    Notes

    -

    function mps_free

    +

    function mps_free

    -

    Name

    -

    mps_free

    +

    Name

    +

    mps_free

    -

    Summary

    -

    Frees a block of memory to a pool.

    +

    Summary

    +

    Frees a block of memory to a pool.

    -

    Associated Protocols

    -

    Allocation

    +

    Associated Protocols

    +

    Allocation

    -

    Syntax

    -

    void mps_free(mps_pool_t pool, mps_addr_t p, size_t size);

    +

    Syntax

    +

    void mps_free(mps_pool_t pool, mps_addr_t p, size_t size);

    -

    Arguments

    -

    pool the pool of the object to be freed

    +

    Arguments

    -

    p a pointer to the object to the freed

    +

    pool the pool of the object to be freed

    -

    size the size of the object to the freed in bytes

    +

    p a pointer to the object to the freed

    +

    size the size of the object to the freed in bytes

    -

    Returned Values

    -

    None.

    +

    Returned Values

    +

    None.

    -

    Resources

    -

    mps.h

    +

    Resources

    +

    mps.h

    -

    Description

    -

    Frees an object of memory, returning the memory block to the pool it was allocated from.The pool might then decide to make it available to other pools, but the way this happens depends onthe pool class and the current situation.

    +

    Description

    +

    Frees an object of memory, returning the memory block to the pool it was allocated from.The pool might then decide to make it available to other pools, but the way this happens depends onthe pool class and the current situation.

    -

    Example

    +

    Example

    -

    See Also

    -

    mps_alloc

    +

    See Also

    +

    -

    Notes

    +mps_alloc

    -

    mps_free takes a size argument, because it is most efficient to do so. In practicalprograms, the type of an object is usually known at the point in the code that calls thedeallocation function, and hence the size is trivially available. In such cases. storing the size onthe MPS side would cost time and memory, and make it hard to get good virtual memory behaviour (asit is, the deallocation code doesn't have to touch the dead object at all).

    -

    Undoubtedly, one day, we'll get around to writing a pool that stores the size of eachobject.

    +

    Notes

    +

    mps_free takes a size argument, because it is most efficient to do so. In practicalprograms, the type of an object is usually known at the point in the code that calls thedeallocation function, and hence the size is trivially available. In such cases. storing the size onthe MPS side would cost time and memory, and make it hard to get good virtual memory behaviour (asit is, the deallocation code doesn't have to touch the dead object at all).

    -

    function mps_lib_memcmp

    +

    Undoubtedly, one day, we'll get around to writing a pool that stores the size of eachobject.

    -

    Name

    +

    function mps_lib_memcmp

    -

    mps_lib_memcmp

    +

    Name

    -

    Summary

    +

    mps_lib_memcmp

    -

    A plinth function similar to C's "memcmp".

    +

    Summary

    -

    Associated Protocols

    +

    A plinth function similar to C's "memcmp".

    -

    Plinth

    +

    Associated Protocols

    -

    Syntax

    +

    Plinth

    -

    int mps_lib_memcmp(const void *s1, const void *s2, size_t n);

    +

    Syntax

    -

    Arguments

    +

    int mps_lib_memcmp(const void *s1, const void *s2, size_t n);

    -

    s1, s2 pointers to memory blocks to be compared

    -

    n length of the blocks, in bytes

    +

    Arguments

    +

    s1, s2 pointers to memory blocks to be compared

    -

    Returned Values

    +

    n length of the blocks, in bytes

    -

    An integer that is greater than, equal to, or less than zero, accordingly as the blockpointed to by "s1" is greater than, equal to, or less than the block pointer to by "s2".

    +

    Returned Values

    -

    Resources

    +

    An integer that is greater than, equal to, or less than zero, accordingly as the blockpointed to by "s1" is greater than, equal to, or less than the block pointer to by "s2".

    -

    mpslib.h

    +

    Resources

    -

    Description

    +

    mpslib.h

    -

    This function is intended to have the same semantics as the "memcmp" function of the ANSI Cstandard (section 7.11.4.1).

    -

    Like other plinth features, it is used by the MPS and provided by the client (possibly usingthe ANSI plinth, mpsliban.c).

    +

    Description

    +

    This function is intended to have the same semantics as the "memcmp" function of the ANSI Cstandard (section 7.11.4.1).

    -

    Example

    +

    Like other plinth features, it is used by the MPS and provided by the client (possibly usingthe ANSI plinth, mpsliban.c).

    -

    None, clients don't use it.

    +

    Example

    -

    Error Handling

    +

    None, clients don't use it.

    -

    None.

    +

    Error Handling

    -

    See Also

    +

    None.

    -

    mps_lib_memset, mps_lib_memcpy, mpsliban.c

    +

    See Also

    -

    Notes

    +

    -

    None.

    +mps_lib_memset, +mps_lib_memcpy, +mpsliban.c

    -

    function mps_lib_memcpy

    +

    Notes

    -

    Name

    +

    None.

    -

    mps_lib_memcpy

    +

    function mps_lib_memcpy

    -

    Summary

    -

    A plinth function similar to C's "memcpy".

    +

    Name

    +

    mps_lib_memcpy

    -

    Associated Protocols

    -

    Plinth

    +

    Summary

    +

    A plinth function similar to C's "memcpy".

    -

    Syntax

    -

    void *mps_lib_memcpy(void *dest, const void *source, size_t n);

    +

    Associated Protocols

    +

    Plinth

    -

    Arguments

    -

    dest destination of copy

    +

    Syntax

    -

    source source of copy

    +

    void *mps_lib_memcpy(void *dest, const void *source, size_t n);

    -

    n length of the blocks, in bytes

    +

    Arguments

    -

    Returned Values

    +

    dest destination of copy

    -

    Returns the value of the dest argument.

    +

    source source of copy

    +

    n length of the blocks, in bytes

    -

    Resources

    -

    mpslib.h

    +

    Returned Values

    +

    Returns the value of the dest argument.

    -

    Description

    -

    This function is intended to have the same semantics as the "memcpy" function of the ANSI Cstandard (section 7.11.2.1).

    +

    Resources

    -

    Like other plinth features, it is used by the MPS and provided by the client (possibly usingthe ANSI plinth, mpsliban.c).

    +

    mpslib.h

    -

    Example

    +

    Description

    -

    None, clients don't use it.

    +

    This function is intended to have the same semantics as the "memcpy" function of the ANSI Cstandard (section 7.11.2.1).

    +

    Like other plinth features, it is used by the MPS and provided by the client (possibly usingthe ANSI plinth, mpsliban.c).

    -

    Error Handling

    -

    None.

    +

    Example

    +

    None, clients don't use it.

    -

    See Also

    -

    mps_lib_memset, mps_lib_memcmp, mpsliban.c

    +

    Error Handling

    +

    None.

    -

    Notes

    -

    None.

    +

    See Also

    +

    -

    function mps_lib_memset

    +mps_lib_memset, +mps_lib_memcmp, +mpsliban.c

    -

    Name

    -

    mps_lib_memset

    +

    Notes

    +

    None.

    -

    Summary

    -

    A plinth function similar to C's "memset".

    +

    function mps_lib_memset

    -

    Associated Protocols

    +

    Name

    -

    Plinth

    +

    mps_lib_memset

    -

    Syntax

    +

    Summary

    -

    void *mps_lib_memset(void *s, int c, size_t n);

    +

    A plinth function similar to C's "memset".

    -

    Arguments

    +

    Associated Protocols

    -

    s destination of copy

    +

    Plinth

    -

    c byte (when converted to an unsigned char) to copy

    -

    n length of the block, in bytes

    +

    Syntax

    +

    void *mps_lib_memset(void *s, int c, size_t n);

    -

    Returned Values

    -

    Returns the value of s.

    +

    Arguments

    +

    s destination of copy

    -

    Resources

    +

    c byte (when converted to an unsigned char) to copy

    -

    mpslib.h

    +

    n length of the block, in bytes

    -

    Description

    +

    Returned Values

    -

    This function is intended to have the same semantics as the "memset" function of the ANSI Cstandard (section 7.11.6.1).

    +

    Returns the value of s.

    -

    Like other plinth features, it is used by the MPS and provided by the client (possibly usingthe ANSI plinth, mpsliban.c).

    +

    Resources

    -

    Example

    +

    mpslib.h

    -

    None, clients don't use it.

    +

    Description

    -

    Error Handling

    +

    This function is intended to have the same semantics as the "memset" function of the ANSI Cstandard (section 7.11.6.1).

    -

    None.

    +

    Like other plinth features, it is used by the MPS and provided by the client (possibly usingthe ANSI plinth, mpsliban.c).

    -

    See Also

    +

    Example

    -

    mps_lib_memcpy, mps_lib_memcmp, mpsliban.c

    +

    None, clients don't use it.

    -

    Notes

    +

    Error Handling

    -

    None.

    +

    None.

    -

    mps_lib_telemetry_control

    +

    See Also

    +

    -

    Name

    +mps_lib_memcpy, -

    mps_lib_telemetry_control

    +mps_lib_memcmp, +mpsliban.c

    -

    Summary

    +

    Notes

    -

    Plinth function to supply a default value for telemetry filters from environment.

    +

    None.

    -

    Associated Protocols

    +

    mps_lib_telemetry_control

    -

    Telemetry

    +

    Name

    -

    Type

    +

    mps_lib_telemetry_control

    -

    unsigned long mps_lib_telemetry_control();

    +

    Summary

    -

    Arguments

    +

    Plinth function to supply a default value for telemetry filters from environment.

    -

    None.

    +

    Associated Protocols

    -

    Initial/Default Values

    +

    Telemetry

    -

    In the absence of environmental data, a default of zero is recommended.

    +

    Type

    -

    Returned Values

    +

    unsigned long mps_lib_telemetry_control();

    -

    The default value of the telemetry filter, as derived from the environment. It isrecommended that the environment be consulted for a symbol analagous to MPS_TELEMETRY_CONTROL, subject to local restrictions.

    +

    Arguments

    -

    Resources

    +

    None.

    -

    Depends on access to the environment.

    +

    Initial/Default Values

    -

    Description

    +

    In the absence of environmental data, a default of zero is recommended.

    -

    See mps_telemetry_control for more information on the significant of the values.

    -

    +

    Returned Values

    +

    The default value of the telemetry filter, as derived from the environment. It isrecommended that the environment be consulted for a symbol analagous to MPS_TELEMETRY_CONTROL, subject to local restrictions.

    -

    Example

    -

    See the supplied ANSI plinth for an example implementation.

    +

    Resources

    +

    Depends on access to the environment.

    -

    See Also

    -

    mps_telemetry_control

    +

    Description

    +

    See mps_telemetry_control for more information on the significant of the values.

    -

    mps_message_collection_stats_condemned_size

    +

    -

    Name

    +

    Example

    -

    mps_message_collection_stats_condemned_size

    +

    See the supplied ANSI plinth for an example implementation.

    -

    Summary

    +

    See Also

    -

    mps_message_collection_stats_condemned_size returns the "condemned size" property of thespecified message in the specified arena.

    +

    +mps_telemetry_control

    -

    Associated Protocols

    -

    Message, GC.

    +

    mps_message_collection_stats_condemned_size

    -

    Syntax

    +

    Name

    -

    size_t mps_message_collection_stats_condemned_size(mps_message_t message)

    +

    mps_message_collection_stats_condemned_size

    -

    Arguments

    +

    Summary

    -

    message -- a message of a message type that supports this method

    +

    mps_message_collection_stats_condemned_size returns the "condemned size" property of thespecified message in the specified arena.

    -

    Initial/Default Values

    +

    Associated Protocols

    -

    Not applicable.

    +

    Message, GC.

    -

    Returned Values

    +

    Syntax

    -

    An approximate size for the set of objects condemned in the collection that generated themessage.

    +

    size_t mps_message_collection_stats_condemned_size(mps_message_t message)

    -

    Resources

    +

    Arguments

    -

    Not applicable.

    +

    message -- a message of a message type that supports this method

    -

    Description

    +

    Initial/Default Values

    -

    Currently, the only type of message that supports this property, is mps_message_type_collection_stats, which is generated whenever a garbage collection completes. Thismethod returns an approximation to the size of the set of objects that were condemned in thatcollection.

    +

    Not applicable.

    -

    Example

    +

    Returned Values

    +

    An approximate size for the set of objects condemned in the collection that generated themessage.

    -

    Error Handling

    +

    Resources

    -

    See Also

    +

    Not applicable.

    -

    mps_message_*

    +

    Description

    -

    Notes

    +

    Currently, the only type of message that supports this property, is mps_message_type_collection_stats, which is generated whenever a garbage collection completes. Thismethod returns an approximation to the size of the set of objects that were condemned in thatcollection.

    -

    mps_message_collection_stats_live_size

    +

    Example

    -

    Name

    +

    Error Handling

    -

    mps_message_collection_stats_live_size

    +

    See Also

    -

    Summary

    +

    -

    mps_message_collection_stats_live_size returns the "live size" property of the specifiedmessage in the specified arena.

    +mps_message_*

    -

    Associated Protocols

    +

    Notes

    -

    Message, GC.

    +

    mps_message_collection_stats_live_size

    -

    Syntax

    -

    size_t mps_message_collection_stats_live_size(mps_message_t message)

    +

    Name

    +

    mps_message_collection_stats_live_size

    -

    Arguments

    -

    message -- a message of a message type that supports this method

    +

    Summary

    +

    mps_message_collection_stats_live_size returns the "live size" property of the specifiedmessage in the specified arena.

    -

    Initial/Default Values

    -

    Not applicable.

    +

    Associated Protocols

    +

    Message, GC.

    -

    Returned Values

    -

    The total size of the condemned objects that survived the collection that generated themessage.

    +

    Syntax

    +

    size_t mps_message_collection_stats_live_size(mps_message_t message)

    -

    Resources

    -

    Not applicable.

    +

    Arguments

    +

    message -- a message of a message type that supports this method

    -

    Description

    -

    Currently, the only type of message that supports this property, is mps_message_type_collection_stats, which is generated whenever a garbage collection completes. Thismethod returns the size of the set of objects that were condemned in that collection, but survived.

    +

    Initial/Default Values

    +

    Not applicable.

    -

    Example

    +

    Returned Values

    -

    Error Handling

    +

    The total size of the condemned objects that survived the collection that generated themessage.

    -

    See Also

    +

    Resources

    -

    mps_message_*

    +

    Not applicable.

    -

    Notes

    +

    Description

    +

    Currently, the only type of message that supports this property, is mps_message_type_collection_stats, which is generated whenever a garbage collection completes. Thismethod returns the size of the set of objects that were condemned in that collection, but survived.

    -

    mps_message_sollection_stats_not_condemned_size

    +

    Example

    -

    Name

    -

    mps_message_collection_stats_not_condemned_size

    +

    Error Handling

    -

    Summary

    +

    See Also

    -

    mps_message_collection_stats_not_condemned_size returns the "not condemned size" propertyof the specified message in the specified arena.

    +

    +mps_message_*

    -

    Associated Protocols

    -

    Message, GC.

    +

    Notes

    -

    Syntax

    +

    mps_message_sollection_stats_not_condemned_size

    -

    size_t mps_message_collection_stats_not_condemned_size(mps_message_t message)

    +

    Name

    -

    Arguments

    +

    mps_message_collection_stats_not_condemned_size

    -

    message -- a message of a message type that supports this method

    +

    Summary

    -

    Initial/Default Values

    +

    mps_message_collection_stats_not_condemned_size returns the "not condemned size" propertyof the specified message in the specified arena.

    -

    Not applicable.

    +

    Associated Protocols

    -

    Returned Values

    +

    Message, GC.

    -

    An approximate size for the set of objects that were in collected pools, but were notcondemned in the collection that generated the message.

    +

    Syntax

    -

    Resources

    +

    size_t mps_message_collection_stats_not_condemned_size(mps_message_t message)

    -

    Not applicable.

    +

    Arguments

    -

    Description

    +

    message -- a message of a message type that supports this method

    -

    Currently, the only type of message that supports this property, is mps_message_type_collection_stats, which is generated whenever a garbage collection completes. Thismethod returns an approximation to the size of the set of objects that were in collected pools, butwere not condemned in that collection.

    +

    Initial/Default Values

    -

    Example

    +

    Not applicable.

    -

    Error Handling

    +

    Returned Values

    +

    An approximate size for the set of objects that were in collected pools, but were notcondemned in the collection that generated the message.

    -

    See Also

    -

    mps_message_*

    +

    Resources

    +

    Not applicable.

    -

    Notes

    +

    Description

    -

    function mps_message_discard

    +

    Currently, the only type of message that supports this property, is mps_message_type_collection_stats, which is generated whenever a garbage collection completes. Thismethod returns an approximation to the size of the set of objects that were in collected pools, butwere not condemned in that collection.

    -

    Name

    +

    Example

    -

    mps_message_discard

    +

    Error Handling

    -

    Summary

    -

    mps_message_discard is used to indicate that there is no further use for thespecified message.

    +

    See Also

    +

    -

    Associated Protocols

    +mps_message_*

    -

    Message.

    +

    Notes

    -

    Syntax

    -

    void mps_message_discard(mps_arena_t arena, mps_message_t message)

    +

    function mps_message_discard

    -

    Arguments

    +

    Name

    + +

    mps_message_discard

    + + +

    Summary

    + +

    mps_message_discard is used to indicate that there is no further use for thespecified message.

    + + +

    Associated Protocols

    + +

    Message.

    + + +

    Syntax

    + +

    void mps_message_discard(mps_arena_t arena, mps_message_t message)

    + + +

    Arguments

    arena @@ -6664,131 +7431,138 @@ void go(mps_space_t space)

    -

    Returned Values

    +

    Returned Values

    -

    None.

    +

    None.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_message_discard is used to indicate that the client has no further use forthe specified message in the specified arena. After this, the message may not be passed as argumentto any message functions.

    +

    mps_message_discard +is used to indicate that the client has no further use for the specified message in the specified arena. After this, the message may not be passed as argumentto any message functions.

    -

    This procedure is called by the client program as a courtesy, to avoid the use of unboundedresources by the message queue itself and any other MPS-managed objects referred to by the message.

    +

    This procedure is called by the client program as a courtesy, to avoid the use of unboundedresources by the message queue itself and any other MPS-managed objects referred to by the message.

    -

    Example

    +

    Example

    -

    [missing]

    +

    [missing]

    -

    Error Handling

    +

    Error Handling

    -

    Can't fail.

    +

    Can't fail.

    -

    See Also

    +

    See Also

    -

    mps_message_get

    +

    +mps_message_get

    -

    Notes

    -

    A finalized object will not be reclaimed by the collector until the finalization message hasbeen discarded, because the message contains a reference to the object.

    +

    Notes

    +

    A finalized object will not be reclaimed by the collector until the finalization message hasbeen discarded, because the message contains a reference to the object.

    -

    function mps_message_finalization_ref

    +

    function mps_message_finalization_ref

    -

    Name

    -

    mps_message_finalization_ref

    +

    Name

    +

    mps_message_finalization_ref

    -

    Summary

    -

    mps_message_finalization_ref returns the "finalization reference" property of thespecified message in the specified arena.

    +

    Summary

    +

    mps_message_finalization_ref returns the "finalization reference" property of thespecified message in the specified arena.

    -

    Associated Protocols

    -

    Message, finalization.

    +

    Associated Protocols

    +

    Message, finalization.

    -

    Syntax

    -

    void mps_message_finalization_ref(mps_addr_t *object_ref, mps_arena_t arena, mps_message_tmessage)

    +

    Syntax

    +

    void mps_message_finalization_ref(mps_addr_t *object_ref, mps_arena_t arena, mps_message_tmessage)

    -

    Arguments

    -

    object_ref -- a reference to a reference to the object to which the message belongs

    +

    Arguments

    -

    arena -- the arena that the message is in

    +

    object_ref -- a reference to a reference to the object to which the message belongs

    -

    message -- a message of a message type that supports this method

    +

    arena -- the arena that the message is in

    +

    message -- a message of a message type that supports this method

    -

    Returned Values

    -

    None.

    +

    Returned Values

    +

    None.

    -

    Resources

    -

    mps.h

    +

    Resources

    +

    mps.h

    -

    Description

    -

    This method returns the "finalization reference" property of the specified message in thespecified arena. The message must be of a message type that supports this method. Currently, theonly such type is that of finalization messages, as returned by mps_message_type_finalization.

    +

    Description

    -

    Note that the reference returned is subject to the normal constraints such as movingcollection, if appropriate. For this reason, it is returned indirectly via "object_ref" to enablethe client to place it directly into scanned memory, without imposing the restriction that the Cstack be a root.

    +

    This method returns the "finalization reference" property of the specified message in thespecified arena. The message must be of a message type that supports this method. Currently, theonly such type is that of finalization messages, as returned by mps_message_type_finalization.

    -

    Note that the invocation of this method does not affect the liveness of the specifiedmessage and hence the liveness of the object referred to by "object_ref. Use mps_message_discard to discard messages.

    +

    Note that the reference returned is subject to the normal constraints such as movingcollection, if appropriate. For this reason, it is returned indirectly via "object_ref" to enablethe client to place it directly into scanned memory, without imposing the restriction that the Cstack be a root.

    +

    Note that the invocation of this method does not affect the liveness of the specifiedmessage and hence the liveness of the object referred to by "object_ref. Use mps_message_discard to discard messages.

    -

    Example

    +

    Example

    -

    Error Handling

    +

    Error Handling

    -

    See Also

    -

    mps_message_*, mps_finalize

    +

    See Also

    +

    -

    function mps_message_gc_condemned_size

    +mps_message_*, +mps_finalize

    -

    Name

    -

    mps_message_gc_condemned_size

    +

    function mps_message_gc_condemned_size

    -

    Summary

    +

    Name

    -

    mps_message_gc_condemned_size returns the "condemned size" property of the specified message in the specified arena.

    +

    mps_message_gc_condemned_size

    -

    Associated Protocols

    +

    Summary

    -

    Message, GC.

    +

    mps_message_gc_condemned_size returns the "condemned size" property of the specified message in the specified arena.

    -

    Syntax

    +

    Associated Protocols

    -

    size_t mps_message_gc_condemned_size(mps_arena_t arena, mps_message_tmessage)

    +

    Message, GC.

    -

    Arguments

    +

    Syntax

    -

    arena-- the arena

    +

    size_t mps_message_gc_condemned_size(mps_arena_t arena, mps_message_tmessage)

    + + +

    Arguments

    + +

    arena-- the arena

    @@ -6796,12 +7570,12 @@ void go(mps_space_t space)

    -

    Returned Values

    +

    Returned Values

    -

    An approximate size for the set of objects condemned in the collection that generated themessage.

    +

    An approximate size for the set of objects condemned in the collection that generated themessage.

    -

    Resources

    +

    Resources

    @@ -6810,58 +7584,60 @@ void go(mps_space_t space)

    -

    Description

    +

    Description

    -

    Currently, the only type of message that supports this property is mps_message_type_gc, such messages are generated whenever a garbage collectioncompletes. This method returns an approximation to the size of the set of objects that werecondemned in that collection.

    +

    Currently, the only type of message that supports this property is mps_message_type_gc, such messages are generated whenever a garbage collectioncompletes. This method returns an approximation to the size of the set of objects that werecondemned in that collection.

    -

    Example

    +

    Example

    -

    Error Handling

    +

    Error Handling

    -

    See Also

    +

    See Also

    -

    mps_message_*

    +

    + +mps_message_*

    -

    function mps_message_gc_live_size

    +

    function mps_message_gc_live_size

    -

    Name

    +

    Name

    -

    mps_message_gc_live_size

    +

    mps_message_gc_live_size

    -

    Summary

    +

    Summary

    -

    mps_message_gc_live_size returns the "live size" property of thespecified message in the specified arena.

    +

    mps_message_gc_live_size returns the "live size" property of thespecified message in the specified arena.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Message, GC.

    +

    Message, GC.

    -

    Syntax

    +

    Syntax

    -

    size_t mps_message_gc_live_size(mps_arena_t arena, mps_message_t message)

    +

    size_t mps_message_gc_live_size(mps_arena_t arena, mps_message_t message)

    -

    Arguments

    +

    Arguments

    -

    arena -- the arena;

    +

    arena -- the arena;

    -

    message -- a message of a message type that supports thismethod.

    +

    message -- a message of a message type that supports thismethod.

    -

    Returned Values

    +

    Returned Values

    -

    The total size of the condemned objects that survived the collection that generated themessage.

    +

    The total size of the condemned objects that survived the collection that generated themessage.

    -

    Resources

    +

    Resources

    @@ -6870,46 +7646,48 @@ void go(mps_space_t space)

    -

    Description

    +

    Description

    -

    Currently, the only type of message that supports this property is mps_message_type_gc, such messages are generated whenever a garbage collectioncompletes. This method returns the size of the set of objects that were condemned in thatcollection, but survived.

    +

    Currently, the only type of message that supports this property is mps_message_type_gc, such messages are generated whenever a garbage collectioncompletes. This method returns the size of the set of objects that were condemned in thatcollection, but survived.

    -

    Example

    +

    Example

    -

    Error Handling

    +

    Error Handling

    -

    See Also

    +

    See Also

    -

    mps_message_*

    +

    + +mps_message_*

    -

    function mps_message_gc_not_condemned_size

    +

    function mps_message_gc_not_condemned_size

    -

    Name

    +

    Name

    -

    mps_message_gc_not_condemned_size

    +

    mps_message_gc_not_condemned_size

    -

    Summary

    +

    Summary

    -

    mps_message_gc_not_condemned_size returns the "not condemnedsize" property of the specified message in the specified arena.

    +

    mps_message_gc_not_condemned_size returns the "not condemnedsize" property of the specified message in the specified arena.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Message, GC.

    +

    Message, GC.

    -

    Syntax

    +

    Syntax

    -

    size_t mps_message_gc_not_condemned_size(mps_arena_t arena,mps_message_t message)

    +

    size_t mps_message_gc_not_condemned_size(mps_arena_t arena,mps_message_t message)

    -

    Arguments

    +

    Arguments

    @@ -6926,56 +7704,58 @@ void go(mps_space_t space)

    -

    Returned Values

    +

    Returned Values

    -

    An approximate size for the set of objects that were in collected pools, but were notcondemned in the collection that generated the message.

    +

    An approximate size for the set of objects that were in collected pools, but were notcondemned in the collection that generated the message.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    Currently, the only type of message that supports this property is mps_message_type_gc; such messages are generated whenever a garbage collectioncompletes. This method returns an approximation to the size of the set of objects that were incollected pools (so potentially subject to garbage collection), but were not condemned in thatcollection.

    +

    Currently, the only type of message that supports this property is mps_message_type_gc; such messages are generated whenever a garbage collectioncompletes. This method returns an approximation to the size of the set of objects that were incollected pools (so potentially subject to garbage collection), but were not condemned in thatcollection.

    -

    Example

    +

    Example

    -

    Error Handling

    +

    Error Handling

    -

    See Also

    +

    See Also

    -

    mps_message_*

    +

    + +mps_message_*

    -

    function mps_message_get

    +

    function mps_message_get

    -

    Name

    +

    Name

    -

    mps_message_get

    +

    mps_message_get

    -

    Summary

    +

    Summary

    -

    Gets a message of the specified type from a message queue.

    +

    Gets a message of the specified type from a message queue.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Message.

    +

    Message.

    -

    Syntax

    +

    Syntax

    -

    mps_bool_t mps_message_get(mps_message_t *message_return, mps_arena_t arena, mps_message_type_tmessage_type)

    +

    mps_bool_t mps_message_get(mps_message_t *message_return, mps_arena_t arena, mps_message_type_tmessage_type)

    -

    Arguments

    +

    Arguments

    message_return @@ -6993,17 +7773,17 @@ void go(mps_space_t space)

    -

    Returned Values

    +

    Returned Values

    -

    Returns true if a message has been removed from the queue, false if not.

    +

    Returns true if a message has been removed from the queue, false if not.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    If there is a message of the specified type on the message queue of the specified arena,then this function removes one such message from the queue, returns a handle to it via themessage_return @@ -7012,38 +7792,40 @@ void go(mps_space_t space)

    -

    Example

    +

    Example

    -

    See Also

    +

    See Also

    -

    mps_message_*

    +

    + +mps_message_*

    -

    mps_message_poll

    +

    mps_message_poll

    -

    Name

    +

    Name

    -

    mps_message_poll

    +

    mps_message_poll

    -

    Summary

    +

    Summary

    -

    mps_message_poll determines whether there are currently any messages on amessage queue.

    +

    mps_message_poll determines whether there are currently any messages on amessage queue.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Message.

    +

    Message.

    -

    Syntax

    +

    Syntax

    -

    mps_bool_t mps_message_poll(mps_arena_t arena)

    +

    mps_bool_t mps_message_poll(mps_arena_t arena)

    -

    Arguments

    +

    Arguments

    arena @@ -7051,259 +7833,267 @@ void go(mps_space_t space)

    -

    Returned Values

    +

    Returned Values

    -

    A flag to indicate whether there are any messages on the queue.

    +

    A flag to indicate whether there are any messages on the queue.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_message_poll is used to determine whether there are currently any messageson the message queue of the specified arena.

    +

    mps_message_poll is used to determine whether there are currently any messageson the message queue of the specified arena.

    -

    Example

    +

    Example

    -

    [missing]

    +

    [missing]

    -

    Error Handling

    +

    Error Handling

    -

    Can't fail.

    +

    Can't fail.

    -

    See Also

    +

    See Also

    -

    mps_message_get

    +

    +mps_message_get

    -

    Notes

    -

    If you expect a particular type of message, it is usually more practical to just call mps_message_get.

    +

    Notes

    +

    If you expect a particular type of message, it is usually more practical to just call mps_message_get.

    -

    function mps_message_queue_type

    +

    function mps_message_queue_type

    -

    Name

    -

    mps_message_queue_type

    +

    Name

    +

    mps_message_queue_type

    -

    Summary

    -

    mps_message_queue_type returns the type of the first message on a message queue.

    +

    Summary

    +

    mps_message_queue_type returns the type of the first message on a message queue.

    -

    Associated Protocols

    -

    Message.

    +

    Associated Protocols

    +

    Message.

    -

    Syntax

    -

    mps_bool_t mps_message_queue_type(mps_message_type_t *message_type_return, mps_arena_t arena)

    +

    Syntax

    +

    mps_bool_t mps_message_queue_type(mps_message_type_t *message_type_return, mps_arena_t arena)

    -

    Arguments

    -

    message_type_return -- the type of the first message on the queue of the specified arena

    +

    Arguments

    -

    arena -- the arena

    +

    message_type_return -- the type of the first message on the queue of the specified arena

    +

    arena -- the arena

    -

    Returned Values

    -

    "True" if there are any messages on the queue of the specified arena, "false" if not.

    +

    Returned Values

    +

    "True" if there are any messages on the queue of the specified arena, "false" if not.

    -

    Resources

    -

    mps.h

    +

    Resources

    +

    mps.h

    -

    Description

    -

    If there are any messages on the queue of the specified arena, then this function returns"true", and also returns the type of the first message via "message_type_return". Otherwise itreturns "false".

    +

    Description

    +

    If there are any messages on the queue of the specified arena, then this function returns"true", and also returns the type of the first message via "message_type_return". Otherwise itreturns "false".

    -

    Example

    +

    Example

    -

    See Also

    -

    mps_message_*

    +

    See Also

    +

    -

    type mps_message_t

    +mps_message_*

    -

    Name

    +

    type mps_message_t

    -

    mps_message_t

    +

    Name

    -

    Summary

    +

    mps_message_t

    -

    mps_message_t is used as a handle on an individual message.

    +

    Summary

    -

    Associated Protocols

    +

    mps_message_t is used as a handle on an individual message.

    -

    Message.

    +

    Associated Protocols

    -

    Type

    +

    Message.

    -

    typedef struct mps_message_s *mps_message_t

    -

    mps_message_s is an incomplete structure type used only to declare the opaque type mps_message_t.

    +

    Type

    +

    typedef struct mps_message_s *mps_message_t

    -

    Resources

    +

    mps_message_s is an incomplete structure type used only to declare the opaque type mps_message_t.

    -

    mps.h

    +

    Resources

    -

    Description

    +

    mps.h

    -

    The opaque type mps_message_t is used as a handle on an individual message. Messages aremanually managed. They are created at the instigation of the MPS (but see mps_message_type_enable), and are deleted by the client.

    -

    An mps_message_t is a reference into MPS managed memory, and can safely be stored as suchin scannable memory.

    +

    Description

    +

    The opaque type mps_message_t is used as a handle on an individual message. Messages aremanually managed. They are created at the instigation of the MPS (but see mps_message_type_enable), and are deleted by the client.

    -

    Example

    +

    An mps_message_t is a reference into MPS managed memory, and can safely be stored as suchin scannable memory.

    -

    Error Handling

    +

    Example

    -

    Not applicable.

    +

    Error Handling

    -

    See Also

    +

    Not applicable.

    -

    mps_message_*

    +

    See Also

    -

    function mps_message_type

    +

    +mps_message_*

    -

    Name

    -

    mps_message_type

    +

    function mps_message_type

    -

    Summary

    +

    Name

    -

    mps_message_type returns the type of a message.

    +

    mps_message_type

    -

    Associated Protocols

    +

    Summary

    -

    Message.

    +

    mps_message_type returns the type of a message.

    -

    Syntax

    +

    Associated Protocols

    -

    mps_message_type_t mps_message_type(mps_arena_t arena, mps_message_t message)

    +

    Message.

    -

    Arguments

    +

    Syntax

    -

    arena -- the arena containing the message

    +

    mps_message_type_t mps_message_type(mps_arena_t arena, mps_message_t message)

    -

    message -- a valid message; that is, one previously returned by mps_message_get, and notdiscarded via mps_message_discard

    +

    Arguments

    -

    Returned Values

    +

    arena -- the arena containing the message

    -

    The type of the specified message.

    +

    message -- a valid message; that is, one previously returned by mps_message_get, and notdiscarded via mps_message_discard

    -

    Resources

    +

    Returned Values

    -

    mps.h

    +

    The type of the specified message.

    -

    Description

    +

    Resources

    -

    mps_message_type returns the type of a message.

    +

    mps.h

    -

    Example

    +

    Description

    +

    mps_message_type returns the type of a message.

    -

    Error Handling

    +

    Example

    -

    See Also

    -

    mps_message_*

    +

    Error Handling

    -

    mps_message_type_collection_stats

    +

    See Also

    +

    -

    Name

    +mps_message_*

    -

    mps_message_type_collection_stats

    +

    mps_message_type_collection_stats

    -

    Summary

    -

    mps_message_type_collection_stats returns the type of garbage collection statistic messages.

    +

    Name

    +

    mps_message_type_collection_stats

    -

    Associated Protocols

    -

    Message, gc.

    +

    Summary

    +

    mps_message_type_collection_stats returns the type of garbage collection statistic messages.

    -

    Syntax

    -

    mps_message_type_t mps_message_type_collection_stats()

    +

    Associated Protocols

    +

    Message, gc.

    -

    Arguments

    +

    Syntax

    -

    Initial/Default Values

    +

    mps_message_type_t mps_message_type_collection_stats()

    -

    Not applicable.

    +

    Arguments

    -

    Returned Values

    -

    The type of garbage collection statistic messages.

    +

    Initial/Default Values

    +

    Not applicable.

    -

    Resources

    -

    Not applicable.

    +

    Returned Values

    +

    The type of garbage collection statistic messages.

    -

    Description

    -

    mps_message_type_collection_stats returns the type of garbage collection statisticmessages. Garbage collection statistic messages are used by the MPS to give the client informationabout garbage collections that have occurred. Such information may be useful in analysing theclient's memory usage over time.

    +

    Resources

    -

    The access methods specific to a message of this type are:

    +

    Not applicable.

    + + +

    Description

    + +

    mps_message_type_collection_stats returns the type of garbage collection statisticmessages. Garbage collection statistic messages are used by the MPS to give the client informationabout garbage collections that have occurred. Such information may be useful in analysing theclient's memory usage over time.

    + +

    The access methods specific to a message of this type are:

    -

    Example

    +

    Example

     {
@@ -7329,209 +8119,215 @@ void go(mps_space_t space)
    -

    Error Handling

    +

    Error Handling

    -

    Cannot fail.

    +

    Cannot fail.

    -

    See Also

    +

    See Also

    -

    mps_message_*,

    +

    -

    "Message Protocol", "GC Protocol"

    +mps_message_*.

    +

    "Message Protocol", "GC Protocol"

    -

    Notes

    +

    Notes

    -

    function mps_message_type_disable

    +

    function mps_message_type_disable

    -

    Name

    -

    mps_message_type_disable

    +

    Name

    +

    mps_message_type_disable

    -

    Summary

    -

    mps_message_type_disable restores the arena to the default state whereby messages of thespecified type are not generated.

    +

    Summary

    -

    This reverses the effect of an earlier call to "m ps_message_type_enable".

    +

    mps_message_type_disable restores the arena to the default state whereby messages of thespecified type are not generated.

    +

    This reverses the effect of an earlier call to "m ps_message_type_enable".

    -

    Associated Protocols

    -

    Message.

    +

    Associated Protocols

    +

    Message.

    -

    Syntax

    -

    void mps_message_type_disable(mps_arena_t arena, mps_message_type_t message_type)

    +

    Syntax

    +

    void mps_message_type_disable(mps_arena_t arena, mps_message_type_t message_type)

    -

    Arguments

    -

    arena -- the arena

    +

    Arguments

    -

    message_type -- the message type to be disabled

    +

    arena -- the arena

    +

    message_type -- the message type to be disabled

    -

    Returned Values

    -

    None.

    +

    Returned Values

    +

    None.

    -

    Resources

    -

    mps.h

    +

    Resources

    +

    mps.h

    -

    Description

    -

    This procedure may be used by the client to specify that messages of the specified typeshould not created for the specified arena.

    +

    Description

    -

    Messages are not generated by default, but the client may enable the generation of messageswith mps_message_type_enable.

    +

    This procedure may be used by the client to specify that messages of the specified typeshould not created for the specified arena.

    -

    Any existing messages of the specified type are flushed from the message queue.

    +

    Messages are not generated by default, but the client may enable the generation of messageswith mps_message_type_enable.

    +

    Any existing messages of the specified type are flushed from the message queue.

    -

    Example

    -

    [none]

    +

    Example

    +

    [none]

    -

    Error Handling

    -

    Never fails.

    +

    Error Handling

    +

    Never fails.

    -

    See Also

    -

    mps_message_*

    +

    See Also

    +

    -

    Notes

    +mps_message_*

    -

    It is permitted to call this function when the message type is already disabled. Such a callwill have no effect.

    +

    Notes

    -

    function mps_message_type_enable

    +

    It is permitted to call this function when the message type is already disabled. Such a callwill have no effect.

    -

    Name

    +

    function mps_message_type_enable

    -

    mps_message_type_enable

    +

    Name

    -

    Summary

    +

    mps_message_type_enable

    -

    mps_message_type_enable allows messages of the specified type to be created for thespecified arena. Without such enabling, the MPS will, by default, not generate any messages of thattype.

    +

    Summary

    -

    Associated Protocols

    +

    mps_message_type_enable allows messages of the specified type to be created for thespecified arena. Without such enabling, the MPS will, by default, not generate any messages of thattype.

    -

    Message.

    +

    Associated Protocols

    -

    Syntax

    +

    Message.

    -

    void mps_message_type_enable(mps_arena_t arena, mps_message_type_t message_type)

    +

    Syntax

    -

    Arguments

    +

    void mps_message_type_enable(mps_arena_t arena, mps_message_type_t message_type)

    -

    arena -- the arena

    -

    message_type -- the message type to be enabled

    +

    Arguments

    +

    arena -- the arena

    -

    Returned Values

    +

    message_type -- the message type to be enabled

    -

    None.

    +

    Returned Values

    -

    Resources

    +

    None.

    -

    mps.h

    +

    Resources

    -

    Description

    +

    mps.h

    -

    This procedure may be used by the client to specify that messages of the specified type maybe created for the specified arena. Without such enabling, the MPS will by default not generate anymessages of that type.

    -

    Note that the enabling of messages of a particular type implies that the client applicationwill handle and discard message of that type, or the message queue may consume unbounded resources.

    +

    Description

    -

    The client may disable message generation again by means of an equivalent call to mps_message_type_disable.

    +

    This procedure may be used by the client to specify that messages of the specified type maybe created for the specified arena. Without such enabling, the MPS will by default not generate anymessages of that type.

    +

    Note that the enabling of messages of a particular type implies that the client applicationwill handle and discard message of that type, or the message queue may consume unbounded resources.

    -

    Example

    +

    The client may disable message generation again by means of an equivalent call to mps_message_type_disable.

    -

    [none]

    +

    Example

    -

    Error Handling

    +

    [none]

    -

    Never fails.

    +

    Error Handling

    -

    See Also

    +

    Never fails.

    -

    mps_message_*

    -

    "Message Protocol"

    +

    See Also

    +

    -

    Notes

    +mps_message_*

    -

    It is permitted to call this function when the message type is already enabled. Such a callwill have no effect.

    +

    "Message Protocol"

    -

    +

    Notes

    -

    function mps_message_type_finalization

    +

    It is permitted to call this function when the message type is already enabled. Such a callwill have no effect.

    +

    -

    Name

    -

    mps_message_type_finalization

    +

    function mps_message_type_finalization

    -

    Summary

    +

    Name

    -

    mps_message_type_finalization returns the type of finalization messages.

    +

    mps_message_type_finalization

    -

    Associated Protocols

    +

    Summary

    -

    Message, Finalization.

    +

    mps_message_type_finalization returns the type of finalization messages.

    -

    Syntax

    +

    Associated Protocols

    -

    mps_message_type_t mps_message_type_finalization(void)

    +

    Message, Finalization.

    -

    Arguments

    +

    Syntax

    -

    None.

    +

    mps_message_type_t mps_message_type_finalization(void)

    -

    Returned Values

    +

    Arguments

    -

    The type of finalization messages.

    +

    None.

    -

    Resources

    +

    Returned Values

    -

    Not applicable.

    +

    The type of finalization messages.

    -

    Description

    +

    Resources

    -

    mps_message_type_finalization returns the type of finalization messages. Finalizationmessages are used by the MPS see signal to the client that an object has become finalizable. Inaddition to the usual methods applicable to messages, finalization messages support the mps_message_finalization_ref method which returns a reference to the registered object.

    +

    Not applicable.

    -

    Example

    +

    Description

    + +

    mps_message_type_finalization returns the type of finalization messages. Finalizationmessages are used by the MPS see signal to the client that an object has become finalizable. Inaddition to the usual methods applicable to messages, finalization messages support the mps_message_finalization_ref method which returns a reference to the registered object.

    + + +

    Example

     {
@@ -7547,45 +8343,49 @@ void go(mps_space_t space)
 }
    -

    See Also

    +

    See Also

    -

    mps_message_*, mps_finalize

    +

    + +mps_message_*, + +mps_finalize

    -

    function mps_message_type_gc

    +

    function mps_message_type_gc

    -

    Name

    +

    Name

    -

    mps_message_type_gc

    +

    mps_message_type_gc

    -

    Summary

    +

    Summary

    -

    mps_message_type_gc returns the type of garbage collectionstatistic messages.

    +

    mps_message_type_gc returns the type of garbage collectionstatistic messages.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Message.

    +

    Message.

    -

    Syntax

    +

    Syntax

    -

    mps_message_type_t mps_message_type_gc(void)

    +

    mps_message_type_t mps_message_type_gc(void)

    -

    Arguments

    +

    Arguments

    -

    None.

    +

    None.

    -

    Returned Values

    +

    Returned Values

    -

    The type of garbage collection statistic messages.

    +

    The type of garbage collection statistic messages.

    -

    Resources

    +

    Resources

    @@ -7594,24 +8394,25 @@ void go(mps_space_t space)

    -

    Description

    +

    Description

    -

    mps_message_type_gc returns the type of garbage collectionstatistic messages. Garbage collection statistic messages are used by the MPS to give the clientinformation about garbage collections that have occurred. Such information may be useful inanalysing the client's memory usage over time.

    +

    mps_message_type_gc returns the type of garbage collectionstatistic messages. Garbage collection statistic messages are used by the MPS to give the clientinformation about garbage collections that have occurred. Such information may be useful inanalysing the client's memory usage over time.

    -

    The access methods specific to a message of this type are:

    +

    The access methods specific to a message of this type are:

      -

    • mps_message_gc_live_size -- gives the total size of thecondemned objects that survived the collection that generated the message

      • +

    • mps_message_gc_live_size -- gives the total size of thecondemned objects that survived the collection that generated the message

      • -

    • mps_message_gc_condemned_size -- gives an approximate size forthe set of objects condemned in the collection that generated the message.

      • +

    • mps_message_gc_condemned_size + -- gives an approximate size for the set of objects condemned in the collection that generated the message.

      • -

    • mps_message_gc_not_condemned_size -- gives an approximate sizefor the set of objects that were in collected pools, but were not condemned in the collection thatgenerated the message.

      • +

    • mps_message_gc_not_condemned_size -- gives an approximate sizefor the set of objects that were in collected pools, but were not condemned in the collection thatgenerated the message.

    -

    Example

    +

    Example

     {
@@ -7628,126 +8429,134 @@ void go(mps_space_t space)
    -

    Error Handling

    +

    Error Handling

    -

    Cannot fail.

    +

    Cannot fail.

    -

    See Also

    +

    See Also

    -

    mps_message_*,

    +

    + +mps_message_*.

    -

    type mps_message_type_t

    +

    type mps_message_type_t

    -

    Name

    +

    Name

    -

    mps_message_type_t

    +

    mps_message_type_t

    -

    Summary

    +

    Summary

    -

    mps_message_type_t is the type of message types.

    +

    mps_message_type_t is the type of message types.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Message.

    +

    Message.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_message_type_t is the type whose values are the various message types. It is opaque.

    +

    mps_message_type_t is the type whose values are the various message types. It is opaque.

    -

    Example

    +

    Example

    -

    See Also

    +

    See Also

    -

    mps_message_*

    +

    + +mps_message_*

    -

    function mps_pool_check_fenceposts

    +

    function mps_pool_check_fenceposts

    -

    Name

    +

    Name

    -

    mps_pool_check_fenceposts

    +

    mps_pool_check_fenceposts

    -

    Summary

    +

    Summary

    -

    Check all the fenceposts in the pool.

    +

    Check all the fenceposts in the pool.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Debug

    +

    Debug

    -

    Syntax

    +

    Syntax

    -

    void mps_pool_check_fenceposts(mps_pool_t pool)

    +

    void mps_pool_check_fenceposts(mps_pool_t pool)

    -

    Arguments

    +

    Arguments

    -

    pool the pool whose fenceposts are to be checked

    +

    pool the pool whose fenceposts are to be checked

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This function is a debugging feature to check all the fenceposts in the pool. If a corruptedfencepost is found, an assert will fire. It is only useful to call this on a debug pool that hadfenceposting turned, it does nothing on other pools.

    +

    This function is a debugging feature to check all the fenceposts in the pool. If a corruptedfencepost is found, an assert will fire. It is only useful to call this on a debug pool that hadfenceposting turned, it does nothing on other pools.

    -

    Example

    +

    Example

    -

    mps_pool_check_fenceposts(gene_pool);

    +

    mps_pool_check_fenceposts(gene_pool);

    -

    Error Handling

    +

    Error Handling

    -

    If a corrupted fencepost is found, an assert will fire. You can install an assert handlerusing mps_assert_install, but you'll probably want to look at the problem with adebugger instead.

    +

    If a corrupted fencepost is found, an assert will fire. You can install an assert handlerusing mps_assert_install, but you'll probably want to look at the problem with adebugger instead.

    -

    See Also

    +

    See Also

    -

    mps_assert_install, mps_class_*_debug

    +

    + +mps_assert_install, + +mps_class_*_debug

    -

    structure mps_pool_debug_option_s

    +

    structure mps_pool_debug_option_s

    -

    Name

    +

    Name

    mps_pool_debug_option_s

    -

    Summary

    +

    Summary

    -

    This structure is used to pass debug options to mps_pool_create for debug classes.

    +

    This structure is used to pass debug options to mps_pool_create for debug classes.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Debug.

    +

    Debug.

    -

    Type

    +

    Type

     typedef struct mps_pool_debug_option_s {
@@ -7757,7 +8566,7 @@ typedef struct mps_pool_debug_option_s {
    -

    Members

    +

    Members

    fence_template @@ -7770,23 +8579,23 @@ typedef struct mps_pool_debug_option_s {

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    Structures of this type are used to pass debug options to mps_pool_create when creatinginstances of debug classes.

    +

    Structures of this type are used to pass debug options to mps_pool_create when creatinginstances of debug classes.

    -

    Fenceposting is enabled by specifying a non-zero fence_size; the size mustbe a multiple of the [pool/format] alignment. The content of fenceposts is given as a template thatis simply copied onto each fencepost (although sometimes the MPS will create fenceposts smaller thanthe given size, for example, to pad out some bit that was left unused because of alignmentrequirements).

    +

    Fenceposting is enabled by specifying a non-zero fence_size; the size mustbe a multiple of the [pool/format] alignment. The content of fenceposts is given as a template thatis simply copied onto each fencepost (although sometimes the MPS will create fenceposts smaller thanthe given size, for example, to pad out some bit that was left unused because of alignmentrequirements).

    -

    Example

    +

    Example

     static mps_pool_debug_option_s debugOptions = { (void *)"postpost", 8 };
-if(mps_pool_create(&pool, arena, mps_class_epdl_debug(),
+if(mps_pool_create(&pool, arena, mps_class_ams_debug(),
                    &debugOptions, 8192, 135, 8)
    != MPS_RES_OK) {
   printf("Error creating pool!"); exit(2);
@@ -7794,336 +8603,360 @@ if(mps_pool_create(&pool, arena, mps_class_epdl_debug(),
    -

    See Also

    +

    See Also

    -

    mps_pool_check_fenceposts

    +

    +mps_pool_check_fenceposts

    -

    Notes

    -

    Fencepost templates allow the client to specify complicated patterns that mimic illegal datavalues, that would cause an assert to fire if read by mistake, and that would never be written byany operation that writes at the wrong address by mistake.

    +

    Notes

    -

    Another trick is to make the pattern contain an instruction sequence that would cause theprogram to error or stop if executed by mistake.

    +

    Fencepost templates allow the client to specify complicated patterns that mimic illegal datavalues, that would cause an assert to fire if read by mistake, and that would never be written byany operation that writes at the wrong address by mistake.

    +

    Another trick is to make the pattern contain an instruction sequence that would cause theprogram to error or stop if executed by mistake.

    -

    function mps_rank_ambig

    +

    function mps_rank_ambig

    -

    Name

    -

    mps_rank_ambig

    +

    Name

    +

    mps_rank_ambig

    -

    Summary

    -

    Function returning the value representing "rank ambig".

    +

    Summary

    +

    Function returning the value representing "rank ambig".

    -

    Associated Protocols

    -

    Allocation, Root, Scanning.

    +

    Associated Protocols

    +

    Allocation, Root, Scanning.

    -

    Syntax

    -

    mps_rank_ambig()

    +

    Syntax

    +

    mps_rank_ambig()

    -

    Type

    -

    mps_rank_t mps_rank_ambig(void)

    +

    Type

    +

    mps_rank_t mps_rank_ambig(void)

    -

    Arguments

    -

    None.

    +

    Arguments

    +

    None.

    -

    Returned Values

    -

    Returns a value of type mps_rank_t representing "rank ambig".

    +

    Returned Values

    +

    Returns a value of type mps_rank_t representing "rank ambig".

    -

    Resources

    -

    mps.h

    +

    Resources

    +

    mps.h

    -

    Description

    -

    Used to get a value for "rank ambig", which is used to denote that certain references (in aroot, for example) are ambiguous references.

    +

    Description

    +

    Used to get a value for "rank ambig", which is used to denote that certain references (in aroot, for example) are ambiguous references.

    -

    Example

    +

    Example

    -

    See Also

    -

    mps_rank_t, mps_rank_exact

    +

    See Also

    +

    -

    function mps_rank_exact

    +mps_rank_t, +mps_rank_exact

    -

    Name

    -

    mps_rank_exact

    +

    function mps_rank_exact

    -

    Summary

    +

    Name

    -

    Used to declare references which the client wishes to be exact references.

    +

    mps_rank_exact

    -

    Associated Protocols

    +

    Summary

    -

    Allocation, Root, Scanning.

    +

    Used to declare references which the client wishes to be exact references.

    -

    Type

    +

    Associated Protocols

    -

    mps_rank_t mps_rank_exact(void);

    +

    Allocation, Root, Scanning.

    -

    Arguments

    +

    Type

    -

    No arguments.

    +

    mps_rank_t mps_rank_exact(void);

    -

    Returned Values

    +

    Arguments

    -

    Returns a rank (see mps_rank_t) which can be used to declare references to be exactreferences.

    +

    No arguments.

    -

    Resources

    +

    Returned Values

    -

    mps.h

    +

    Returns a rank (see mps_rank_t) which can be used to declare references to be exactreferences.

    -

    Description

    +

    Resources

    -

    Used to declare references which the client wishes to be exact, non-weak references.

    +

    mps.h

    -

    Example

    +

    Description

    -

    [missing]

    +

    Used to declare references which the client wishes to be exact, non-weak references.

    -

    See Also

    +

    Example

    -

    mps_rank_t, mps_rank_ambig, mps_rank_weak

    +

    [missing]

    -

    type mps_rank_t

    +

    See Also

    +

    -

    Name

    +mps_rank_t, -

    mps_rank_t

    +mps_rank_ambig, +mps_rank_weak

    -

    Summary

    -

    A type whose values are "reference ranks".

    +

    type mps_rank_t

    -

    Associated Protocols

    +

    Name

    -

    Allocation, Root.

    +

    mps_rank_t

    -

    Type

    +

    Summary

    -

    typedef unsigned int mps_rank_t;

    +

    A type whose values are "reference ranks".

    -

    Resources

    +

    Associated Protocols

    -

    mps.h

    +

    Allocation, Root.

    -

    Description

    +

    Type

    -

    mps_rank_t is a concrete type. It is an alias (via the C typedef mechanism) for "unsignedint" provided for convenience and clarity. An object of type mps_rank_t can store a valuerepresenting one reference rank. Reference ranks are used to conveniently express specific semanticsof particular references. See "MPS Scanning Protocol" for descriptions of these semantics, and mps_rank_* for the actual ranks used to declare these semantics.

    +

    typedef unsigned int mps_rank_t;

    -

    Example

    +

    Resources

    -

    (Probably won't be used explicitly, most likely to be seen in the prototype declaration forother MPS functions. For example, mps_root_create.)

    +

    mps.h

    -

    See Also

    +

    Description

    -

    mps_rank_*

    +

    mps_rank_t is a concrete type. It is an alias (via the C typedef mechanism) for "unsignedint" provided for convenience and clarity. An object of type mps_rank_t can store a valuerepresenting one reference rank. Reference ranks are used to conveniently express specific semanticsof particular references. See "MPS Scanning Protocol" for descriptions of these semantics, and mps_rank_* for the actual ranks used to declare these semantics.

    -

    function mps_rank_weak

    +

    Example

    +

    (Probably won't be used explicitly, most likely to be seen in the prototype declaration forother MPS functions. For example, mps_root_create.)

    -

    Name

    -

    mps_rank_weak

    +

    See Also

    +

    -

    Summary

    +mps_rank_*

    -

    Function to return a value used to represent "rank weak".

    +

    function mps_rank_weak

    -

    Associated Protocols

    -

    Allocation, Scanning.

    +

    Name

    +

    mps_rank_weak

    -

    Type

    -

    extern mps_rank_t mps_rank_weak(void);

    +

    Summary

    +

    Function to return a value used to represent "rank weak".

    -

    Arguments

    -

    None.

    +

    Associated Protocols

    +

    Allocation, Scanning.

    -

    Returned Values

    -

    Returns a value of type mps_rank_t that represent "rank weak".

    +

    Type

    +

    extern mps_rank_t mps_rank_weak(void);

    -

    Resources

    -

    mps.h

    +

    Arguments

    +

    None.

    -

    Description

    -

    mps_rank_weak returns a value used to represent "rank weak".

    +

    Returned Values

    -

    "Rank weak" is often used to denote that certain references (in a root or in objectsallocated in a pool) are weak references.

    +

    Returns a value of type mps_rank_t that represent "rank weak".

    -

    Example

    +

    Resources

    -

    <example of how to use the symbol>

    +

    mps.h

    -

    See Also

    +

    Description

    -

    mps_rank_t, mps_rank_exact

    +

    mps_rank_weak returns a value used to represent "rank weak".

    +

    "Rank weak" is often used to denote that certain references (in a root or in objectsallocated in a pool) are weak references.

    -

    type mps_reg_scan_t

    +

    Example

    -

    Name

    +

    <example of how to use the symbol>

    -

    mps_reg_scan_t

    +

    See Also

    -

    Summary

    +

    -

    Type of root scanning functions for mps_root_create_reg.

    +mps_rank_t, +mps_rank_exact

    -

    Associated Protocols

    -

    Root.

    +

    type mps_reg_scan_t

    -

    Syntax

    +

    Name

    + +

    mps_reg_scan_t

    + + +

    Summary

    + +

    Type of root scanning functions for mps_root_create_reg.

    + + +

    Associated Protocols

    + +

    Root.

    + + +

    Syntax

    typedef mps_res_t (*mps_reg_scan_t)( mps_ss_t scan_state, mps_thr_t thread, void *p, size_t s)

    -

    Arguments

    +

    Arguments

    -

    scan_state a scan state

    +

    scan_state a scan state

    -

    thread the thread

    +

    thread the thread

    -

    p a value passed through from root registration

    +

    p a value passed through from root registration

    -

    s a value passed through from root registration

    +

    s a value passed through from root registration

    -

    Returned Values

    +

    Returned Values

    -

    A result code.

    +

    A result code.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This is the type of root scanning functions the client provides to mps_root_create_reg.These functions will be called, whenever the root needs to be scanned, and passed the "p" and "s"values specified in the call to mps_root_create_reg.

    +

    This is the type of root scanning functions the client provides to mps_root_create_reg.These functions will be called, whenever the root needs to be scanned, and passed the "p" and "s"values specified in the call to mps_root_create_reg.

    -

    See Also

    +

    See Also

    -

    mps_root_create_reg, mps_stack_scan_ambig

    +

    + +mps_root_create_reg, + +mps_stack_scan_ambig

    -

    Notes

    +

    Notes

    -

    Users are not expected to write any scanning functions of this type. The one functionsupplied with the MPS, mps_stack_scan_ambig, should be enough for most purposes.

    +

    Users are not expected to write any scanning functions of this type. The one functionsupplied with the MPS, mps_stack_scan_ambig, should be enough for most purposes.

    -

    type mps_res_t

    +

    type mps_res_t

    -

    Name

    +

    Name

    -

    mps_res_t

    +

    mps_res_t

    -

    Summary

    +

    Summary

    -

    mps_res_t is the type of result codes returned by operations that may fail.

    +

    mps_res_t is the type of result codes returned by operations that may fail.

    -

    Type

    +

    Type

    -

    typedef int mps_res_t;

    +

    typedef int mps_res_t;

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    A result code indicates the success or failure of an operation, along with the reason forfailure. Like UNIX error codes, the meaning of the code depends on the call that returned it. Referto the documentation of the function for the exact meaning. This documentation describes the broadcategories with mnemonic names for various sorts of problems.

    +

    A result code indicates the success or failure of an operation, along with the reason forfailure. Like UNIX error codes, the meaning of the code depends on the call that returned it. Referto the documentation of the function for the exact meaning. This documentation describes the broadcategories with mnemonic names for various sorts of problems.

    -

    MPS_RES_OK: The operation succeeded. Out and in/out parameters will only be updated if OK isreturned, otherwise they will be left untouched. MPS_RES_OK is zero.

    +

    MPS_RES_OK: The operation succeeded. Out and in/out parameters will only be updated if OK isreturned, otherwise they will be left untouched. MPS_RES_OK is zero.

    -

    MPS_RES_FAIL: Something went wrong that does not fall into any of the other categories. Theexact meaning depends on the call. See the documentation of the function.

    +

    MPS_RES_FAIL: Something went wrong that does not fall into any of the other categories. Theexact meaning depends on the call. See the documentation of the function.

    -

    MPS_RES_RESOURCE: A needed resource could not be obtained. Which resource, depends on thecall. Compare with MPS_RES_MEMORY, which is a special case of this.

    +

    MPS_RES_RESOURCE: A needed resource could not be obtained. Which resource, depends on thecall. Compare with MPS_RES_MEMORY, which is a special case of this.

    -

    MPS_RES_MEMORY: Needed memory (committed memory, not address space) could not be obtained.

    +

    MPS_RES_MEMORY: Needed memory (committed memory, not address space) could not be obtained.

    -

    MPS_RES_LIMIT: An internal limitation was reached. For example, the maximum number ofsomething was reached.

    +

    MPS_RES_LIMIT: An internal limitation was reached. For example, the maximum number ofsomething was reached.

    -

    MPS_RES_UNIMPL: The operation, or some vital part of it, is unimplemented. This might bereturned by functions that are no longer supported, or by operations that are included for futureexpansion, but not yet supported.

    +

    MPS_RES_UNIMPL: The operation, or some vital part of it, is unimplemented. This might bereturned by functions that are no longer supported, or by operations that are included for futureexpansion, but not yet supported.

    -

    MPS_RES_IO: An I/O error occurred. Exactly what depends on the function.

    +

    MPS_RES_IO: An I/O error occurred. Exactly what depends on the function.

    -

    MPS_RES_COMMIT_LIMIT: The arena's commit limit would have been exceeded as a result of(explicit or implicit) allocation. See protocol.arena.commit.

    +

    MPS_RES_COMMIT_LIMIT: The arena's commit limit would have been exceeded as a result of(explicit or implicit) allocation. See protocol.arena.commit.

    -

    MPS_RES_PARAM: A parameter of the operation was invalid.

    +

    MPS_RES_PARAM: A parameter of the operation was invalid.

    -

    A

    +

    A

    -

    ny function that might fail will return a result code. Any other results of the function arebe passed back in "return" parameters. See MPS Interface Conventions for more information.

    +

    ny function that might fail will return a result code. Any other results of the function arebe passed back in "return" parameters. See MPS Interface Conventions for more information.

    -

    Example

    +

    Example

     mps_addr_t p;
@@ -8136,72 +8969,74 @@ if(res != MPS_RES_OK) {
 }
    -

    For more examples, s ee doc.mps.ref-man.if-conv.

    +

    For more examples, s ee doc.mps.ref-man.if-conv.

    -

    See Also

    +

    See Also

    -

    MPS_RES_*

    +

    + +MPS_RES_*

    -

    function mps_root_create

    +

    function mps_root_create

    -

    Name

    +

    Name

    -

    mps_root_create

    +

    mps_root_create

    -

    Summary

    +

    Summary

    -

    The function mps_root_create declares a root that consists of all the references indicatedby a scanning function.

    +

    The function mps_root_create declares a root that consists of all the references indicatedby a scanning function.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Root.

    +

    Root.

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_root_create(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_trm, mps_root_scan_t scan, void *p, size_t s)

    +

    mps_res_t mps_root_create(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_trm, mps_root_scan_t scan, void *p, size_t s)

    -

    Arguments

    +

    Arguments

    -

    root_o a pointer to a variable to store the new root structure

    +

    root_o a pointer to a variable to store the new root structure

    -

    arena the arena

    +

    arena the arena

    -

    rank the rank of references in the root

    +

    rank the rank of references in the root

    -

    rm the root mode

    +

    rm the root mode

    -

    scan the scanning function

    +

    scan the scanning function

    -

    p a value to be passed to the scanning function

    +

    p a value to be passed to the scanning function

    -

    s a value to be passed to the scanning function

    +

    s a value to be passed to the scanning function

    -

    Returned Values

    +

    Returned Values

    -

    If the return value is MPS_RES_OK, a new root structure in "*root_o".

    +

    If the return value is MPS_RES_OK, a new root structure in "*root_o".

    -

    Resources

    +

    Resources

    -

    mps.h.

    +

    mps.h.

    -

    Description

    +

    Description

    -

    The client provides a scanning function, that will be called with a scan state and "p" and"s", whenever the root needs to be scanned. See mps_root_scan_t for details.

    +

    The client provides a scanning function, that will be called with a scan state and "p" and"s", whenever the root needs to be scanned. See mps_root_scan_t for details.

    -

    If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be validwhenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're usingasynchronous GC, this could be right after the root is registered, so the root has to be valid whenit is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

    +

    If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be validwhenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're usingasynchronous GC, this could be right after the root is registered, so the root has to be valid whenit is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

    -

    Example

    +

    Example

     static mps_root_t mmRoot;
@@ -8223,79 +9058,94 @@ int main(void)
    -

    Error Handling

    +

    Error Handling

    -

    mps_root_create returns MPS_RES_MEMORY when it fails to allocate memory for the internalroot structure; you need to deallocate or reclaim something to make enough space, or expand thearena.

    +

    mps_root_create returns MPS_RES_MEMORY when it fails to allocate memory for the internalroot structure; you need to deallocate or reclaim something to make enough space, or expand thearena.

    -

    See Also

    +

    See Also

    -

    mps_root_scan_t, mps_rm_t, mps_rank_t, mps_root_t, mps_root_create_fmt,mps_root_create_table, MPS_RM_CONST

    +

    + +mps_root_scan_t, + +mps_rm_t, + +mps_rank_t, + +mps_root_t, + +mps_root_create_fmt, + +mps_root_create_table, + +MPS_RM_CONST

    -

    Notes

    +

    Notes

    -

    "p" and "s" are just arbitrary data that scanning function can use. This is needed because Clacks local functions.

    +

    "p" and "s" are just arbitrary data that scanning function can use. This is needed because Clacks local functions.

    -

    function mps_root_create_fmt

    +

    function mps_root_create_fmt

    -

    Name

    +

    Name

    -

    mps_root_create_fmt

    +

    mps_root_create_fmt

    -

    Summary

    +

    Summary

    -

    The function mps_root_create_fmt declares a root that consists of a block of objects, andprovides a scanning function for them.

    +

    The function mps_root_create_fmt declares a root that consists of a block of objects, andprovides a scanning function for them.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Root.

    +

    Root.

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_root_create_fmt(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_fmt_scan_t scan, mps_addr_t base, mps_addr_t limit)

    +

    mps_res_t mps_root_create_fmt(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_fmt_scan_t scan, mps_addr_t base, mps_addr_t limit)

    -

    Arguments

    +

    Arguments

    -

    root_o a pointer to a variable to store the new root structure

    +

    root_o a pointer to a variable to store the new root structure

    -

    arena the arena

    +

    arena the arena

    -

    rank the rank of references in the root

    +

    rank the rank of references in the root

    -

    rm the root mode

    +

    rm the root mode

    -

    scan the scanning function

    +

    scan the scanning function

    -

    base the address of the start of the root

    +

    base the address of the start of the root

    -

    limit the address just beyond the end of the root

    +

    limit the address just beyond the end of the root

    -

    Returned Values

    +

    Returned Values

    -

    If the return value is MPS_RES_OK, the new root in "*root_o".

    +

    If the return value is MPS_RES_OK, the new root in "*root_o".

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    The client provides a scanning function, that will be called with a scan state and an areaof memory, whenever the root needs to be scanned. See mps_fmt_scan_t for details.

    +

    The client provides a scanning function, that will be called with a scan state and an areaof memory, whenever the root needs to be scanned. See mps_fmt_scan_t for details.

    -

    If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be validwhenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're usingasynchronous GC, this could be right after the root is registered, so the root has to be valid whenit is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

    +

    If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be validwhenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're usingasynchronous GC, this could be right after the root is registered, so the root has to be valid whenit is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

    -

    Example

    +

    Example

     static mps_root_t mmRoot;
@@ -8322,81 +9172,104 @@ int main(void)
    -

    Error Handling

    +

    Error Handling

    -

    mps_root_create_fmt returns MPS_RES_MEMORY when it fails to allocate memory for theinternal root structure; you need to deallocate or reclaim something to make enough space, or expandthe arena.

    +

    mps_root_create_fmt returns MPS_RES_MEMORY when it fails to allocate memory for theinternal root structure; you need to deallocate or reclaim something to make enough space, or expandthe arena.

    -

    See Also

    +

    See Also

    -

    mps_fmt_scan_t, mps_rm_t, mps_rank_t, mps_root_t, mps_root_create, mps_root_create_table,MPS_RM_PROT, MPS_RM_PROT_INNER, MPS_RM_CONST

    +

    + +mps_fmt_scan_t, + +mps_rm_t, + +mps_rank_t, + +mps_root_t, + +mps_root_create, + +mps_root_create_table, + +MPS_RM_PROT, + +MPS_RM_PROT_INNER, + +MPS_RM_CONST

    -

    Notes

    +

    Notes

    -

    This is like mps_root_create_table, except you get to supply your own scanning function.This is like mps_root_create, except the scanning function has a slightly different argument list(and the MPS knows where the root is).

    +

    This is like mps_root_create_table, except you get to supply your own scanning function.This is like mps_root_create, except the scanning function has a slightly different argument list(and the MPS knows where the root is).

    -

    function mps_root_create_reg

    +

    function mps_root_create_reg

    -

    Name

    +

    Name

    -

    mps_root_create_reg

    +

    mps_root_create_reg

    -

    Summary

    +

    Summary

    -

    mps_root_create_reg registers a thread as a root.

    +

    mps_root_create_reg registers a thread as a root.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Root.

    +

    Root.

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_root_create_reg(mps_root_t * root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_thr_t thread, mps_reg_scan_t scan, void *p, size_t s)

    +

    mps_res_t mps_root_create_reg(mps_root_t * root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_thr_t thread, mps_reg_scan_t scan, void *p, size_t s)

    -

    Arguments

    +

    Arguments

    -

    root_o a pointer to a variable to store the new root structure

    +

    root_o a pointer to a variable to store the new root structure

    -

    arena the arena

    +

    arena the arena

    -

    rank the rank of references in the root

    +

    rank the rank of references in the root

    -

    rm the root mode

    +

    rm the root mode

    -

    thread the thread to the registered as a root

    +

    thread the thread to the registered as a root

    -

    scan the scanning function

    +

    scan the scanning function

    -

    p a value to be passed to the scanning function

    +

    p a value to be passed to the scanning function

    -

    s a value to be passed to the scanning function

    +

    s a value to be passed to the scanning function

    -

    Returned Values

    +

    Returned Values

    -

    If the return value is MPS_RES_OK, a new root structure in "*root_o".

    +

    If the return value is MPS_RES_OK, a new root structure in "*root_o".

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_root_create_reg declares the state of a thread as a root. The client provides a scanningfunction that will be called and passed "p" and "s", whenever the root needs to be scanned. See mps_reg_scan_t for details.

    +

    mps_root_create_reg +declares the state of a thread as a root. The client provides a +scanning function that will be called and passed "p" and "s", whenever +the root needs to be scanned. See mps_reg_scan_t for details.

    -

    If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be validwhenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're usingasynchronous GC, this could be right after the root is registered, so the root has to be valid whenit is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

    +

    If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be validwhenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're usingasynchronous GC, this could be right after the root is registered, so the root has to be valid whenit is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

    -

    Example

    +

    Example

     typedef struct {
@@ -8420,77 +9293,81 @@ void InitThread(ThreadLocals *thr)
    -

    Error Handling

    +

    Error Handling

    -

    mps_root_create_reg returns MPS_RES_MEMORY when it fails to allocate memory for theinternal root structure; you need to deallocate or reclaim something to make enough space, or expandthe arena.

    +

    mps_root_create_reg returns MPS_RES_MEMORY when it fails to allocate memory for theinternal root structure; you need to deallocate or reclaim something to make enough space, or expandthe arena.

    -

    See Also

    +

    See Also

    -

    mps_stack_scan_ambig, mps_reg_scan_t

    +

    + +mps_stack_scan_ambig, + +mps_reg_scan_t

    -

    Notes

    +

    Notes

    -

    Only one suitable scanning function is supplied with the MPS, namely mps_stack_scan_ambig.

    +

    Only one suitable scanning function is supplied with the MPS, namely mps_stack_scan_ambig.

    -

    function mps_root_create_table

    +

    function mps_root_create_table

    -

    Name

    +

    Name

    -

    mps_root_create_table

    +

    mps_root_create_table

    -

    Summary

    +

    Summary

    -

    mps_root_create_table create s a root that is a vector of references.

    +

    mps_root_create_table create s a root that is a vector of references.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Root.

    +

    Root.

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_root_create_table(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t size)

    +

    mps_res_t mps_root_create_table(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t size)

    -

    Arguments

    +

    Arguments

    -

    root_o a pointer to a variable for storing the new root structure in

    +

    root_o a pointer to a variable for storing the new root structure in

    -

    arena the arena

    +

    arena the arena

    -

    rank the rank of the references in this root

    +

    rank the rank of the references in this root

    -

    rm the root mode

    +

    rm the root mode

    -

    base a pointer to the vector of references that is being registered

    +

    base a pointer to the vector of references that is being registered

    -

    size the number of references in the vector being registered

    +

    size the number of references in the vector being registered

    -

    Returned Values

    +

    Returned Values

    -

    If the return value is MPS_RES_OK, the new root in "*root_o".

    +

    If the return value is MPS_RES_OK, the new root in "*root_o".

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This function declares a root that is a vector of references.

    +

    This function declares a root that is a vector of references.

    -

    If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be validwhenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're usingasynchronous GC, this could be right after the root is registered, so the root has to be valid whenit is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

    +

    If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be validwhenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're usingasynchronous GC, this could be right after the root is registered, so the root has to be valid whenit is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

    -

    Example

    +

    Example

     static mps_root_t mmRoot;
@@ -8513,50 +9390,59 @@ int main(void)
    -

    Error Handling

    +

    Error Handling

    -

    mps_root_create_table returns MPS_RES_MEMORY when it fails to allocate memory for theinternal root structure; you need to deallocate or reclaim something to make enough space, or expandthe arena.

    +

    mps_root_create_table returns MPS_RES_MEMORY when it fails to allocate memory for theinternal root structure; you need to deallocate or reclaim something to make enough space, or expandthe arena.

    -

    See Also

    +

    See Also

    -

    mps_root_create_table_masked, MPS_RM_PROT, MPS_RM_PROT_INNER, MPS_RM_CONST

    +

    + +mps_root_create_table_masked, + +MPS_RM_PROT, + +MPS_RM_PROT_INNER, + +MPS_RM_CONST

    -

    function mps_root_create_table_masked

    +

    function mps_root_create_table_masked

    -

    Name

    +

    Name

    -

    mps_root_create_table_masked

    +

    mps_root_create_table_masked

    -

    Summary

    +

    Summary

    -

    mps_root_create_table_masked creates a root that is a vector of tagged values.

    +

    mps_root_create_table_masked creates a root that is a vector of tagged values.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Root.

    +

    Root.

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_root_create_table_masked(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t size, mps_word_t mask);

    +

    mps_res_t mps_root_create_table_masked(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t size, mps_word_t mask);

    -

    Arguments

    +

    Arguments

    -

    root_o a pointer to a variable for storing the new root structure in

    +

    root_o a pointer to a variable for storing the new root structure in

    -

    arena the arena

    +

    arena the arena

    -

    rank the rank of the references in this root

    +

    rank the rank of the references in this root

    -

    rm the root mode

    +

    rm the root mode

    -

    base a pointer to the vector of references that is being registered

    +

    base a pointer to the vector of references that is being registered

    size the number of references in the vector being registered @@ -8565,24 +9451,24 @@ int main(void)

    -

    Returned Values

    +

    Returned Values

    -

    If the return value is MPS_RES_OK, the new root in "*root_o".

    +

    If the return value is MPS_RES_OK, the new root in "*root_o".

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_root_create_table_masked creates a root that is a table of tagged values. The maskparameter indicates which bits of a pointer are tag bits. References are assumed to have a tag ofzero, values with other tags are ignored.

    +

    mps_root_create_table_masked creates a root that is a table of tagged values. The maskparameter indicates which bits of a pointer are tag bits. References are assumed to have a tag ofzero, values with other tags are ignored.

    -

    If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be validwhenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're usingasynchronous GC, this could be right after the root is registered, so the root has to be valid whenit is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

    +

    If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be validwhenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're usingasynchronous GC, this could be right after the root is registered, so the root has to be valid whenit is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

    -

    Example

    +

    Example

     #define tagMASK 0x0003
@@ -8607,64 +9493,73 @@ int main(void)
    -

    Error Handling

    +

    Error Handling

    -

    mps_root_create_table_masked returns MPS_RES_MEMORY when it fails to allocate memoryfor the internal root structure; you need to deallocate or reclaim something to make enough space,or expand the arena.

    +

    mps_root_create_table_masked returns MPS_RES_MEMORY when it fails to allocate memoryfor the internal root structure; you need to deallocate or reclaim something to make enough space,or expand the arena.

    -

    See Also

    +

    See Also

    -

    mps_root_create_table, MPS_RM_PROT, MPS_RM_PROT_INNER, MPS_RM_CONST

    +

    + +mps_root_create_table, + +MPS_RM_PROT, + +MPS_RM_PROT_INNER, + +MPS_RM_CONST

    -

    type mps_root_scan_t

    +

    type mps_root_scan_t

    -

    Name

    +

    Name

    -

    mps_root_scan_t

    +

    mps_root_scan_t

    -

    Summary

    +

    Summary

    -

    Type of root scanning functions for mps_root_create.

    +

    Type of root scanning functions for mps_root_create.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Root.

    +

    Root.

    -

    Syntax

    +

    Syntax

    -

    typedef mps_res_t (*mps_root_scan_t)(mps_ss_t scan_state, void * p, size_t s)

    +

    typedef mps_res_t (*mps_root_scan_t)(mps_ss_t scan_state, void * p, size_t s)

    -

    Arguments

    +

    Arguments

    -

    scan_state a scan state

    +

    scan_state a scan state

    -

    p an argument passed through from mps_root_create

    +

    p an argument passed through from mps_root_create

    -

    s an argument passed through from mps_root_create

    +

    s an argument passed through from mps_root_create

    -

    Returned Values

    +

    Returned Values

    -

    A result code.

    +

    A result code.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This is the type of root scanning functions the client provides tomps_root_create. The MPS will call these functions whenever the root needs to bescanned, with a scan state (of type mps_ss_t ), and the p ands values specified in the call to mps_root_create. Apart from theargument list, the scanning function works like the format scan methods: it needs to indicate allreferences using mps_fix or MPS_FIX*.

    +

    This is the type of root scanning functions the client provides tomps_root_create. The MPS will call these functions whenever the root needs to bescanned, with a scan state (of type mps_ss_t ), and the p ands values specified in the call to mps_root_create. Apart from theargument list, the scanning function works like the format scan methods: it needs to indicate allreferences using mps_fix or MPS_FIX*.

    -

    Example

    +

    Example

     static StackFrame *stackBottom;
@@ -8690,129 +9585,158 @@ static mps_res_t rootScanner(mps_ss_t ss, void * p, size_t s)
    -

    Error Handling

    +

    Error Handling

    -

    If a fixing operation returns a value other than MPS_RES_OK, the scanningfunction must return that value, and may return without scanning further references. Generally, itis better if it returns as soon as possible. If the scanning is completed successfully, the functionshould return MPS_RES_OK.

    +

    If a fixing operation returns a value other than MPS_RES_OK, the scanning function must +return that value, and may return without scanning further +references. Generally, itis better if it returns as soon as +possible. If the scanning is completed successfully, the +function should return MPS_RES_OK.

    -

    See Also

    +

    See Also

    -

    mps_root_create, mps_ss_t, mps_fix, MPS_SCAN_BEGIN, MPS_SCAN_END, MPS_FIX12, MPS_FIX1,MPS_FIX2, MPS_FIX_CALL, mps_fmt_scan_t

    +

    + +mps_root_create, + +mps_ss_t, + +mps_fix, + +MPS_SCAN_BEGIN, + +MPS_SCAN_END, + +MPS_FIX12, + +MPS_FIX1, + +MPS_FIX2, + +MPS_FIX_CALL, + +mps_fmt_scan_t

    -

    type mps_roots_stepper_t

    +

    type mps_roots_stepper_t

    -

    Name

    +

    Name

    -

    mps_roots_stepper_t

    +

    mps_roots_stepper_t

    -

    Summary

    +

    Summary

    -

    Type of the client-supplied root walker component.

    +

    Type of the client-supplied root walker component.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    None.

    +

    None.

    -

    Type

    +

    Type

    typedef void (*mps_roots_stepper_t)( mps_addr_t *, mps_root_t, void *, size_t )

    -

    Arguments

    +

    Arguments

    -

    The function pointed to by an object of type mps_roots_stepper_t takes the followingargument list:

    +

    The function pointed to by an object of type mps_roots_stepper_t takes the followingargument list:

    -

    (mps_addr_t *ref, mps_root_t root, void *p, size_t s)

    +

    (mps_addr_t *ref, mps_root_t root, void *p, size_t s)

    -

    ref is the address of a root which references an object in the arena. It's a pointer to aroot which points to "something" in the client heap. That "something" will be an object if the rootis an exact root. But it might be an interior pointer to an object if the root is an ambiguous root.

    +

    ref is the address of a root which references an object in the arena. It's a pointer to aroot which points to "something" in the client heap. That "something" will be an object if the rootis an exact root. But it might be an interior pointer to an object if the root is an ambiguous root.

    -

    root is the MPS root object which contains ref.

    +

    root is the MPS root object which contains ref.

    -

    p and s are two closure values which are copies of the corresponding values which the clientpassed into mps_arena_roots_walk.

    +

    p and s are two closure values which are copies of the corresponding values which the clientpassed into mps_arena_roots_walk.

    -

    Returned Values

    +

    Returned Values

    -

    he function pointed to by an object of type mps_roots_stepper_t returns no values.

    +

    he function pointed to by an object of type mps_roots_stepper_t returns no values.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    A pointer to a function is passed into the function mps_arena_roots_walk; the pointer hasthis type. The root walker arranges to apply this function to all objects which are directlyreferenced from the roots.

    +

    A pointer to a function is passed into the function mps_arena_roots_walk; the pointer hasthis type. The root walker arranges to apply this function to all objects which are directlyreferenced from the roots.

    -

    Example

    +

    Example

    -

    <example of how to use the symbol>

    +

    <example of how to use the symbol>

    -

    Error Handling

    +

    Error Handling

    -

    T

    +

    T

    -

    he function pointed to by an object of type mps_roots_stepper_t has no way of signalling anerror to the caller.

    +

    he function pointed to by an object of type mps_roots_stepper_t has no way of signalling anerror to the caller.

    -

    See Also

    +

    See Also

    -

    mps_arena_roots_arena_walk

    +

    + +mps_arena_roots_arena_walk

    -

    Notes

    +

    Notes

    -

    type mps_sac_classes_s

    +

    type mps_sac_class_s

    -

    Name

    +

    Name

    -

    mps_sac_classes_s

    +

    mps_sac_class_s

    -

    Summary

    +

    Summary

    -

    A structure describing a size class to be passed as an argument to mps_sac_create.

    +

    A structure describing a size class to be passed as an argument to mps_sac_create.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Allocation cache

    +

    Allocation cache

    -

    Type

    +

    Type

    -typedef struct mps_sac_classes_s {
+typedef struct mps_sac_class_s {
   size_t mps_block_size;
   size_t mps_cached_count;
   unsigned mps_frequency;
-} mps_sac_classes_s;
+} mps_sac_class_s;
    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    mps_sac_classes_s is the element t ype of the array passed tomps_sac_create to describ e the size classes. Each element of this array describes oneclass by specifying block_size, the maximum size (in bytes) in this class;cached_count , the number of objects of this class to cache ; andfrequency , a number that describes the frequency of requests (allocation anddeallocation combined ) in this class relative to all the other classes. The classes should be givenin the order of ascending size.

    +

    mps_sac_class_s is the element t ype of the array passed tomps_sac_create to describ e the size classes. Each element of this array describes oneclass by specifying block_size, the maximum size (in bytes) in this class;cached_count , the number of objects of this class to cache ; andfrequency , a number that describes the frequency of requests (allocation anddeallocation combined ) in this class relative to all the other classes. The classes should be givenin the order of ascending size.

    -

    block_size s have to be aligned to the pool alignment. All sizes must bedifferent, and the smallest size must be large enough to hold a void *.

    +

    block_size s have to be aligned to the pool alignment. All sizes must bedifferent, and the smallest size must be large enough to hold a void *.

    cached_count @@ -8821,14 +9745,14 @@ typedef struct mps_sac_classes_s { of zero prevents anycaching of blocks falling into that class.

    -

    The MPS automatically provides an "overlarge" class for arbitrarily large objects above thelargest class described. Allocations falling into the overlarge class are not cached.

    +

    The MPS automatically provides an "overlarge" class for arbitrarily large objects above thelargest class described. Allocations falling into the overlarge class are not cached.

    -

    Example

    +

    Example

       mps_sac_t sac;
-  mps_sac_classes_s classes[3] = { {8, 38, 1}, {136, 19, 3}, {512, 4, 1} };
+  mps_sac_class_s classes[3] = { {8, 38, 1}, {136, 19, 3}, {512, 4, 1} };
 
   res = mps_sac_create(&sac, pool, 3, classes);
   if (res != MPS_RES_OK) {
@@ -8838,74 +9762,76 @@ typedef struct mps_sac_classes_s {
    -

    See Also

    +

    See Also

    -

    mps_sac_create

    +

    + +mps_sac_create

    -

    Notes

    +

    Notes

    -

    Any blocks whose size falls between two classes are allocated from the larger class.

    +

    Any blocks whose size falls between two classes are allocated from the larger class.

    -

    function mps_sac_create

    +

    function mps_sac_create

    -

    Name

    +

    Name

    -

    mps_sac_create

    +

    mps_sac_create

    -

    Summary

    +

    Summary

    -

    This function creates a segregated allocation cache.

    +

    This function creates a segregated allocation cache.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Allocation cache

    +

    Allocation cache

    -

    Type

    +

    Type

    -

    mps_res_t mps_sac_create(mps_sac_t *sac_o, mps_pool_t pool, size_t classes_count,mps_sac_classes_s *classes);

    +

    mps_res_t mps_sac_create(mps_sac_t *sac_o, mps_pool_t pool, size_t classes_count,mps_sac_class_s *classes);

    -

    Arguments

    +

    Arguments

    -

    sac_o a pointer to a variable to hold the cache created

    +

    sac_o a pointer to a variable to hold the cache created

    -

    pool the pool the cache is attached to

    +

    pool the pool the cache is attached to

    -

    classes_count the number of the size classes

    +

    classes_count the number of the size classes

    -

    classes pointer to the first element of an array describing the size classes

    +

    classes pointer to the first element of an array describing the size classes

    -

    Returned Values

    +

    Returned Values

    -

    If the return value is MPS_RES_OK, a new cache in *sac_o.

    +

    If the return value is MPS_RES_OK, a new cache in *sac_o.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This function creates an allocation cache whose free-list is segregated into the given sizeclasses. The cache can get more memory from the given pool, or return memory to it.

    +

    This function creates an allocation cache whose free-list is segregated into the given sizeclasses. The cache can get more memory from the given pool, or return memory to it.

    -

    Segregated allocation caches can be associated with any pool that supports mps_alloc and mps_free.

    +

    Segregated allocation caches can be associated with any pool that supports mps_alloc and mps_free.

    -

    The size classes are described by an array of element type mps_sac_classes_s(q.v.). This array is used to initialize the cache, and is not needed aftermps_sac_create returns. There might be a limit on how many classes can be described,but it will be no less than MPS_SAC_CLASS_LIMIT. You must specify at least one class.The MPS automatically provides an "overlarge" class for arbitrarily large objects above the largestclass described. Allocations falling into the overlarge class are not cached.

    +

    The size classes are described by an array of element type mps_sac_class_s(q.v.). This array is used to initialize the cache, and is not needed aftermps_sac_create returns. There might be a limit on how many classes can be described,but it will be no less than MPS_SAC_CLASS_LIMIT. You must specify at least one class.The MPS automatically provides an "overlarge" class for arbitrarily large objects above the largestclass described. Allocations falling into the overlarge class are not cached.

    -

    Example

    +

    Example

       mps_sac_t sac;
-  mps_sac_classes_s classes[3] = { {8, 38, 1}, {136, 19, 3}, {512, 4, 1} };
+  mps_sac_class_s classes[3] = { {8, 38, 1}, {136, 19, 3}, {512, 4, 1} };
 
   res = mps_sac_create(&sac, pool, 3, classes);
   if (res != MPS_RES_OK) {
@@ -8915,69 +9841,85 @@ typedef struct mps_sac_classes_s {
    -

    Error Handling

    +

    Error Handling

    -

    mps_sac_create returns MPS_RES_MEMORY orMPS_RES_COMMIT_LIMIT when it fails to allocate memory for the internal cache structure;see the documentation for those return codes for recovery options. It returnsMPS_RES_LIMIT if you ask for too many size classes; combine some small adjacentclasses. It returns MPS_RES_PARAM if the pool doesn't support segregated allocationcaches.

    +

    mps_sac_create returns MPS_RES_MEMORY orMPS_RES_COMMIT_LIMIT when it fails to allocate memory for the internal cache structure;see the documentation for those return codes for recovery options. It returnsMPS_RES_LIMIT if you ask for too many size classes; combine some small adjacentclasses. It returns MPS_RES_PARAM if the pool doesn't support segregated allocationcaches.

    -

    See Also

    +

    See Also

    -

    mps_sac_classes_s, MPS_SAC_CLASS_LIMIT, mps_sac_destroy, MPS_RES_MEMORY,MPS_RES_COMMIT_LIMIT, MPS_RES_LIMIT, MPS_RES_PARAM, mps_sac_t

    +

    + +mps_sac_class_s, + +MPS_SAC_CLASS_LIMIT, + +mps_sac_destroy, + +MPS_RES_MEMORY, + +MPS_RES_COMMIT_LIMIT, + +MPS_RES_LIMIT, + +MPS_RES_PARAM, + +mps_sac_t

    -

    Notes

    +

    Notes

    -

    Too many classes will slow down allocation; too few classes waste more space in internalfragmentation. It is assumed that overlarge allocations are rare; otherwise, you would add anotherclass for them, or even create separate allocation caches or pools for them.

    +

    Too many classes will slow down allocation; too few classes waste more space in internalfragmentation. It is assumed that overlarge allocations are rare; otherwise, you would add anotherclass for them, or even create separate allocation caches or pools for them.

    -

    Some pools will work more efficiently with caches than others. In the future, the MPS mightoffer pools specially optimized for particular types of cache.

    +

    Some pools will work more efficiently with caches than others. In the future, the MPS mightoffer pools specially optimized for particular types of cache.

    -

    Segregated allocation caches work poorly with debug pool classes at the moment: the checkingonly happens when blocks are moved between the cache and the pool. This will be fixed, but the speedof allocation with a debug class will always be similar to mps_alloc, rather than cached speed.

    +

    Segregated allocation caches work poorly with debug pool classes at the moment: the checkingonly happens when blocks are moved between the cache and the pool. This will be fixed, but the speedof allocation with a debug class will always be similar to mps_alloc, rather than cached speed.

    -

    function mps_sac_destroy

    +

    function mps_sac_destroy

    -

    Name

    +

    Name

    -

    mps_sac_destroy

    +

    mps_sac_destroy

    -

    Summary

    +

    Summary

    -

    This function destroys a segregated allocation cache.

    +

    This function destroys a segregated allocation cache.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Allocation cache

    +

    Allocation cache

    -

    Type

    +

    Type

    -

    void mps_sac_destroy(mps_sac_t);

    +

    void mps_sac_destroy(mps_sac_t);

    -

    Arguments

    +

    Arguments

    -

    sac the segregated allocation cache

    +

    sac the segregated allocation cache

    -

    Returned Values

    +

    Returned Values

    -

    None.

    +

    None.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This function destroys a segregated allocation cache. All memory held in it is returned tothe associated pool.

    +

    This function destroys a segregated allocation cache. All memory held in it is returned tothe associated pool.

    -

    Example

    +

    Example

       res = mps_sac_create(&sac, pool, 3, classes);
@@ -8993,64 +9935,68 @@ typedef struct mps_sac_classes_s {
    -

    See Also

    +

    See Also

    -

    mps_sac_create, mps_sac_t

    +

    + +mps_sac_create, + +mps_sac_t

    -

    Notes

    +

    Notes

    -

    Destroying the cache might well cause the pool to return some memory to the arena, butthat's up to the pool's usual policy.

    +

    Destroying the cache might well cause the pool to return some memory to the arena, butthat's up to the pool's usual policy.

    -

    Destroying the cache has no effect on objects allocated through it.

    +

    Destroying the cache has no effect on objects allocated through it.

    -

    function mps_sac_flush

    +

    function mps_sac_flush

    -

    Name

    +

    Name

    -

    mps_sac_flush

    +

    mps_sac_flush

    -

    Summary

    +

    Summary

    -

    This function flushes the segregated allocation cache given.

    +

    This function flushes the segregated allocation cache given.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Allocation cache

    +

    Allocation cache

    -

    Type

    +

    Type

    -

    void mps_sac_flush(mps_sac_t sac);

    +

    void mps_sac_flush(mps_sac_t sac);

    -

    Arguments

    +

    Arguments

    -

    sac the segregated allocation cache

    +

    sac the segregated allocation cache

    -

    Returned Values

    +

    Returned Values

    -

    None.

    +

    None.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This function flushes the segregated allocation cache given, returning all memory held in itto the associated pool.

    +

    This function flushes the segregated allocation cache given, returning all memory held in itto the associated pool.

    -

    The client is responsible for synchronising the access to the cache, but the MPS willproperly synchronize with any other threads that might be accessing the same pool.

    +

    The client is responsible for synchronising the access to the cache, but the MPS willproperly synchronize with any other threads that might be accessing the same pool.

    -

    Example

    +

    Example

       mps_sac_t sac_small, sac_large;
@@ -9079,58 +10025,60 @@ typedef struct mps_sac_classes_s {
    -

    See Also

    +

    See Also

    -

    mps_sac_t

    +

    + +mps_sac_t

    -

    Notes

    +

    Notes

    -

    This is something that you'd typically do when you know you won't be using the cache for awhile, but want to hold on to the cache itself. Destroying a cache has the effect of flushing it,naturally.

    +

    This is something that you'd typically do when you know you won't be using the cache for awhile, but want to hold on to the cache itself. Destroying a cache has the effect of flushing it,naturally.

    -

    Flushing the cache might well cause the pool to return some memory to the arena, but that'supto the pool's usual policy.

    +

    Flushing the cache might well cause the pool to return some memory to the arena, but that'supto the pool's usual policy.

    -

    Note that the MPS might also decide to take memory from the cache without the clientrequesting a flush.

    +

    Note that the MPS might also decide to take memory from the cache without the clientrequesting a flush.

    -

    type mps_sac_t

    +

    type mps_sac_t

    -

    Name

    +

    Name

    -

    mps_sac_t

    +

    mps_sac_t

    -

    Summary

    +

    Summary

    -

    Type of segregated allocation caches.

    +

    Type of segregated allocation caches.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Allocation cache

    +

    Allocation cache

    -

    Type

    +

    Type

    -

    typedef struct mps_sac_s *mps_sac_t;

    +

    typedef struct mps_sac_s *mps_sac_t;

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    A value of this type represents an allocation cache with segregated freelists. It is anopaque type.

    +

    A value of this type represents an allocation cache with segregated freelists. It is anopaque type.

    -

    Example

    +

    Example

       mps_sac_t sac;
-  mps_sac_classes_s classes[3] = { {8, 38, 1}, {136, 19, 3}, {512, 4, 1} };
+  mps_sac_class_s classes[3] = { {8, 38, 1}, {136, 19, 3}, {512, 4, 1} };
 
   res = mps_sac_create(&sac, pool, 3, classes);
   if (res != MPS_RES_OK) {
@@ -9140,68 +10088,82 @@ typedef struct mps_sac_classes_s {
    -

    See Also

    +

    See Also

    -

    mps_sac_create, mps_sac_destroy, MPS_SAC_ALLOC,mps_sac_alloc, MPS_SAC_FREE, mps_sac_free,mps_sac_flush

    +

    + +mps_sac_create, + +mps_sac_destroy, + +MPS_SAC_ALLOC, + +mps_sac_alloc, + +MPS_SAC_FREE, + +mps_sac_free, + +mps_sac_flush

    -

    Notes

    +

    Notes

    -

    None.

    +

    None.

    -

    function mps_stack_scan_ambig

    +

    function mps_stack_scan_ambig

    -

    Name

    +

    Name

    -

    mps_stack_scan_ambig

    +

    mps_stack_scan_ambig

    -

    Summary

    +

    Summary

    -

    A scanning function for ambiguous scanning of thread states.

    +

    A scanning function for ambiguous scanning of thread states.

    -

    Associated Protocols

    +

    Associated Protocols

    -

    Root.

    +

    Root.

    -

    Syntax

    +

    Syntax

    -

    mps_res_t mps_stack_scan_ambig(mps_ss_t scan_state, mps_thr_t thread, void *stack_bottom, size_t ignore)

    +

    mps_res_t mps_stack_scan_ambig(mps_ss_t scan_state, mps_thr_t thread, void *stack_bottom, size_t ignore)

    -

    Arguments

    +

    Arguments

    -

    scan_state a scan state

    +

    scan_state a scan state

    -

    thread the thread

    +

    thread the thread

    -

    stack_bottom a pointer to the bottom of the stack

    +

    stack_bottom a pointer to the bottom of the stack

    -

    ignore ignored

    +

    ignore ignored

    -

    Returned Values

    +

    Returned Values

    -

    A result code.

    +

    A result code.

    -

    Resources

    +

    Resources

    -

    mps.h

    +

    mps.h

    -

    Description

    +

    Description

    -

    This is a root scanning function of type mps_reg_scan_t. It will scan allinteger registers and everything on the stack of the thread given, and can therefore only be usedwith roots of rank MPS_RANK_AMBIG. It will only scan things at the given stack bottompointer or higher on the stack (that is, more recently added). References are assumed to berepresented as machine words, and are required to be 4-byte-aligned; unaligned values are ignored.

    +

    This is a root scanning function of type mps_reg_scan_t. It will scan allinteger registers and everything on the stack of the thread given, and can therefore only be usedwith roots of rank MPS_RANK_AMBIG. It will only scan things at the given stack bottompointer or higher on the stack (that is, more recently added). References are assumed to berepresented as machine words, and are required to be 4-byte-aligned; unaligned values are ignored.

    -

    Clients don't call this function, it is used as an argument of mps_root_create_reg.

    +

    Clients don't call this function, it is used as an argument of mps_root_create_reg.

    -

    Example

    +

    Example

     typedef struct {
@@ -9224,265 +10186,295 @@ void InitThread(ThreadLocals *thr)
    -

    See Also

    +

    See Also

    -

    mps_reg_scan_t, mps_root_create_reg

    +

    +mps_reg_scan_t, -

    Notes

    +mps_root_create_reg

    -

    The MPS provides this function because it's hard to write (it's OS- andarchitecture-dependent and possibly compiler-dependent).

    +

    Notes

    -

    function mps_telemetry_control

    +

    The MPS provides this function because it's hard to write (it's OS- andarchitecture-dependent and possibly compiler-dependent).

    -

    Name

    +

    function mps_telemetry_control

    -

    mps_telemetry_control

    +

    Name

    -

    Summary

    +

    mps_telemetry_control

    -

    This function is used to read and change the filters on the telemetry stream.

    +

    Summary

    -

    Associated Protocols

    +

    This function is used to read and change the filters on the telemetry stream.

    -

    Telemetry.

    +

    Associated Protocols

    -

    Syntax

    +

    Telemetry.

    -

    mps_word_t mps_telemetry_control(mps_word_t reset_mask, mps_word_t flip_mask);

    +

    Syntax

    -

    Arguments

    +

    mps_word_t mps_telemetry_control(mps_word_t reset_mask, mps_word_t flip_mask);

    -

    reset_mask is a bit mask indicating the bits that should be reset, regardless of previousvalue.

    -

    flip_mask is a bit mask indicating the bits whose value should be flipped after theresetting.

    +

    Arguments

    +

    reset_mask is a bit mask indicating the bits that should be reset, regardless of previousvalue.

    -

    Returned Values

    +

    flip_mask is a bit mask indicating the bits whose value should be flipped after theresetting.

    -

    The function returns the previous value of the telemetry filter control.

    +

    Returned Values

    -

    Description

    +

    The function returns the previous value of the telemetry filter control.

    -

    This function is used to read and change the filters on the telemetry stream. It isgenerally for use by developers.

    -

    The parameters reset_mask and flip_mask allow specifying any binary operation on the filtercontrol. To use this function for typical operations, the parameters should be set as follows:

    +

    Description

    -

    Operation reset_mask flip_mask

    +

    This function is used to read and change the filters on the telemetry stream. It isgenerally for use by developers.

    -

    set(M) M M

    +

    The parameters reset_mask and flip_mask allow specifying any binary operation on the filtercontrol. To use this function for typical operations, the parameters should be set as follows:

    -

    reset(M) M 0

    +

    Operation reset_mask flip_mask

    -

    flip(M) 0 M

    +

    set(M) M M

    -

    read() 0 0

    +

    reset(M) M 0

    -

    The significance of the bits is liable to change, but the current values (number the leastsignificant bit as zero) are:

    +

    flip(M) 0 M

    -

    0 -- per space or arena

    +

    read() 0 0

    -

    1 -- per pool

    +

    The significance of the bits is liable to change, but the current values (number the leastsignificant bit as zero) are:

    -

    2 -- per trace or scan

    +

    0 -- per space or arena

    -

    3 -- per page (segment)

    +

    1 -- per pool

    -

    4 -- per reference or fix

    +

    2 -- per trace or scan

    -

    5 -- per allocation or object

    +

    3 -- per page (segment)

    -

    6 -- user events (e.g., mps_telemetry_intern)

    +

    4 -- per reference or fix

    +

    5 -- per allocation or object

    -

    Example

    +

    6 -- user events (e.g., mps_telemetry_intern)

    -

    See Also

    +

    Example

    -

    mps_lib_telemetry_control

    +

    See Also

    -

    function mps_telemetry_flush

    +

    +mps_lib_telemetry_control

    -

    Name

    -

    mps_telemetry_flush

    +

    function mps_telemetry_flush

    -

    Summary

    +

    Name

    -

    This function is used to flush the internal event buffers.

    +

    mps_telemetry_flush

    -

    Associated Protocols

    +

    Summary

    -

    Telemetry.

    +

    This function is used to flush the internal event buffers.

    -

    Syntax

    +

    Associated Protocols

    -

    void mps_telemetry_flush(void);

    +

    Telemetry.

    -

    Resources

    +

    Syntax

    -

    mps.h

    +

    void mps_telemetry_flush(void);

    -

    Description

    +

    Resources

    -

    This function is used to flush the internal event buffers into the event stream. Thisfunction also calls mps_lib_io_flush on the event stream itself. This ensures that even the latestevents are now properly recorded, should the application terminate (uncontrollably as a result of abug, for example) or some interactive tool require access to the event data. You could even trycalling this from a debugger after a problem.

    +

    mps.h

    -

    Example

    +

    Description

    -

    mps_telemetry_flush();

    +

    This function is used to flush the internal event buffers into the event stream. Thisfunction also calls mps_lib_io_flush on the event stream itself. This ensures that even the latestevents are now properly recorded, should the application terminate (uncontrollably as a result of abug, for example) or some interactive tool require access to the event data. You could even trycalling this from a debugger after a problem.

    -

    See Also

    +

    Example

    -

    mps_lib_io_flush

    +

    mps_telemetry_flush();

    -

    function mps_telemetry_intern

    +

    See Also

    +

    -

    Name

    +mps_lib_io_flush

    -

    mps_telemetry_intern

    +

    function mps_telemetry_intern

    -

    Summary

    -

    This function registers a string with the MPS, and receives a unique identifier in return.This identifier is suitable for use with mps_telemetry_label.

    +

    Name

    +

    mps_telemetry_intern

    -

    Associated Protocols

    -

    Telemetry

    +

    Summary

    +

    This function registers a string with the MPS, and receives a unique identifier in return.This identifier is suitable for use with mps_telemetry_label.

    -

    Type

    -

    mps_word_t mps_telemetry_intern(char *)

    +

    Associated Protocols

    +

    Telemetry

    -

    Arguments

    -

    The function receives a name as a nul-terminated string in the usual C way. The string'slength should not exceed 256 characters, including nul terminating character. In appropriatevarieties this restriction is checked and will cause the MPS to issue an ASSERT. So don't do it.

    +

    Type

    +

    mps_word_t mps_telemetry_intern(char *)

    -

    Returned Values

    -

    The function returns a unique idenifier that may be used to represent the string in future.

    +

    Arguments

    +

    The function receives a name as a nul-terminated string in the usual C way. The string'slength should not exceed 256 characters, including nul terminating character. In appropriatevarieties this restriction is checked and will cause the MPS to issue an ASSERT. So don't do it.

    -

    Description

    -

    The intention of this function is to provide an immediate identifier that can be used toconcisely represent a string for the purposes of mps_telemetry_label. Note that the appropriatesettings must be made to the telemetry filter (via mps_telemetry_control) before this function isinvoked; the associate event is of the user kind.

    +

    Returned Values

    +

    The function returns a unique idenifier that may be used to represent the string in future.

    -

    Error Handling

    -

    The string's length should not exceed 256 characters, including nul terminating character.This will cause the MPS to issue an ASSERT in appropriate varieties.

    +

    Description

    +

    The intention of this function is to provide an immediate +identifier that can be used toconcisely represent a string for the +purposes of mps_telemetry_label. Note that +the appropriatesettings must be made to the telemetry filter (via +mps_telemetry_control) before +this function is invoked; the associate event is of the user kind.

    -

    See Also

    -

    mps_telemetry_label

    +

    Error Handling

    -

    mps_telemetry_control

    +

    The string's length should not exceed 256 characters, including nul terminating character.This will cause the MPS to issue an ASSERT in appropriate varieties.

    -

    function mps_telemetry_label

    +

    See Also

    +

    -

    Name

    +mps_telemetry_label

    -

    mps_telemetry_label

    +

    +mps_telemetry_control

    -

    Summary

    -

    This function associates an identifier returned from mps_telemetry_intern, and hence astring, with an address, in the telemetry stream.

    +

    function mps_telemetry_label

    -

    Associated Protocols

    +

    Name

    -

    telemetry

    +

    mps_telemetry_label

    -

    Type

    +

    Summary

    -

    void mps_telemetry_label(mps_addr_t, mps_word_t);

    +

    This function associates an identifier returned from mps_telemetry_intern, and hence astring, with an address, in the telemetry stream.

    -

    Arguments

    +

    Associated Protocols

    -

    The function receives an address and an identifier. The identifier should be one returned by mps_telemetry_intern in the same session.

    +

    telemetry

    -

    Description

    +

    Type

    -

    This function is intended to associate the address with an identifier in the telemetrystream. Note that the user kind must be set in the telemetry filter.

    +

    void mps_telemetry_label(mps_addr_t, mps_word_t);

    -

    Example

    +

    Arguments

    -

    Typical uses include:

    +

    The function receives an address and an identifier. The identifier should be one returned by mps_telemetry_intern in the same session.

    -

    - Label pools with a human-meaningful name;

    -

    - Label allocated objects with their type or class.

    +

    Description

    +

    This function is intended to associate the address with an identifier in the telemetrystream. Note that the user kind must be set in the telemetry filter.

    -

    See Also

    -

    mps_telemetry_intern, mps_telemetry_control, mps_thr_t

    +

    Example

    +

    Typical uses include:

    -

    Name

    +

    - Label pools with a human-meaningful name;

    -

    mps_thr_t

    +

    - Label allocated objects with their type or class.

    -

    Summary

    +

    See Also

    -

    mps_thr_t is the type of thread records registered with the MPS.

    +

    +mps_telemetry_intern, -

    Associated Protocols

    +mps_telemetry_control, -

    Threads.

    +mps_thr_t

    -

    Type

    +

    Name

    -

    typedef mps_thr_s *mps_thr_t;

    +

    mps_thr_t

    -

    Resources

    +

    Summary

    -

    mps.h

    +

    mps_thr_t is the type of thread records registered with the MPS.

    -

    Description

    +

    Associated Protocols

    -

    An object of the opaque type mps_thr_t is a thread registration. In a multi-threadedenvironment where incremental garbage collection is used, threads must be registered with the MPS sothat the MPS can examine their state.

    +

    Threads.

    -

    An object of type mps_thr_t is obtained using the thread registration function mps_thread_reg.

    +

    Type

    -

    Example

    +

    typedef mps_thr_s *mps_thr_t;

    + + +

    Resources

    + +

    mps.h

    + + +

    Description

    + +

    An object of the opaque type mps_thr_t is a thread registration. In a multi-threadedenvironment where incremental garbage collection is used, threads must be registered with the MPS sothat the MPS can examine their state.

    + +

    An object of type mps_thr_t is obtained using the thread registration function mps_thread_reg.

    + + +

    Example

       mps_thr_t this_thread;
@@ -9493,15 +10485,28 @@ void InitThread(ThreadLocals *thr)
    -

    See Also

    +

    See Also

    -

    mps_reg_t, mps_thread_reg, mps_thread_dereg, mps_reg_scan_t, mps_root_create_reg, mps_stack_scan_ambig

    +

    + +mps_reg_t, + +mps_thread_reg, + +mps_thread_dereg, + +mps_reg_scan_t, + +mps_root_create_reg, + +mps_stack_scan_ambig

    -

    A. References

    +

    A. References

    -

    B. Document History

    +

    B. Document History

    @@ -9535,14 +10540,24 @@ void InitThread(ThreadLocals *thr) + + + + + + + + + +
    2002-06-20NBQuite a bit of proof-reading, to insert missing spaces. Also reformatted for easier editing, including the "See Also" sections.

    C. Copyright and License

    -

    This document is copyright © 1997-2002 Ravenbrook Limited. All rights reserved. This is an open source license. Contact Ravenbrook for commercial licensing options.

    +

    This document is copyright © 1997-2002 Ravenbrook Limited. All rights reserved. This is an open source license. Contact Ravenbrook for commercial licensing options.

    -

    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

    +

    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

      @@ -9554,13 +10569,13 @@ void InitThread(ThreadLocals *thr)
    -

    This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement, are disclaimed. In no event shall the copyright holders and contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

    +

    This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement, are disclaimed. In no event shall the copyright holders and contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

    -

    $Id$

    +

    $Id$

    Ravenbrook / From 59360f67ff1c808eab4de8f4ff5d7e75a63d6666 Mon Sep 17 00:00:00 2001 From: Nick Barnes Date: Thu, 20 Jun 2002 17:11:31 +0100 Subject: [PATCH 05/11] Ams now uses (!nonwhite & !nongrey) for grey. see analysis of job000535. Copied from Perforce Change: 30349 ServerID: perforce.ravenbrook.com --- mps/code/poolams.c | 37 +++++++++++++++++++++++++++---------- mps/code/poolams.h | 14 +++++++------- 2 files changed, 34 insertions(+), 17 deletions(-) diff --git a/mps/code/poolams.c b/mps/code/poolams.c index b8542425954..b8650af428e 100644 --- a/mps/code/poolams.c +++ b/mps/code/poolams.c @@ -1451,11 +1451,28 @@ static Res AMSFix(Pool pool, ScanState ss, Seg seg, Ref *refIO) /* AMSBlacken -- the pool class blackening method * - * Turn all grey objects black. - */ + * Turn all grey objects black. */ + + +static Res amsBlackenObject(Seg seg, Index i, Addr p, Addr next, void *clos) +{ + AVER(clos == NULL); + /* Do what amsScanObject does, minus the scanning. */ + if (AMS_IS_GREY(seg, i)) { + Index j = AMS_ADDR_INDEX(seg, next); + AVER(!AMS_IS_INVALID_COLOUR(seg, i)); + AMS_GREY_BLACKEN(seg, i); + if (i+1 < j) + AMS_RANGE_BLACKEN(seg, i+1, j); + } + return ResOK; +} + + static void AMSBlacken(Pool pool, TraceSet traceSet, Seg seg) { AMS ams; + Res res; AVERT(Pool, pool); ams = Pool2AMS(pool); @@ -1463,14 +1480,14 @@ static void AMSBlacken(Pool pool, TraceSet traceSet, Seg seg) AVERT(TraceSet, traceSet); AVERT(Seg, seg); - /* If it's white for any of these traces, remove the greyness from tables. */ + /* If it's white for any of these traces, turn grey to black without scanning. */ if (TraceSetInter(traceSet, SegWhite(seg)) != TraceSetEMPTY) { AMSSeg amsseg = Seg2AMSSeg(seg); AVERT(AMSSeg, amsseg); AVER(amsseg->marksChanged); /* there must be something grey */ amsseg->marksChanged = FALSE; - /* This will turn grey->black, and not affect black or white. */ - BTSetRange(amsseg->nongreyTable, 0, amsseg->grains); + res = amsIterate(seg, amsBlackenObject, NULL); + AVER(res == ResOK); } } @@ -1685,18 +1702,18 @@ Bool AMSCheck(AMS ams) * Copyright (C) 2001-2002 Ravenbrook Limited . * All rights reserved. This is an open source license. Contact * Ravenbrook for commercial licensing options. - * + * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are * met: - * + * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. - * + * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. - * + * * 3. Redistributions in any form must be accompanied by information on how * to obtain complete source code for this software and any accompanying * software that uses this software. The source code must either be @@ -1707,7 +1724,7 @@ Bool AMSCheck(AMS ams) * include source code for modules or files that typically accompany the * major components of the operating system on which the executable file * runs. - * + * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR diff --git a/mps/code/poolams.h b/mps/code/poolams.h index 7a4c27bfd59..e2d34b178a5 100644 --- a/mps/code/poolams.h +++ b/mps/code/poolams.h @@ -110,17 +110,17 @@ typedef struct AMSSegStruct { (!AMS_IS_GREY(seg, index) && !AMS_IS_WHITE(seg, index)) #define AMS_IS_INVALID_COLOUR(seg, index) \ - (AMS_IS_GREY(seg, index) && AMS_IS_WHITE(seg, index)) + (AMS_IS_GREY(seg, index) && !AMS_IS_WHITE(seg, index)) #define AMS_WHITE_GREYEN(seg, index) \ BEGIN \ - BTSet(Seg2AMSSeg(seg)->nonwhiteTable, index); \ BTRes(Seg2AMSSeg(seg)->nongreyTable, index); \ END #define AMS_GREY_BLACKEN(seg, index) \ BEGIN \ BTSet(Seg2AMSSeg(seg)->nongreyTable, index); \ + BTSet(Seg2AMSSeg(seg)->nonwhiteTable, index); \ END #define AMS_WHITE_BLACKEN(seg, index) \ @@ -200,18 +200,18 @@ extern AMSPoolClass AMSDebugPoolClassGet(void); * Copyright (C) 2001-2002 Ravenbrook Limited . * All rights reserved. This is an open source license. Contact * Ravenbrook for commercial licensing options. - * + * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are * met: - * + * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. - * + * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. - * + * * 3. Redistributions in any form must be accompanied by information on how * to obtain complete source code for this software and any accompanying * software that uses this software. The source code must either be @@ -222,7 +222,7 @@ extern AMSPoolClass AMSDebugPoolClassGet(void); * include source code for modules or files that typically accompany the * major components of the operating system on which the executable file * runs. - * + * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR From 91f3758a6a8f239c9c0776787a96256ea9fef610 Mon Sep 17 00:00:00 2001 From: Nick Barnes Date: Thu, 20 Jun 2002 17:14:58 +0100 Subject: [PATCH 06/11] Readme for 1.100.1 Copied from Perforce Change: 30350 ServerID: perforce.ravenbrook.com --- mps/readme.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/mps/readme.txt b/mps/readme.txt index 21ed02f542b..e98df25545a 100644 --- a/mps/readme.txt +++ b/mps/readme.txt @@ -54,12 +54,12 @@ The MPS Kit is a complete set of sources and documentation to enable third parties to use, modify, and adapt the MPS. For Windows, the kit is distributed as the self-extracting archive -"mps-kit-1.100.0.exe", and also as the ZIP archive -"mps-kit-1.100.0.zip", which may be unpacked using WinZip. +"mps-kit-1.100.1.exe", and also as the ZIP archive +"mps-kit-1.100.1.zip", which may be unpacked using WinZip. For Unix and Mac OS X, the integration kit is distributed as the tarball -"mps-kit-1.100.0.tar.gz". Unpack it using the command "gunzip -c -mps-kit-1.100.0.tar.gz | tar xvf -", or by dropping the file onto +"mps-kit-1.100.1.tar.gz". Unpack it using the command "gunzip -c +mps-kit-1.100.1.tar.gz | tar xvf -", or by dropping the file onto StuffIt Expander under Mac OS X. The top-level file "index.html" in the sources indexes many other files, From babf8fa85cecd1ec06a0440455be417c544db15c Mon Sep 17 00:00:00 2001 From: Nick Barnes Date: Fri, 21 Jun 2002 15:06:03 +0100 Subject: [PATCH 07/11] Remove mpstd.h Copied from Perforce Change: 30381 ServerID: perforce.ravenbrook.com --- mps/code/mpstd.h | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/mps/code/mpstd.h b/mps/code/mpstd.h index 4043b6716d7..7884fc016f8 100644 --- a/mps/code/mpstd.h +++ b/mps/code/mpstd.h @@ -259,7 +259,6 @@ #define MPS_ARCH_AL #define MPS_BUILD_GC #define MPS_T_WORD unsigned long -#define MPS_T_SHORT unsigned #define MPS_WORD_WIDTH 64 #define MPS_WORD_SHIFT 6 #define MPS_PF_ALIGN 8 @@ -274,7 +273,6 @@ #define MPS_ARCH_AL #define MPS_BUILD_CC #define MPS_T_WORD unsigned long -#define MPS_T_SHORT unsigned #define MPS_WORD_WIDTH 64 #define MPS_WORD_SHIFT 6 #define MPS_PF_ALIGN 8 @@ -338,18 +336,18 @@ * Copyright (C) 2001-2002 Ravenbrook Limited . * All rights reserved. This is an open source license. Contact * Ravenbrook for commercial licensing options. - * + * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are * met: - * + * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. - * + * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. - * + * * 3. Redistributions in any form must be accompanied by information on how * to obtain complete source code for this software and any accompanying * software that uses this software. The source code must either be @@ -360,7 +358,7 @@ * include source code for modules or files that typically accompany the * major components of the operating system on which the executable file * runs. - * + * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR From 3ac0eed0e5fee3ed28cbe877e5cf0dc97b3423ea Mon Sep 17 00:00:00 2001 From: Nick Barnes Date: Fri, 21 Jun 2002 15:06:54 +0100 Subject: [PATCH 08/11] Removed obsolete symbols and fixed a bit of formatting. Copied from Perforce Change: 30382 ServerID: perforce.ravenbrook.com --- mps/manual/reference/index.html | 694 +------------------------------- 1 file changed, 18 insertions(+), 676 deletions(-) diff --git a/mps/manual/reference/index.html b/mps/manual/reference/index.html index c97226fe95e..1087452fe71 100644 --- a/mps/manual/reference/index.html +++ b/mps/manual/reference/index.html @@ -66,7 +66,6 @@

    MPS_ARCH_AL

    @@ -276,70 +268,6 @@ typedef struct RegisterFile { 1997-05-01

    -

    MPS_ARCH_M6

    - - -

    Name

    - -

    MPS_ARCH_M6

    - - -

    Summary

    - -

    MPS_ARCH_M6 is a C -preprocessor macro that indicates, if defined, that the target -processor architecture of the compilation is a member of the Motorola -68000 family. It is defined, if appropriate, by "mpstd.h".

    - - -

    Associated Protocols

    - -

    None.

    - - -

    Resources

    - -

    msptd.h.

    - - -

    Description

    - -

    See summary.

    - - -

    Example

    - -
    -#ifdef MPS_ARCH_M6
-
-typedef struct RegisterFile {
-  unsigned long d[8];
-  unsigned long a[8];
-  unsigned long usp, msp, isp, pc, sr;
-} RegisterFile;
-
-#endif /* MPS_ARCH_M6 */
-
    - - -

    Error Handling

    - -

    Not applicable.

    - - -

    See Also

    - -

    - -MPS_PF_*, - -MPS_OS_*, - -MPS_BUILD_*, - -MPS_ARCH_*

    - -

    function mps_fix

    @@ -1302,9 +1230,7 @@ the MPS.

    href="#mps_root_create_table">mps_root_create_table    , mps_root_create_table_masked, - -MPS_RM_PROT_INNER

    +href="#mps_root_create_table_masked">mps_root_create_table_masked    .

    Notes

    @@ -1335,97 +1261,6 @@ root. Lots of OSes can't cope with writing to protected pages. So we'll need to document that caveat too. drj 1998-05-20

    -

    MPS_RM_PROT_INNER

    - - -

    Name

    - -

    MPS_RM_PROT_INNER

    - - -

    Summary

    - -

    MPS_RM_PROT_INNER is -a constant used in root mode arguments to indicate partially -protectable roots.

    - - -

    Associated Protocols

    - -

    Root.

    - - -

    Type

    - -

    Integral constant.

    - - -

    Resources

    - -

    mps.h

    - - -

    Description

    - -

    MPS_RM_PROT_INNER is -a preprocessor macro defining a constant that can be OR'ed with other -MPS_RM_* constants, and passed as the root mode argument -to certain root creation functions (mps_root_create_fmt, mps_root_create_table, -mps_root_create_table_masked).

    - -

    Passing MPS_RM_PROT_INNER means that the -MPS may place a hardware write barrier on any pages which are entirely -covered by the root. Format methods and any scanning function (except -for the one for this root) may not write data in this root. They may -read it.

    - - -

    Example

    - -
    -res = mps_root_create_table(&mmRoot, arena, mps_rank_exact(),
-                            MPS_RM_PROT | MPS_RM_PROT_INNER,
-                            (mps_addr_t)&Objects, rootCOUNT);
-
    - - -

    See Also

    - -

    - -mps_root_create_fmt, - -mps_root_create_table, - -mps_root_create_table_masked, - -MPS_RM_PROT

    - - -

    Notes

    - -

    To specify MPS_RM_PROT_INNER, you must also -specify MPS_RM_PROT. The -meaning of MPS_RM_PROT is -overridden by MPS_RM_PROT_INNER.

    - - -

    Internal Notes

    - -

    Future meaning: The MPS may place a hardware read and/or write -barrier on any pages which are entirely covered by the root. Format -methods and scanning functions (except for the one for this root) may -not read or write data in this root.

    - -

    function mps_sac_alloc

    @@ -4530,209 +4365,6 @@ href="#mps_arena_spare_commit_limit">mps_arena_spare_commit_limit

    None.

    -

    function mps_assert_default

    - - -

    Name

    - -

    mps_assert_default

    - - -

    Summary

    - -

    mps_assert_default returns a pointer to the default assertion handler.

    - - -

    Associated Protocols

    - -

    Assertion.

    - - -

    Syntax

    - - -

    Arguments

    - -

    None.

    - - -

    Initial/Default Values

    - -

    None.

    - - -

    Returned Values

    - -

    A pointer to the default assertion handler.

    - - -

    Resources

    - -

    mps.h

    - - -

    Description

    - -

    mps_assert_default returns a pointer to the default assertion handler. It is intended tobe used in conjunction with mps_assert_install.

    - -

    You may also call the default assertion handler directly, in which case the first, second,and third arguments must be non-NULL pointers to zero-terminated strings.

    - - -

    Example

    - - -

    Error Handling

    - -

    Can't fail.

    - - -

    See Also

    - -

    - -mps_assert_install

    - -

    "Assertion Protocol"

    - - -

    Notes

    - -

    None.

    - - -

    function mps_assert_install

    - - -

    Name

    - -

    mps_assert_install

    - - -

    Summary

    - -

    mps_assert_install installs the specified assertion handler as the current assertionhandler.

    - - -

    Associated Protocols

    - -

    Assertion.

    - - -

    Syntax

    - -

    mps_assert_t mps_assert_install(void my_assertion_handler);

    - - -

    Arguments

    - -

    my_assertion_handler the handler that you want to install

    - - -

    Returned Values

    - -

    A pointer to the previously installed assertion handler.

    - - -

    Resources

    - -

    mps.h

    - - -

    Description

    - -

    mps_assert_install installs the specified assertion handler as the current assertionhandler. It returns a pointer to the previously installed assertion handler. Note that there is oneMPS assertion handler for the entire process (in particular it is not per arena).

    - - -

    Example

    - -
    -mps_assert_t old_handler;
-
-void my_assertion_handler(const char *cond,
-const char *id,
-const char *file, unsigned int line)
-{
-  fatal_error_dialog("The Memory Pool System detected an inconsistency"
-                     "in file %s at line%u: %s\n", file, line, cond);
-  old_handler(cond, id, file, line);
-  abort();
-  NOTREACHED;
-}
-
-/* ... */
-
-  /* install the handler: */
-  old_handler = mps_assert_install(my_assertion_handler);
-
-  /* ... use the MPS ... */
-
-  /* restore the old handler */
-  (void) mps_assert_install(old_handler);
-
    - - -

    Error Handling

    - - -

    See Also

    - -

    - -mps_assert_default

    - - -

    Notes

    - -

    None.

    - - -

    type mps_assert_t

    - - -

    Name

    - -

    mps_assert_t

    - - -

    Summary

    - -

    mps_assert_t is the type of assertion handlers in the MPS.

    - - -

    Associated Protocols

    - -

    Assertion.

    - - -

    Syntax

    - -

    typedef void (*mps_assert_t)(const char *, const char *, const char *, unsigned); -

    - - -

    Resources

    - -

    mps.h

    - - -

    Description

    - -

    mps_assert_t is the type of assertion handlers in the MPS.

    - -

    - - -

    Example

    - - -

    See Also

    - - -

    Notes

    - -

    None.

    - -

    function mps_bool_t

    @@ -7203,198 +6835,6 @@ mpsliban.c

    href="#mps_telemetry_control">mps_telemetry_control

    -

    mps_message_collection_stats_condemned_size

    - - -

    Name

    - -

    mps_message_collection_stats_condemned_size

    - - -

    Summary

    - -

    mps_message_collection_stats_condemned_size returns the "condemned size" property of thespecified message in the specified arena.

    - - -

    Associated Protocols

    - -

    Message, GC.

    - - -

    Syntax

    - -

    size_t mps_message_collection_stats_condemned_size(mps_message_t message)

    - - -

    Arguments

    - -

    message -- a message of a message type that supports this method

    - - -

    Initial/Default Values

    - -

    Not applicable.

    - - -

    Returned Values

    - -

    An approximate size for the set of objects condemned in the collection that generated themessage.

    - - -

    Resources

    - -

    Not applicable.

    - - -

    Description

    - -

    Currently, the only type of message that supports this property, is mps_message_type_collection_stats, which is generated whenever a garbage collection completes. Thismethod returns an approximation to the size of the set of objects that were condemned in thatcollection.

    - - -

    Example

    - - -

    Error Handling

    - - -

    See Also

    - -

    - -mps_message_*

    - - -

    Notes

    - - -

    mps_message_collection_stats_live_size

    - - -

    Name

    - -

    mps_message_collection_stats_live_size

    - - -

    Summary

    - -

    mps_message_collection_stats_live_size returns the "live size" property of the specifiedmessage in the specified arena.

    - - -

    Associated Protocols

    - -

    Message, GC.

    - - -

    Syntax

    - -

    size_t mps_message_collection_stats_live_size(mps_message_t message)

    - - -

    Arguments

    - -

    message -- a message of a message type that supports this method

    - - -

    Initial/Default Values

    - -

    Not applicable.

    - - -

    Returned Values

    - -

    The total size of the condemned objects that survived the collection that generated themessage.

    - - -

    Resources

    - -

    Not applicable.

    - - -

    Description

    - -

    Currently, the only type of message that supports this property, is mps_message_type_collection_stats, which is generated whenever a garbage collection completes. Thismethod returns the size of the set of objects that were condemned in that collection, but survived.

    - - -

    Example

    - - -

    Error Handling

    - - -

    See Also

    - -

    - -mps_message_*

    - - -

    Notes

    - - -

    mps_message_sollection_stats_not_condemned_size

    - - -

    Name

    - -

    mps_message_collection_stats_not_condemned_size

    - - -

    Summary

    - -

    mps_message_collection_stats_not_condemned_size returns the "not condemned size" propertyof the specified message in the specified arena.

    - - -

    Associated Protocols

    - -

    Message, GC.

    - - -

    Syntax

    - -

    size_t mps_message_collection_stats_not_condemned_size(mps_message_t message)

    - - -

    Arguments

    - -

    message -- a message of a message type that supports this method

    - - -

    Initial/Default Values

    - -

    Not applicable.

    - - -

    Returned Values

    - -

    An approximate size for the set of objects that were in collected pools, but were notcondemned in the collection that generated the message.

    - - -

    Resources

    - -

    Not applicable.

    - - -

    Description

    - -

    Currently, the only type of message that supports this property, is mps_message_type_collection_stats, which is generated whenever a garbage collection completes. Thismethod returns an approximation to the size of the set of objects that were in collected pools, butwere not condemned in that collection.

    - - -

    Example

    - - -

    Error Handling

    - - -

    See Also

    - -

    - -mps_message_*

    - - -

    Notes

    - -

    function mps_message_discard

    @@ -7669,7 +7109,7 @@ is used to indicate that the client has no further use for the specified message

    Name

    -

    mps_message_gc_not_condemned_size

    +

    mps_message_gc_not_condemned_size

    Summary

    @@ -8035,107 +7475,6 @@ is used to indicate that the client has no further use for the specified message mps_message_*

    -

    mps_message_type_collection_stats

    - - -

    Name

    - -

    mps_message_type_collection_stats

    - - -

    Summary

    - -

    mps_message_type_collection_stats returns the type of garbage collection statistic messages.

    - - -

    Associated Protocols

    - -

    Message, gc.

    - - -

    Syntax

    - -

    mps_message_type_t mps_message_type_collection_stats()

    - - -

    Arguments

    - - -

    Initial/Default Values

    - -

    Not applicable.

    - - -

    Returned Values

    - -

    The type of garbage collection statistic messages.

    - - -

    Resources

    - -

    Not applicable.

    - - -

    Description

    - -

    mps_message_type_collection_stats returns the type of garbage collection statisticmessages. Garbage collection statistic messages are used by the MPS to give the client informationabout garbage collections that have occurred. Such information may be useful in analysing theclient's memory usage over time.

    - -

    The access methods specific to a message of this type are:

    - - - - -

    Example

    - -
    -{
-  mps_message_type_t type;
-
-  if(mps_message_queue_type(&type, arena)) {
-    if(type == mps_message_type_collection_stats()) {
-      size_t live, condemned, not_condemned;
-      mps_message_t message;
-      mps_bool_t got_message;
-      got_message = mps_message_get(&message, arena, type);
-      assert(got_message);
-      live = mps_message_collection_stats_live_size(message);
-      condemned = mps_message_collection_stats_condemned_size(message);
-      not_condemned = mps_message_collection_stats_not_condemned_size(message);
-      mps_message_discard(arena, message);
-      process_collection_stats(live, condemned, not_condemned);
-    } else {
-      unknown_message_type();
-    }
-  }
-}
-
    - - -

    Error Handling

    - -

    Cannot fail.

    - - -

    See Also

    - -

    - -mps_message_*.

    - -

    "Message Protocol", "GC Protocol"

    - - -

    Notes

    - -

    function mps_message_type_disable

    @@ -8524,15 +7863,14 @@ is used to indicate that the client has no further use for the specified message

    Error Handling

    -

    If a corrupted fencepost is found, an assert will fire. You can install an assert handlerusing mps_assert_install, but you'll probably want to look at the problem with adebugger instead.

    +

    If a corrupted fencepost is found, an assert will fire. You will +probably want to look at the problem with a debugger.

    See Also

    -mps_assert_install, - mps_class_*_debug

    @@ -8541,9 +7879,7 @@ is used to indicate that the client has no further use for the specified message

    Name

    -

    - mps_pool_debug_option_s -

    +

    mps_pool_debug_option_s

    Summary

    @@ -9196,8 +8532,6 @@ href="#mps_root_create_table">mps_root_create_table    , MPS_RM_PROT, -MPS_RM_PROT_INNER, - MPS_RM_CONST

    @@ -9404,8 +8738,6 @@ href="#mps_root_create_table_masked">mps_root_create_table_masked    , MPS_RM_PROT, -MPS_RM_PROT_INNER, - MPS_RM_CONST

    @@ -9507,8 +8839,6 @@ href="#mps_root_create_table">mps_root_create_table, MPS_RM_PROT, -MPS_RM_PROT_INNER, - MPS_RM_CONST

    @@ -10442,6 +9772,8 @@ href="#mps_telemetry_control">mps_telemetry_control, mps_thr_t

    +

    type mps_thr_t

    +

    Name

    mps_thr_t

    @@ -10550,6 +9882,16 @@ href="#mps_stack_scan_ambig">mps_stack_scan_ambig

    + + + 2002-06-21 + + NB + + Removed obsolete symbols. + + + From 7fa596997a957030fa10225fad55e2487e06bf65 Mon Sep 17 00:00:00 2001 From: Nick Barnes Date: Fri, 21 Jun 2002 15:24:14 +0100 Subject: [PATCH 09/11] Un-p4dti these documents. Copied from Perforce Change: 30383 ServerID: perforce.ravenbrook.com --- mps/design/index.html | 31 +++++++++++-------------------- mps/manual/index.html | 12 +++++++++++- 2 files changed, 22 insertions(+), 21 deletions(-) diff --git a/mps/design/index.html b/mps/design/index.html index baaf17d392c..f3b6c0b1d49 100644 --- a/mps/design/index.html +++ b/mps/design/index.html @@ -44,10 +44,7 @@

    This is not a complete set of design documents for the MPS. We have many hundreds of documents, many of which contain confidential information. We are sorting through these and will include more as time goes on. We have tried to select the key documents for inclusion in the open source release, by including those documents referenced by the source code.

    -

    This document will be modified as the product is developed. Design -documents will appear here according to the design document procedure -[RB -2000-10-05].

    +

    This document will be modified as the product is developed.

    The readership of this document is the product developers.

    @@ -471,22 +468,6 @@ documents will appear here according to the design document procedure

    A. References

    - - - - - - - - - - -
    [RB 2000-10-05] - "P4DTI Project Design Document Procedure"; - Richard Brooksby; - Ravenbrook Limited; - 2000-10-05. -

    B. Document History

    @@ -513,6 +494,16 @@ documents will appear here according to the design document procedure + + + 2002-06-21 + + NB + + Remove P4DTI reference, which doesn't fit here. Maybe one day we'll have a corporate design document procedure. + + + diff --git a/mps/manual/index.html b/mps/manual/index.html index ea60c29d0c4..eadce5128e9 100644 --- a/mps/manual/index.html +++ b/mps/manual/index.html @@ -39,7 +39,7 @@

    1. Introduction

    -

    This is the catalogue of manuals for the Perforce Defect Tracking Integration product.

    +

    This is the catalogue of manuals for the Memory Pool System product.

    This document will be modified as the product is developed.

    @@ -102,6 +102,16 @@ + + + 2002-06-21 + + NB + + This isn't the P4DTI! + + + From caaee3ce3d6862e943f9896004e8f350bb7aec96 Mon Sep 17 00:00:00 2001 From: Nick Barnes Date: Fri, 21 Jun 2002 15:27:52 +0100 Subject: [PATCH 10/11] Include a list of undocumented symbols in the reference manual. Copied from Perforce Change: 30384 ServerID: perforce.ravenbrook.com --- mps/manual/reference/index.html | 164 ++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) diff --git a/mps/manual/reference/index.html b/mps/manual/reference/index.html index 1087452fe71..57412aa0f8d 100644 --- a/mps/manual/reference/index.html +++ b/mps/manual/reference/index.html @@ -47,6 +47,8 @@
  • 3. Reference
    • +
  • 4. Undocumented Symbols
    • +
  • A. References
  • B. Document History
    • @@ -58,6 +60,14 @@

    1. Introduction

    +

    This is the reference manual for the Memory Pool System.

    + +

    This document is quite incomplete. At present it consists +simply of reference descriptions of a number of MPS symbols (section 3). Many MPS symbols are not described +here (see section 4 for a list). There are +also no overview or protocol-oriented sections.

    +

    2. Overview

    @@ -9835,6 +9845,160 @@ href="#mps_telemetry_control">mps_telemetry_control, href="#mps_stack_scan_ambig">mps_stack_scan_ambig

    +

    4. Undocumented Symbols

    + +

    The following MPS symbols are used or defined in MPS header files, +and intended for client use, but are not yet documented in this +reference manual.

    + +
    +mps_arena_t
+mps_pool_t
+mps_chain_t
+mps_root_t
+mps_ap_t
+mps_ld_t
+mps_ss_t
+mps_alloc_pattern_t
+mps_frame_t
+mps_word_t
+mps_shift_t
+mps_rm_t
+MPS_RES_OK
+MPS_RES_FAIL
+MPS_RES_RESOURCE
+MPS_RES_UNIMPL
+MPS_RES_IO
+MPS_RES_COMMIT_LIMIT
+mps_ap_s
+mps_sac_freelist_block_s
+mps_sac_s
+mps_ld_s
+mps_ss_s
+mps_fmt_fixed_s
+MPS_BEGIN
+MPS_END
+mps_arena_step
+mps_arena_destroy
+mps_arena_reserved
+mps_arena_has_addr
+mps_arena_extend
+mps_arena_retract
+mps_fmt_create_fixed
+mps_fmt_destroy
+mps_pool_create
+mps_pool_create_v
+mps_pool_destroy
+mps_gen_param_s
+mps_chain_create
+mps_chain_destroy
+mps_alloc_v
+mps_ap_create
+mps_ap_create_v
+mps_ap_destroy
+mps_reserve
+mps_commit
+mps_ap_fill
+mps_ap_fill_with_reservoir_permit
+mps_ap_trip
+MPS_SAC_ALLOC
+MPS_SAC_FREE
+mps_reservoir_limit_set
+mps_reservoir_limit
+mps_reservoir_available
+mps_reserve_with_reservoir_permit
+MPS_RESERVE_BLOCK
+MPS_RESERVE_WITH_RESERVOIRf_PERMIT_BLOCK
+mps_root_destroy
+mps_tramp_t
+mps_tramp
+mps_thread_reg
+mps_thread_dereg
+mps_ld_reset
+mps_ld_add
+mps_ld_merge
+mps_ld_isstale
+mps_collections
+mps_definalize
+mps_pool_check_free_space
+mps_lib_get_EOF
+mps_lib_stream_s
+mps_lib_get_stderr
+mps_lib_get_stdout
+mps_lib_fputc
+mps_lib_fputs
+mps_lib_assert_fail
+mps_clock_t
+mps_clock
+mps_class_amcz
+mps_class_ams
+mps_class_ams_debug
+mps_class_awl
+mps_class_lo
+mps_mv_free_size
+mps_mv_size
+mps_class_mv
+mps_class_mv_debug
+mps_mvt_free_size
+mps_mvt_size
+mps_mvff_free_size
+mps_mvff_size
+mps_class_mvff_debug
+mps_SEH_filter
+mps_SEH_handler
+mps_io_t
+mps_io_create
+mps_io_destroy
+mps_io_write
+mps_io_flush
+MPS_PF_STRING
+MPS_PF_ALIGN
+MPS_ARCH_60
+MPS_ARCH_I3
+MPS_ARCH_I4
+MPS_ARCH_M2
+MPS_ARCH_M4
+MPS_ARCH_PP
+MPS_ARCH_S8
+MPS_ARCH_S9
+MPS_BUILD_AC
+MPS_BUILD_CC
+MPS_BUILD_GC
+MPS_BUILD_LC
+MPS_BUILD_MV
+MPS_BUILD_MW
+MPS_BUILD_SC
+MPS_OS_FR
+MPS_OS_I5
+MPS_OS_IA
+MPS_OS_LI
+MPS_OS_O1
+MPS_OS_S7
+MPS_OS_SO
+MPS_OS_SU
+MPS_OS_W3
+MPS_OS_XC
+MPS_PF_FRI4GC
+MPS_PF_I5M2CC
+MPS_PF_IAM4CC
+MPS_PF_LII4GC
+MPS_PF_LIPPGC
+MPS_PF_O1ALCC
+MPS_PF_O1ALGC
+MPS_PF_S760AC
+MPS_PF_S760MW
+MPS_PF_S7PPAC
+MPS_PF_S7PPMW
+MPS_PF_SOS8GC
+MPS_PF_SOS9SC
+MPS_PF_SUS8GC
+MPS_PF_SUS8LC
+MPS_PF_W3ALMV
+MPS_PF_W3I3MV
+MPS_PF_W3PPMV
+MPS_PF_XCPPGC
+
    +

    A. References

    From 04f7858470d52d32b544da021d032604da1da20a Mon Sep 17 00:00:00 2001 From: Nick Barnes Date: Mon, 24 Jun 2002 11:08:39 +0100 Subject: [PATCH 11/11] Mv2 has become mvt; typo in mminfo index. Copied from Perforce Change: 30448 ServerID: perforce.ravenbrook.com --- mps/design/poolmvt/index.html | 798 +++++++++++++++++----------------- 1 file changed, 399 insertions(+), 399 deletions(-) diff --git a/mps/design/poolmvt/index.html b/mps/design/poolmvt/index.html index 070cc4fce5a..18b69590386 100644 --- a/mps/design/poolmvt/index.html +++ b/mps/design/poolmvt/index.html @@ -30,36 +30,36 @@ 
              THE DESIGN OF A NEW MANUAL-VARIABLE MEMORY POOL CLASS
-                           design.mps.poolmv2
+                           design.mps.poolmvt
                               draft design
                        P T Withington 1998-02-13
 
 
 INTRODUCTION:
 
-This is a second-generation design for a pool that manually manages 
-variable-sized objects. It is intended as a replacement for poolmv (except in 
-its control pool role) and poolepdl, and it is intended to satisfy the 
-requirements of the Dylan "misc" pool and the product malloc/new drop-in 
+This is a second-generation design for a pool that manually manages
+variable-sized objects. It is intended as a replacement for poolmv (except in
+its control pool role) and poolepdl, and it is intended to satisfy the
+requirements of the Dylan "misc" pool and the product malloc/new drop-in
 replacement.
 
-[This form should include these fields, rather than me having to create them 
+[This form should include these fields, rather than me having to create them
 "by hand"]
 
 .readership: MM developers
 
 .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) 
+.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)
 
 .hist.-1: Initial email discussion mail.ptw.1998-02-04.21-27(0), ff.
-.hist.0: Draft created 1998-02-13 by P. T. Withington from email RFC 
+.hist.0: Draft created 1998-02-13 by P. T. Withington from email RFC
 mail.ptw.1998-02-12.03-36, ff.
-.hist.1: Revised 1998-04-01 in response to email RFC 
+.hist.1: Revised 1998-04-01 in response to email RFC
 mail.ptw.1998-03-23.20-43(0), ff.
-.hist.2: Revised 1998-04-15 in response to email RFC 
+.hist.2: Revised 1998-04-15 in response to email RFC
 mail.ptw.1998-04-13.21-40(0), ff.
 .hist.3: Erroneously incremented version number
 .hist.4: Revised 1998-05-06 in response to review review.design.mps.poolmv2.2
@@ -68,55 +68,55 @@ mail.ptw.1998-04-13.21-40(0), ff.
 
 DEFINITIONS
 
-.def.alignment: Alignment is a constraint on an object's address, typically to 
+.def.alignment: Alignment is a constraint on an object's address, typically to
 be a power of 2 (see also, glossary.alignment )
 
 .def.bit-map: A bitmap is a boolean-valued vector (see also, glossary.bitmap ).
 
-.def.block: A block is a contiguous extent of memory.  In this document, block 
-is used to mean a contiguous extent of memory managed by the pool for the pool 
+.def.block: A block is a contiguous extent of memory.  In this document, block
+is used to mean a contiguous extent of memory managed by the pool for the pool
 client, typically a subset of a segment (compare with .def.segment).
 
-.def.cartesian-tree: A cartesian tree is a binary tree ordered by two keys 
+.def.cartesian-tree: A cartesian tree is a binary tree ordered by two keys
 (paper.stephenson83(0)).
 
-.def.crossing-map: A mechanism that supports finding the start of an object 
-from any address within the object, typically only required on untagged 
+.def.crossing-map: A mechanism that supports finding the start of an object
+from any address within the object, typically only required on untagged
 architectures (see also, glossary.crossing.map ).
 
-.def.footer: A block of descriptive information describing and immediately 
+.def.footer: A block of descriptive information describing and immediately
 following another block of memory (see also .def.header).
 
-.def.fragmentation: Fragmented memory is memory reserved to the program but not 
-usable by the program because of the arrangement of memory already in use (see 
+.def.fragmentation: Fragmented memory is memory reserved to the program but not
+usable by the program because of the arrangement of memory already in use (see
 also, glossary.fragmentation ).
 
-.def.header: A block of descriptive information describing and immediately 
+.def.header: A block of descriptive information describing and immediately
 preceding another block of memory (see also, glossary.in-band.header ).
 
-.def.in-band: From "in band signalling", when descriptive information about a 
-data structure is stored in the data structure itself (see also, 
+.def.in-band: From "in band signalling", when descriptive information about a
+data structure is stored in the data structure itself (see also,
 glossary.in-band.header ).
 
-.def.out-of-band: When descriptive information about a data structure is stored 
+.def.out-of-band: When descriptive information about a data structure is stored
 separately from the structure itself (see also, glossary.out-of-band.header ).
 
-.def.refcount: A refcount is a count of the number of users of an object (see 
+.def.refcount: A refcount is a count of the number of users of an object (see
 also, glossary.reference.count ).
 
-.def.segment: A segment is a contiguous extent of memory.  In this document, 
-segment is used to mean a contiguous extent of memory managed by the MPS arena 
-(design.mps.arena(1)) and subdivided by the pool to provide blocks (see 
+.def.segment: A segment is a contiguous extent of memory.  In this document,
+segment is used to mean a contiguous extent of memory managed by the MPS arena
+(design.mps.arena(1)) and subdivided by the pool to provide blocks (see
 .def.block) to its clients.
 
-.def.splay-tree: A splay tree is a self-adjusting binary tree (paper.st85(0), 
+.def.splay-tree: A splay tree is a self-adjusting binary tree (paper.st85(0),
 paper.sleator96(0)).
 
-.def.splinter: A splinter is a fragment of memory that is too small to be 
+.def.splinter: A splinter is a fragment of memory that is too small to be
 useful (see also, glossary.splinter )
 
-.def.subblock: A subblock is a contiguous extent of memory.  In this document, 
-subblock is used to mean a contiguous extent of memory manage by the client for 
+.def.subblock: A subblock is a contiguous extent of memory.  In this document,
+subblock is used to mean a contiguous extent of memory manage by the client for
 its own use, typically a subset of a block (compare with .def.block).
 
 
@@ -138,12 +138,12 @@ ABBREVIATIONS
 
 OVERVIEW:
 
-mv2 is intended to satisfy the requirements of the clients that need 
-manual-variable pools, improving on the performance of the existing 
-manual-variable pool implementations, and reducing the duplication of code that 
-currently exists. The expected clients of mv2 are: Dylan (currently for its 
-misc pool), EP (particularly the dl pool, but all pools other than the PS 
-object pool), and Product (initially the malloc/new pool, but also other manual 
+mvt is intended to satisfy the requirements of the clients that need
+manual-variable pools, improving on the performance of the existing
+manual-variable pool implementations, and reducing the duplication of code that
+currently exists. The expected clients of mvt are: Dylan (currently for its
+misc pool), EP (particularly the dl pool, but all pools other than the PS
+object pool), and Product (initially the malloc/new pool, but also other manual
 pool classes).
 
 
@@ -151,99 +151,99 @@ REQUIREMENTS:
 
 .req.cat: Requirements are categorized per guide.req(2).
 
-.req.risk: req.epcore(16) is known to be obsolete, but the revised document has 
+.req.risk: req.epcore(16) is known to be obsolete, but the revised document has
 not yet been accepted.
 
 
 Critical Requirements
 
-.req.fun.man-var: The pool class must support manual allocation and freeing of 
-variable-sized blocks (source: req.dylan.fun.misc.alloc, 
-req.epcore.fun.{dl,gen,tmp,stat,cache,trap}.{alloc,free}, 
+.req.fun.man-var: The pool class must support manual allocation and freeing of
+variable-sized blocks (source: req.dylan.fun.misc.alloc,
+req.epcore.fun.{dl,gen,tmp,stat,cache,trap}.{alloc,free},
 req.product.fun.{malloc,new,man.man}).
 
-.non-req.fun.gc: There is not a requirement that the pool class support 
-formatted objects, scanning, or collection objects; but it should not be 
+.non-req.fun.gc: There is not a requirement that the pool class support
+formatted objects, scanning, or collection objects; but it should not be
 arbitrarily precluded.
 
-.req.fun.align: The pool class must support aligned allocations to 
-client-specified alignments.  An individual instance need only support a single 
-alignment; multiple instances may be used to support more than one alignment 
+.req.fun.align: The pool class must support aligned allocations to
+client-specified alignments.  An individual instance need only support a single
+alignment; multiple instances may be used to support more than one alignment
 (source: req.epcore.attr.align).
 
-.req.fun.reallocate: The pool class must support resizing of allocated blocks 
+.req.fun.reallocate: The pool class must support resizing of allocated blocks
 (source req.epcore.fun.dl.promise.free, req.product.dc.env.{ansi-c,cpp}).
 
-.non-req.fun.reallocate.in-place: There is not a requirement blocks must be 
+.non-req.fun.reallocate.in-place: There is not a requirement blocks must be
 resized in place (where possible); but it seems like a good idea.
 
-.req.fun.thread: Each instance of the pool class must support multiple threads 
+.req.fun.thread: Each instance of the pool class must support multiple threads
 of allocation (source req.epcore.fun.dl.multi, req.product.dc.env.{ansi-c,cpp}).
 
-.req.attr.performance: The pool class must meet or exceed performance of 
-"competitive" allocators (source: rec.epcore.attr.{run-time,tp}, 
-req.product.attr.{mkt.eval, perform}).  [Dylan does not seem to have any 
-requirement that storage be allocated with a particular response time or 
-throughput, just so long as we don't block for too long. Clearly there is a 
+.req.attr.performance: The pool class must meet or exceed performance of
+"competitive" allocators (source: rec.epcore.attr.{run-time,tp},
+req.product.attr.{mkt.eval, perform}).  [Dylan does not seem to have any
+requirement that storage be allocated with a particular response time or
+throughput, just so long as we don't block for too long. Clearly there is a
 missing requirement.]
 
 .req.attr.performance.time: By inference, the time overhead must be competetive.
 
-.req.attr.performance.space: By inference, the space overhead must be 
+.req.attr.performance.space: By inference, the space overhead must be
 competetive.
 
-.req.attr.reliability: The pool class must have "rock-solid reliability" 
+.req.attr.reliability: The pool class must have "rock-solid reliability"
 (source: req.dylan.attr.rel.mtbf, req.epcore.attr.rel, req.product.attr.rel).
 
-.req.fun.range: The pool class must be able to manage blocks ranging in size 
-from 1 byte to all of addressable memory 
-(req.epcore.attr.{dl,gen,tmp,stat,cache,trap}.obj.{min,max}.  The range 
-requirement may be satisfied by multiple instances each managing a particular 
-client-specified subrange of sizes.  [Dylan has requirements 
-req.dylan.attr.{capacity,obj.max}, but no requirement that such objects reside 
-in a manual pool.] 
+.req.fun.range: The pool class must be able to manage blocks ranging in size
+from 1 byte to all of addressable memory
+(req.epcore.attr.{dl,gen,tmp,stat,cache,trap}.obj.{min,max}.  The range
+requirement may be satisfied by multiple instances each managing a particular
+client-specified subrange of sizes.  [Dylan has requirements
+req.dylan.attr.{capacity,obj.max}, but no requirement that such objects reside
+in a manual pool.]
 
-.req.fun.debug: The pool class must support debugging erroneous usage by client 
-programs (source: req.epcore.fun.{dc.variety, debug.support}, 
-req.product.attr.{mkt.eval,perform}).  Debugging is permitted to incur 
+.req.fun.debug: The pool class must support debugging erroneous usage by client
+programs (source: req.epcore.fun.{dc.variety, debug.support},
+req.product.attr.{mkt.eval,perform}).  Debugging is permitted to incur
 additional overhead.
 
-.req.fun.debug.boundaries: The pool class must support checking for accesses 
+.req.fun.debug.boundaries: The pool class must support checking for accesses
 outside the boundaries of live objects.
 
-.req.fun.debug.log: The pool class must support logging of all allocations and 
+.req.fun.debug.log: The pool class must support logging of all allocations and
 deallocations.
 
-.req.fun.debug.enumerate: The pool class must support examining all allocated 
+.req.fun.debug.enumerate: The pool class must support examining all allocated
 objects.
 
-.req.fun.debug.free: The pool class must support detecting incorrect, 
+.req.fun.debug.free: The pool class must support detecting incorrect,
 overlapping, and double frees.
 
-.req.fun.tolerant: The pool class must support tolerance of erroneous usage 
+.req.fun.tolerant: The pool class must support tolerance of erroneous usage
 (source req.product.attr.use.level.1).
 
 
 Essential Requirements
 
-.req.fun.profile: The pool class should support memory usage profiling (source: 
+.req.fun.profile: The pool class should support memory usage profiling (source:
 req.product.attr.{mkt.eval, perform}).
 
-.req.attr.flex: The pool class should be flexible so that it can be tuned to 
-specific allocation and freeing patterns (source: 
-req.product.attr.flex,req.epcore.attr.{dl,cache,trap}.typ).  The flexibility 
-requirement may be satisfied by multiple instances each optimizing a specific 
+.req.attr.flex: The pool class should be flexible so that it can be tuned to
+specific allocation and freeing patterns (source:
+req.product.attr.flex,req.epcore.attr.{dl,cache,trap}.typ).  The flexibility
+requirement may be satisfied by multiple instances each optimizing a specific
 pattern.
 
-.req.attr.adapt: The pool class should be adaptive so that it can accommodate 
-changing allocation and freeing patterns (source: 
+.req.attr.adapt: The pool class should be adaptive so that it can accommodate
+changing allocation and freeing patterns (source:
 req.epcore.fun.{tmp,stat}.policy, req.product.attr.{mkt.eval,perform}).
 
 
 Nice Requirements
 
-.req.fun.suballocate: The pool class may support freeing of any aligned, 
-contiguous subset of an allocated block (source req.epcore.fun.dl.free.any, 
+.req.fun.suballocate: The pool class may support freeing of any aligned,
+contiguous subset of an allocated block (source req.epcore.fun.dl.free.any,
 req.product.attr.{mkt.eval,perform}).
 
 
@@ -251,148 +251,148 @@ req.product.attr.{mkt.eval,perform}).
 
 ARCHITECTURE:
 
-.arch.overview: The pool has several layers: client allocation is by Allocation 
-Points (APs). .arch.overview.ap: APs acquire storage from the pool 
-available-block queue (ABQ). .arch.overview.abq: The ABQ holds blocks of a 
-minimum configurable size: "reuse size".  .arch.overview.storage: The ABQ 
-acquires storage from the arena or from the coalescing-block structure (CBS). 
-.arch.overview.storage.contiguous: The arena storage is requested to be 
-contiguous to maximize opportunities for coalescing (Loci will be used when 
-available). .arch.overview.cbs: The CBS holds blocks freed by the client until, 
-through coalescing, they have reached the reuse size, at which point they are 
+.arch.overview: The pool has several layers: client allocation is by Allocation
+Points (APs). .arch.overview.ap: APs acquire storage from the pool
+available-block queue (ABQ). .arch.overview.abq: The ABQ holds blocks of a
+minimum configurable size: "reuse size".  .arch.overview.storage: The ABQ
+acquires storage from the arena or from the coalescing-block structure (CBS).
+.arch.overview.storage.contiguous: The arena storage is requested to be
+contiguous to maximize opportunities for coalescing (Loci will be used when
+available). .arch.overview.cbs: The CBS holds blocks freed by the client until,
+through coalescing, they have reached the reuse size, at which point they are
 made available on the ABQ.
 
-.arch.ap: The pool will use allocation points as the allocation interface to 
-the client. .arch.ap.two-phase: Allocation points will request blocks from the 
-pool and suballocate those blocks (using the existing AP, compare and 
-increment, 2-phase mechanism) to satisfy client requests. .arch.ap.fill: The 
-pool will have a configurable "fill size" that will be the preferred size block 
-used to fill the allocation point. .arch.ap.fill.size: The fill size should be 
-chosen to amortize the cost of refill over a number of typical reserve/commit 
-operations, but not so large as to exceed the typical object population of the 
-pool. .arch.ap.no-fit: When an allocation does not fit in the remaining space 
-of the allocation point, there may be a remaining fragment. 
-.arch.ap.no-fit.sawdust: If the fragment is below a configurable threshold 
-(minimum size), it will be left unused (but returned to the CBS so it will be 
-reclaimed when adjacent objects are freed); .arch.ap.no-fit.splinter: 
-otherwise, the remaining fragment will be (effectively) returned to the head of 
-the available-block queue, so that it will be used as soon as possible (i.e., 
-by objects of similar birthdate). .arch.ap.no-fit.oversize: If the requested 
-allocation exceeds the fill size it is treated exceptionally (this may indicate 
-the client has either misconfigured or misused the pool and should either 
-change the pool configuration or create a separate pool for these exceptional 
-objects for best performance). .arch.ap.no-fit.oversize.policy: Oversize blocks 
-are assumed to have exceptional lifetimes, hence are allocated to one side and 
-do not participate in the normal storage recycling of the pool. 
-.arch.ap.refill.overhead: If reuse size is small, or becomes small due to 
-.arch.adapt, all allocations will effectively be treated exceptionally (the AP 
-will trip and a oldest-fit block will be chosen on each allocation).  This mode 
+.arch.ap: The pool will use allocation points as the allocation interface to
+the client. .arch.ap.two-phase: Allocation points will request blocks from the
+pool and suballocate those blocks (using the existing AP, compare and
+increment, 2-phase mechanism) to satisfy client requests. .arch.ap.fill: The
+pool will have a configurable "fill size" that will be the preferred size block
+used to fill the allocation point. .arch.ap.fill.size: The fill size should be
+chosen to amortize the cost of refill over a number of typical reserve/commit
+operations, but not so large as to exceed the typical object population of the
+pool. .arch.ap.no-fit: When an allocation does not fit in the remaining space
+of the allocation point, there may be a remaining fragment.
+.arch.ap.no-fit.sawdust: If the fragment is below a configurable threshold
+(minimum size), it will be left unused (but returned to the CBS so it will be
+reclaimed when adjacent objects are freed); .arch.ap.no-fit.splinter:
+otherwise, the remaining fragment will be (effectively) returned to the head of
+the available-block queue, so that it will be used as soon as possible (i.e.,
+by objects of similar birthdate). .arch.ap.no-fit.oversize: If the requested
+allocation exceeds the fill size it is treated exceptionally (this may indicate
+the client has either misconfigured or misused the pool and should either
+change the pool configuration or create a separate pool for these exceptional
+objects for best performance). .arch.ap.no-fit.oversize.policy: Oversize blocks
+are assumed to have exceptional lifetimes, hence are allocated to one side and
+do not participate in the normal storage recycling of the pool.
+.arch.ap.refill.overhead: If reuse size is small, or becomes small due to
+.arch.adapt, all allocations will effectively be treated exceptionally (the AP
+will trip and a oldest-fit block will be chosen on each allocation).  This mode
 will be within a constant factor in overhead of an unbuffered pool.
 
-.arch.abq: The available block queue holds blocks that have coalesced 
-sufficiently to reach reuse size.  arch.abq.reuse.size: A multiple of the 
-quantum of virtual memory is used as the reuse size (.anal.policy.size).  
-.arch.abq.fifo: It is a FIFO queue (recently coalesced blocks go to the tail of 
-the queue, blocks are taken from the head of the queue for reuse). 
-.arch.abq.delay-reuse: By thus delaying reuse, coalescing opportunities are 
-greater. .arch.abq.high-water: It has a configurable high water mark, which 
-when reached will cause blocks at the head of the queue to be returned to the 
-arena, rather than reused. .arch.abq.return: When the MPS supports it, the pool 
-will be able to return free blocks from the ABQ to the arena on demand. 
-.arch.return.segment: arch.abq.return can be guaranteed to be able to return a 
-segment by setting reuse size to twice the size of the segments the pool 
+.arch.abq: The available block queue holds blocks that have coalesced
+sufficiently to reach reuse size.  arch.abq.reuse.size: A multiple of the
+quantum of virtual memory is used as the reuse size (.anal.policy.size).
+.arch.abq.fifo: It is a FIFO queue (recently coalesced blocks go to the tail of
+the queue, blocks are taken from the head of the queue for reuse).
+.arch.abq.delay-reuse: By thus delaying reuse, coalescing opportunities are
+greater. .arch.abq.high-water: It has a configurable high water mark, which
+when reached will cause blocks at the head of the queue to be returned to the
+arena, rather than reused. .arch.abq.return: When the MPS supports it, the pool
+will be able to return free blocks from the ABQ to the arena on demand.
+.arch.return.segment: arch.abq.return can be guaranteed to be able to return a
+segment by setting reuse size to twice the size of the segments the pool
 requests from the arena.
 
-.arch.cbs: The coalescing block structure holds blocks that have been freed by 
-the client. .arch.cbs.optimize: The data structure is optimized for coalescing. 
-.arch.cbs.abq: When a block reaches reuse size, it is added to the ABQ. 
-.arch.cbs.data-structure: The data structures are organized so that a block can 
-be on both the CBS and ABQ simultaneously to permit additional coalescing, up 
+.arch.cbs: The coalescing block structure holds blocks that have been freed by
+the client. .arch.cbs.optimize: The data structure is optimized for coalescing.
+.arch.cbs.abq: When a block reaches reuse size, it is added to the ABQ.
+.arch.cbs.data-structure: The data structures are organized so that a block can
+be on both the CBS and ABQ simultaneously to permit additional coalescing, up
 until the time the block is removed from the ABQ and assigned to an AP.
 
-.arch.fragmentation.internal: Internal fragmentation results from The pool will 
-request large segments from the arena to minimize the internal fragmentation 
+.arch.fragmentation.internal: Internal fragmentation results from The pool will
+request large segments from the arena to minimize the internal fragmentation
 due to objects not crossing segment boundaries.
 
-.arch.modular: The architecture will be modular, to allow building variations 
-on the pool by assembling different parts. .arch.modular.example: For example, 
-it should be possible to build pools with any of the freelist mechanisms, with 
-in-band or out-of-band storage (where applicable), that do or do not support 
+.arch.modular: The architecture will be modular, to allow building variations
+on the pool by assembling different parts. .arch.modular.example: For example,
+it should be possible to build pools with any of the freelist mechanisms, with
+in-band or out-of-band storage (where applicable), that do or do not support
 derived object descriptions, etc.
 
-.arch.modular.initial: The initial architecture will use 
-.mech.freelist.splay-tree for the CBS, .sol.mech.storage.out-of-band, 
+.arch.modular.initial: The initial architecture will use
+.mech.freelist.splay-tree for the CBS, .sol.mech.storage.out-of-band,
 .sol.mech.desc.derived, and .sol.mech.allocate.buffer.
 
-.arch.segregate: The architecture will support segregated allocation through 
-the use of multiple allocation points. The client will choose the appropriate 
+.arch.segregate: The architecture will support segregated allocation through
+the use of multiple allocation points. The client will choose the appropriate
 allocation point either at run time, or when possible, at compile time.
 
-.arch.segregate.initial: The initial architecture will segregate allocations 
-into two classes: large and small. This will be implemented by creating two 
+.arch.segregate.initial: The initial architecture will segregate allocations
+into two classes: large and small. This will be implemented by creating two
 pools with different parameters.
 
-.arch.segregate.initial.choice: The initial architecture will provide glue code 
-to choose which pool to allocate from at run time. If possible this glue code 
-will be written in a way that a good compiler can optimize the selection of 
-pool at compile time. Eventually this glue code should be subsumed by the 
+.arch.segregate.initial.choice: The initial architecture will provide glue code
+to choose which pool to allocate from at run time. If possible this glue code
+will be written in a way that a good compiler can optimize the selection of
+pool at compile time. Eventually this glue code should be subsumed by the
 client or generated automatically by a tool.
 
-.arch.debug: Debugging features such as tags, fenceposts, types, creators will 
-be implemented in a layer above the pool and APs.  A generic pool debugging 
+.arch.debug: Debugging features such as tags, fenceposts, types, creators will
+be implemented in a layer above the pool and APs.  A generic pool debugging
 interface will be developed to support debugging in this outer layer.
 
-.arch.debug.initial: The initial architecture will have counters for 
+.arch.debug.initial: The initial architecture will have counters for
 objects/bytes allocated/freed and support for detecting overlapping frees.
 
-.arch.dependency.loci: The architecture depends on the arena being able to 
-efficiently provide segments of varying sizes without excessive fragmentation.  
-The locus mechanism should satisfy this dependency. (See .anal.strategy.risk) 
+.arch.dependency.loci: The architecture depends on the arena being able to
+efficiently provide segments of varying sizes without excessive fragmentation.
+The locus mechanism should satisfy this dependency. (See .anal.strategy.risk)
 
-.arch.dependency.mfs: The architecture internal data structures depend on 
-efficient manual management of small, fixed-sized objects (2 different sizes). 
+.arch.dependency.mfs: The architecture internal data structures depend on
+efficient manual management of small, fixed-sized objects (2 different sizes).
 The MFS pool should satisfy this dependency.
 
-.arch.contingency: Since the strategy we propose is new, it may not work. 
-.arch.contingency.pathalogical: In particular, pathological allocation patterns 
-could result in fragmentation such that no blocks recycle from the CBS to ABQ. 
-.arch.contingency.fallback: As a fallback, there will be a pool creation 
-parameter for a high water mark for the CBS. 
-.arch.contingency.fragmentation-limit: When the free space in the CBS as a 
-percentage of all the memory managed by the pool (a measure of fragmentation) 
-reaches that high water mark, the CBS will be searched oldest-fit before 
-requesting additional segments from the arena. .arch.contingency.alternative: 
-We also plan to implement .mech.freelist.cartesian-tree as an alternative CBS, 
+.arch.contingency: Since the strategy we propose is new, it may not work.
+.arch.contingency.pathalogical: In particular, pathological allocation patterns
+could result in fragmentation such that no blocks recycle from the CBS to ABQ.
+.arch.contingency.fallback: As a fallback, there will be a pool creation
+parameter for a high water mark for the CBS.
+.arch.contingency.fragmentation-limit: When the free space in the CBS as a
+percentage of all the memory managed by the pool (a measure of fragmentation)
+reaches that high water mark, the CBS will be searched oldest-fit before
+requesting additional segments from the arena. .arch.contingency.alternative:
+We also plan to implement .mech.freelist.cartesian-tree as an alternative CBS,
 which would permit more efficient searching of the CBS.
 
-.arch.parameters: The architecture supports several parameters so that multiple 
-pools may be instantiated and tuned to support different object cohorts. The 
-important parameters are: reuse size, minimum size, fill size, ABQ high water 
-mark, CBS fragmentation limit (see .arch.contingency.fragmentation-limit).  
-.arch.parameters.client-visible: The client-visible parameters of the pool are 
-the minimum object size, the mean object size, the maximum object size, the 
-reserve depth and fragmentation limit.  The minimum object size determines when 
-a splinter is kept on the head of the ABQ (.arch.ap.no-fit.splinter).  The 
-maximum object size determines the fill size (.arch.ap.fill-size) and hence 
-when a block is allocated exceptionally (.arch.ap.no-fit.oversize). The mean 
-object size is the most likely object size.  The reserve depth is a measure of 
-the hysteresis of the object population.  The mean object size, reserve depth 
-and, maximum object size are used to determine the size of the ABQ 
-(.arch.abq.high-water).  The fragmentation limit is used to determine when 
+.arch.parameters: The architecture supports several parameters so that multiple
+pools may be instantiated and tuned to support different object cohorts. The
+important parameters are: reuse size, minimum size, fill size, ABQ high water
+mark, CBS fragmentation limit (see .arch.contingency.fragmentation-limit).
+.arch.parameters.client-visible: The client-visible parameters of the pool are
+the minimum object size, the mean object size, the maximum object size, the
+reserve depth and fragmentation limit.  The minimum object size determines when
+a splinter is kept on the head of the ABQ (.arch.ap.no-fit.splinter).  The
+maximum object size determines the fill size (.arch.ap.fill-size) and hence
+when a block is allocated exceptionally (.arch.ap.no-fit.oversize). The mean
+object size is the most likely object size.  The reserve depth is a measure of
+the hysteresis of the object population.  The mean object size, reserve depth
+and, maximum object size are used to determine the size of the ABQ
+(.arch.abq.high-water).  The fragmentation limit is used to determine when
 contingency mode is used to satisfy an allocation request (.arch.contingency).
 
-.arch.adapt: We believe that an important adaptation to explore is tying the 
-reuse size inversely to the fragmentation (as measured in 
-.arch.contingency.fragmentation-limit). .arch.adapt.reuse: By setting reuse 
-size low when fragmentation is high, smaller blocks will be available for 
-reuse, so fragmentation should diminish. .arch.adapt.overhead: This will result 
-in higher overhead as the AP will need to be refilled more often, so reuse size 
-should be raised again as fragmentation diminishes. .arch.adapt.oldest-fit: In 
-the limit, if reuse size goes to zero, the pool will implement a "oldest-fit" 
-policy: the oldest free block of sufficient size will be used for each 
+.arch.adapt: We believe that an important adaptation to explore is tying the
+reuse size inversely to the fragmentation (as measured in
+.arch.contingency.fragmentation-limit). .arch.adapt.reuse: By setting reuse
+size low when fragmentation is high, smaller blocks will be available for
+reuse, so fragmentation should diminish. .arch.adapt.overhead: This will result
+in higher overhead as the AP will need to be refilled more often, so reuse size
+should be raised again as fragmentation diminishes. .arch.adapt.oldest-fit: In
+the limit, if reuse size goes to zero, the pool will implement a "oldest-fit"
+policy: the oldest free block of sufficient size will be used for each
 allocation.
 
-.arch.adapt.risk: This adaptation is an experimental policy and should not be 
+.arch.adapt.risk: This adaptation is an experimental policy and should not be
 delivered to clients until thoroughly tested.
 
 
@@ -401,91 +401,91 @@ delivered to clients until thoroughly tested.
 
 ANALYSIS:
 
-.anal.discard: We have discarded many traditional solutions based on experience 
-and analysis in paper.wil95(1). In particular, managing the free list as a 
-linear list arranged by address or size and basing policy on searching such a 
-linear list in a particular direction, from a particular starting point, using 
-fit and/or immediacy as criteria. We believe that none of these solutions is 
-derived from considering the root of the problem to be solved (as described in 
-.strategy), although their behavior as analyzed by Wilson gives several 
+.anal.discard: We have discarded many traditional solutions based on experience
+and analysis in paper.wil95(1). In particular, managing the free list as a
+linear list arranged by address or size and basing policy on searching such a
+linear list in a particular direction, from a particular starting point, using
+fit and/or immediacy as criteria. We believe that none of these solutions is
+derived from considering the root of the problem to be solved (as described in
+.strategy), although their behavior as analyzed by Wilson gives several
 insights.
 
-.anal.strategy: For any program to run in the minimum required memory (with 
-minimal overhead -- we discard solutions such as compression for now), 
-fragmentation must be eliminated. To eliminate fragmentation, simply place 
-blocks in memory so that they die "in order" and can be immediately coalesced. 
-This ideal is not achievable, but we believe we can find object attributes that 
-correlate with deathtime and exploit them to approximate the ideal. Initially 
-we believe birth time and type (as approximated by size) will be useful 
+.anal.strategy: For any program to run in the minimum required memory (with
+minimal overhead -- we discard solutions such as compression for now),
+fragmentation must be eliminated. To eliminate fragmentation, simply place
+blocks in memory so that they die "in order" and can be immediately coalesced.
+This ideal is not achievable, but we believe we can find object attributes that
+correlate with deathtime and exploit them to approximate the ideal. Initially
+we believe birth time and type (as approximated by size) will be useful
 attributes to explore.
 
-.anal.strategy.perform: To meet .req.attr.performance, the implementation of 
+.anal.strategy.perform: To meet .req.attr.performance, the implementation of
 .sol.strategy must be competitive in both time and space.
 
-.anal.strategy.risk: The current MPS segment substrate can cause internal 
-fragmentation which an individual pool can do nothing about. We expect that 
+.anal.strategy.risk: The current MPS segment substrate can cause internal
+fragmentation which an individual pool can do nothing about. We expect that
 request.epcore.170193.sugg.loci will be implemented to remove this risk.
 
-.anal.policy: Deferred coalescing, when taken to the extreme will not minimize 
-the memory consumption of a program, as no memory would ever be reused. Eager 
-reuse appears to lead to more fragmentation, whereas delayed reuse appears to 
-reduce fragmentation (paper.wil95(1)). The systems studied by Wilson did not 
-directly address deferring reuse. Our proposed policy is to reuse blocks when 
-they reach a (configurable) size. We believe that this policy along with the 
-policy of segregating allocations by death time, will greatly reduce 
-fragmentation. .anal.policy.risk: This policy could lead to pathologic behavior 
+.anal.policy: Deferred coalescing, when taken to the extreme will not minimize
+the memory consumption of a program, as no memory would ever be reused. Eager
+reuse appears to lead to more fragmentation, whereas delayed reuse appears to
+reduce fragmentation (paper.wil95(1)). The systems studied by Wilson did not
+directly address deferring reuse. Our proposed policy is to reuse blocks when
+they reach a (configurable) size. We believe that this policy along with the
+policy of segregating allocations by death time, will greatly reduce
+fragmentation. .anal.policy.risk: This policy could lead to pathologic behavior
 if allocations cannot be successfully segregated.
 
-.anal.policy.allocate.segregate: This policy has some similarities to 
-CustomAlloc (paper.grun92(1)). CustomAlloc segregates objects by size classes, 
-and then within those classes chooses a different allocator depending on 
-whether that size class has a stable or unstable population. Classes with 
-stable population recycle storage within the class, whereas classes with 
-unstable populations return their storage to the general allocation pool for 
-possible reuse by another class. CustomAlloc, however, requires profiling the 
-application and tuning the allocator according to those profiles. Although we 
+.anal.policy.allocate.segregate: This policy has some similarities to
+CustomAlloc (paper.grun92(1)). CustomAlloc segregates objects by size classes,
+and then within those classes chooses a different allocator depending on
+whether that size class has a stable or unstable population. Classes with
+stable population recycle storage within the class, whereas classes with
+unstable populations return their storage to the general allocation pool for
+possible reuse by another class. CustomAlloc, however, requires profiling the
+application and tuning the allocator according to those profiles. Although we
 intend to support such tuning, we do not want to require it.
 
-.anal.policy.reallocate: For reallocation, .fun.suballocate can be used to free 
-the remainder if a block is made smaller. Doing so will cause the freed block 
-to obey .sol.policy.allocate [i.e., the freed block will not be treated 
-specially, it will be subject to the normal policy on reuse]. Copying can be 
-used if a block is made larger. paper.vo96(0) reports success in 
-over-allocating a block the first time it is resized larger, presumably because 
-blocks that are resized once tend to be resized again and over-allocating may 
-avoid a subsequent copy. If each object that will be reallocated can be given 
-its own allocation point until its final reallocation, the allocation point can 
+.anal.policy.reallocate: For reallocation, .fun.suballocate can be used to free
+the remainder if a block is made smaller. Doing so will cause the freed block
+to obey .sol.policy.allocate [i.e., the freed block will not be treated
+specially, it will be subject to the normal policy on reuse]. Copying can be
+used if a block is made larger. paper.vo96(0) reports success in
+over-allocating a block the first time it is resized larger, presumably because
+blocks that are resized once tend to be resized again and over-allocating may
+avoid a subsequent copy. If each object that will be reallocated can be given
+its own allocation point until its final reallocation, the allocation point can
 be used to hold released or spare storage.
 
-.anal.policy.size: We believe that this will take advantage of the underlying 
-virtual memory system's ability to compact the physical memory footprint of the 
-program by discarding free fragments that align with the virtual memory 
-quantum.  (In a VM system one can approximate compaction by sparse mapping.  If 
-every other page of a segment is unused, the unused pages can be unmapped, 
+.anal.policy.size: We believe that this will take advantage of the underlying
+virtual memory system's ability to compact the physical memory footprint of the
+program by discarding free fragments that align with the virtual memory
+quantum.  (In a VM system one can approximate compaction by sparse mapping.  If
+every other page of a segment is unused, the unused pages can be unmapped,
 freeing up physical memory that can be mapped to a new contiguous vm range.)
 
-.anal.mech.freelist: The literature (paper.grun92(1), paper.vo96(0)) indicate 
-that .sol.freelist.cartesian-tree provides a space-efficient implementation at 
-some cost in speed. .sol.freelist.splay-tree is faster but less 
-space-efficient. .sol.freelist.bitmap is unstudied. Many of the faster 
-allocators maintain caches of free blocks by size to speed allocation of 
-"popular" sizes. We intend to initially explore not doing so, as we believe 
-that policy ultimately leads to fragmentation by mixing objects of varying 
-death times. Instead we intend to use a free list mechanism to support fast 
+.anal.mech.freelist: The literature (paper.grun92(1), paper.vo96(0)) indicate
+that .sol.freelist.cartesian-tree provides a space-efficient implementation at
+some cost in speed. .sol.freelist.splay-tree is faster but less
+space-efficient. .sol.freelist.bitmap is unstudied. Many of the faster
+allocators maintain caches of free blocks by size to speed allocation of
+"popular" sizes. We intend to initially explore not doing so, as we believe
+that policy ultimately leads to fragmentation by mixing objects of varying
+death times. Instead we intend to use a free list mechanism to support fast
 coalescing, deferring reuse of blocks until a minimum size has been reached.
 
-anal.mech.allocate.optimize-small: Wilson (paper.wil95(1)) notes that small 
-blocks typically have short lifetimes and that overall performance is improved 
-if you optimize the management of small blocks, e.g., 
-sol.mech.allocate.lookup-table for all small blocks.  We believe that 
+anal.mech.allocate.optimize-small: Wilson (paper.wil95(1)) notes that small
+blocks typically have short lifetimes and that overall performance is improved
+if you optimize the management of small blocks, e.g.,
+sol.mech.allocate.lookup-table for all small blocks.  We believe that
 .sol.mech.allocate.buffer does exactly that.
 
-.anal.mech.allocate.optimize-new: Wilson (paper.wil95(1)) reports some benefit 
-from "preserving wilderness", that is, when a block of memory must be requested 
-from the system to satisfy an allocation, only the minimum amount of that block 
-is used, the remainder is preserved (effectively by putting it at the tail of 
-the free list). This mechanism may or may not implement .sol.policy.allocate. 
-We believe a better mechanism is to choose to preserve or not, based on 
+.anal.mech.allocate.optimize-new: Wilson (paper.wil95(1)) reports some benefit
+from "preserving wilderness", that is, when a block of memory must be requested
+from the system to satisfy an allocation, only the minimum amount of that block
+is used, the remainder is preserved (effectively by putting it at the tail of
+the free list). This mechanism may or may not implement .sol.policy.allocate.
+We believe a better mechanism is to choose to preserve or not, based on
 .sol.policy.allocate.
 
 
@@ -493,62 +493,62 @@ We believe a better mechanism is to choose to preserve or not, based on
 
 IDEAS:
 
-.sol: Many solution ideas for manual management of variable-sized memory blocks 
-are enumerated by paper.wil95(1). Here we list the most promising, and some of 
+.sol: Many solution ideas for manual management of variable-sized memory blocks
+are enumerated by paper.wil95(1). Here we list the most promising, and some of
 our own.
 
 
 Strategy
 
-.sol.strategy: To run a program in the minimal required memory, with minimal 
-overhead, utilize memory efficiently. Memory becomes unusable when fragmented. 
-Strategy is to minimize fragmentation. So place blocks where they won't cause 
+.sol.strategy: To run a program in the minimal required memory, with minimal
+overhead, utilize memory efficiently. Memory becomes unusable when fragmented.
+Strategy is to minimize fragmentation. So place blocks where they won't cause
 fragmentation later.
 
-.sol.strategy.death: objects that will die together (in time) should be 
+.sol.strategy.death: objects that will die together (in time) should be
 allocated together (in space); thus they will coalesce, reducing fragmentation.
 
-.sol.strategy.death.birth: assume objects allocated near each other in time 
+.sol.strategy.death.birth: assume objects allocated near each other in time
 will have similar deathtimes (paper.beck82(0))
-.sol.strategy.death.type: assume objects of different type may have different 
+.sol.strategy.death.type: assume objects of different type may have different
 deathtimes, even if born together
 .sol.strategy.death.predict: find and use program features to predict deathtimes
 
-.sol.strategy.reallocate: reallocation implies rebirth, or at least a change in 
+.sol.strategy.reallocate: reallocation implies rebirth, or at least a change in
 lifetime
 
-.sol.strategy.debug: as much of the debugging functionality as possible should 
-be implemented as a generally available MPS utility; the pool will provide 
-support for debugging that would be expensive or impossible to allocate outside 
+.sol.strategy.debug: as much of the debugging functionality as possible should
+be implemented as a generally available MPS utility; the pool will provide
+support for debugging that would be expensive or impossible to allocate outside
 the pool
 
 
 Policy
 
-[Policy is an implementable decision procedure, hopefully approximating the 
+[Policy is an implementable decision procedure, hopefully approximating the
 strategy.]
 
 .sol.policy.reuse: defer reusing blocks, to encourage coalescing
-.sol.policy.split: when a block is split to satisfy an allocation, use the 
+.sol.policy.split: when a block is split to satisfy an allocation, use the
 remainder as soon as possible
-.sol.policy.size: prevent .policy.reuse from consuming all of memory by 
+.sol.policy.size: prevent .policy.reuse from consuming all of memory by
 choosing a (coalesced) block for reuse when it reaches a minimum size
-.sol.policy.size.fixed: use the quantum of virtual memory (e.g., one page) as 
+.sol.policy.size.fixed: use the quantum of virtual memory (e.g., one page) as
 minimum size
 .sol.policy.size.tune: allow tuning minimum size
 .sol.policy.size.adapt: adaptively change minimum size
-.sol.policy.allocate: allocate objects with similar birthdate and lifetime 
+.sol.policy.allocate: allocate objects with similar birthdate and lifetime
 together
 .sol.policy.allocate.segregate: segregate allocations by type
 .sol.policy.allocate.segregate.size: use size as a substitute for type
 .sol.policy.allocate.segregate.tune: permit tuning of segregation
 .sol.policy.allocate.segregate.adapt: adaptively segregate allocations
 
-.sol.policy.reallocate: implement reallocation in a central mechanism outside 
+.sol.policy.reallocate: implement reallocation in a central mechanism outside
 of the pool, create a generic pool interface in support of same.
 
 .sol.policy.debug: implement a pool debugging interface
-.sol.policy.debug.counters: implement debugging counters in the pool that are 
+.sol.policy.debug.counters: implement debugging counters in the pool that are
 queried with a generic interface
 .sol.policy.debug.verify: implement debugging error returns on overlapping frees
 
@@ -559,75 +559,75 @@ Mechanism
 
 .sol.mech.free-list: mechanisms that can be used to describe the free list
 
-.sol.mech.free-list.cartesian-tree: Using address and size as keys supports 
-fast coalescing of adjacent blocks and fast searching for optimal-sized blocks. 
-Unfortunately, because the shape of the tree is constrained by the second key, 
-it can become unbalanced. This data structure is used in the SunOS 4.1 malloc 
+.sol.mech.free-list.cartesian-tree: Using address and size as keys supports
+fast coalescing of adjacent blocks and fast searching for optimal-sized blocks.
+Unfortunately, because the shape of the tree is constrained by the second key,
+it can become unbalanced. This data structure is used in the SunOS 4.1 malloc
 (paper.grun92(1)).
-.sol.mech.free-list.splay-tree: The amortized cost of a splay tree is 
-competitive with balanced binary trees in the worst case, but can be 
-significantly better for regular patterns of access because recently-accessed 
-keys are moved to the root of the tree and hence can be re-accessed quickly. 
-This data structure is used in the System Vr4 malloc (paper.vo96(0)). (For a 
+.sol.mech.free-list.splay-tree: The amortized cost of a splay tree is
+competitive with balanced binary trees in the worst case, but can be
+significantly better for regular patterns of access because recently-accessed
+keys are moved to the root of the tree and hence can be re-accessed quickly.
+This data structure is used in the System Vr4 malloc (paper.vo96(0)). (For a
 complete analysis of the splay tree algorithm time bounds see paper.st85(0).)
-.sol.mech.free-list.bit-map: Using address as an index and fix-sized blocks, 
-the booleans can represent whether a block is free or not. Adjacent blocks can 
-be used to construct larger blocks. Efficient algorithms for searching for runs 
-in a vector are known. This data structure is used in many file system disk 
+.sol.mech.free-list.bit-map: Using address as an index and fix-sized blocks,
+the booleans can represent whether a block is free or not. Adjacent blocks can
+be used to construct larger blocks. Efficient algorithms for searching for runs
+in a vector are known. This data structure is used in many file system disk
 block managers.
-.sol.mech.free-list.refcount: A count of the number of allocated but not freed 
-subblocks of a block can be used to determine when a block is available for 
-reuse. This is an extremely compact data structure, but does not support 
+.sol.mech.free-list.refcount: A count of the number of allocated but not freed
+subblocks of a block can be used to determine when a block is available for
+reuse. This is an extremely compact data structure, but does not support
 subblock reuse.
-.sol.mech.free-list.hybrid: Bitmaps appear suited particularly to managing 
-small, contiguous blocks. The tree structures appear suited particularly to 
-managing varying-sized, discontiguous blocks. A refcount can be very efficient 
-if objects can be placed accurately according to death time. A hybrid mechanism 
+.sol.mech.free-list.hybrid: Bitmaps appear suited particularly to managing
+small, contiguous blocks. The tree structures appear suited particularly to
+managing varying-sized, discontiguous blocks. A refcount can be very efficient
+if objects can be placed accurately according to death time. A hybrid mechanism
 may offer better performance for a wider range of situations.
 
 .sol.mech.storage: methods that can be used to store the free list description
 
-.sol.mech.storage.in-band: The tree data structures are amenable to being 
-stored in the free blocks themselves, minimizing the space overhead of 
-management. To do so imposes a minimum size on free blocks and reduces the 
+.sol.mech.storage.in-band: The tree data structures are amenable to being
+stored in the free blocks themselves, minimizing the space overhead of
+management. To do so imposes a minimum size on free blocks and reduces the
 locality of the data structure.
-.sol.mech.storage.out-of-band: The bit-map data structure must be stored 
+.sol.mech.storage.out-of-band: The bit-map data structure must be stored
 separately.
 
-.sol.mech.desc: for an allocated block to be freed, its base and bound must be 
+.sol.mech.desc: for an allocated block to be freed, its base and bound must be
 known
 
-.sol.mech.desc.derived: Most clients can supply the base of the block. Some 
+.sol.mech.desc.derived: Most clients can supply the base of the block. Some
 clients can supply the bound.
-.sol.mech.desc.in-band: When the bound cannot be supplied, it can be stored as 
-an in-band "header". If neither the base nor bound can be supplied (e.g., the 
-client may only have an interior pointer to the block), a header and footer may 
+.sol.mech.desc.in-band: When the bound cannot be supplied, it can be stored as
+an in-band "header". If neither the base nor bound can be supplied (e.g., the
+client may only have an interior pointer to the block), a header and footer may
 be required.
-.sol.mech.desc.out-of-band: In un-tagged architectures, it may be necessary to 
-store the header and footer out-of-band to distinguish them from client data. 
-Out-of-band storage can improve locality and reliability. Any of the free-list 
+.sol.mech.desc.out-of-band: In un-tagged architectures, it may be necessary to
+store the header and footer out-of-band to distinguish them from client data.
+Out-of-band storage can improve locality and reliability. Any of the free-list
 structures can also be used to describe allocated blocks out-of-band.
-.sol.mech.desc.crossing-map: An alternative for untagged architectures is to 
-store a "crossing map" which records an encoding of the start of objects and 
+.sol.mech.desc.crossing-map: An alternative for untagged architectures is to
+store a "crossing map" which records an encoding of the start of objects and
 then store the descriptive information in-band.
 
-.sol.mech.allocate: mechanisms that can be used to allocate blocks (these 
+.sol.mech.allocate: mechanisms that can be used to allocate blocks (these
 typically sit on top of a more general free-list manager)
 
-.sol.mech.allocate.lookup-table: Use a table of popular sizes to cache free 
+.sol.mech.allocate.lookup-table: Use a table of popular sizes to cache free
 blocks of those sizes.
-.sol.mech.allocate.buffer: Allocate from contiguous blocks using compare and 
+.sol.mech.allocate.buffer: Allocate from contiguous blocks using compare and
 increment.
-.sol.mech.allocate.optimize-small: Use a combination of techniques to ensure 
-the time spent managing a block is small relative to the block's lifetime; 
+.sol.mech.allocate.optimize-small: Use a combination of techniques to ensure
+the time spent managing a block is small relative to the block's lifetime;
 assume small blocks typically have short lifetimes.
-.sol.mech.allocate.optimize-new: When "virgin" memory is acquired from the 
-operating system to satisfy a request, try to preserve it (i.e., use only what 
+.sol.mech.allocate.optimize-new: When "virgin" memory is acquired from the
+operating system to satisfy a request, try to preserve it (i.e., use only what
 is necessary)
 .sol.mech.allocate.segregate.size: use size as a substitute for type
 
-.sol.mech.reallocate: use .req.fun.suballocate to return unused memory when a 
-block shrinks, but differentiate this from an erroneous overlapping free by 
+.sol.mech.reallocate: use .req.fun.suballocate to return unused memory when a
+block shrinks, but differentiate this from an erroneous overlapping free by
 using separate interfaces.
 
 
@@ -640,67 +640,67 @@ The implementation consists of the following separable modules:
 
 Coalescing Block Structure
 
-.impl.c.cbs: The initial implementation will use .sol.mech.free-list.splay-tree 
-and sol.mech.storage.out-of-band. For locality, this storage should be managed 
-as a linked free list of splay nodes suballocated from blocks acquired from a 
-pool shared by all CBS's. Must support creation and destruction of an empty 
-tree. Must support search, insert and delete by key of type Addr.  Must support 
-finding left and right neighbors of a failed search for a key. Must support 
-iterating over the elements of the tree with reasonable efficiency. Must 
-support storing and retrieving a value of type Size associated with the key. 
-Standard checking and description should be provided. See design.mps.splay(0) 
+.impl.c.cbs: The initial implementation will use .sol.mech.free-list.splay-tree
+and sol.mech.storage.out-of-band. For locality, this storage should be managed
+as a linked free list of splay nodes suballocated from blocks acquired from a
+pool shared by all CBS's. Must support creation and destruction of an empty
+tree. Must support search, insert and delete by key of type Addr.  Must support
+finding left and right neighbors of a failed search for a key. Must support
+iterating over the elements of the tree with reasonable efficiency. Must
+support storing and retrieving a value of type Size associated with the key.
+Standard checking and description should be provided. See design.mps.splay(0)
 and design.mps.cbs(0).
 
 
 Available Block Queue
 
-.impl.c.abq: The initial implementation will be a queue of fixed size 
-(determined at pool creation time from the high water mark). Must support 
-creation and destruction of an empty queue. Must support insertion at the head 
-or tail of the queue (failing if full), peeking at the head of the queue, and 
-removal of the head (failing if empty) or any element of the queue (found by a 
+.impl.c.abq: The initial implementation will be a queue of fixed size
+(determined at pool creation time from the high water mark). Must support
+creation and destruction of an empty queue. Must support insertion at the head
+or tail of the queue (failing if full), peeking at the head of the queue, and
+removal of the head (failing if empty) or any element of the queue (found by a
 search). Standard checking and description should be provided.
 
 
 Pool Implementation
 
-.impl.c: The initial implementation will use the above modules to implement a 
-buffered pool. Must support creation and destruction of the pool. Creation 
-takes parameters: minimum size, mean size, maximum size, reserve depth and 
-fragmentation limit. Minimum, mean, and maximum size are used to calculate the 
-internal fill and reuse sizes. Reserve depth and mean size are used to 
-calculate the ABQ high water mark.  Fragmentation limit is used to set the CBS 
-contingency mode.  Must support buffer initialization, filling and emptying. 
-Must support freeing. Standard checking and description should be provided. 
-[Eventually, it should support scanning, so it can be used with collected 
+.impl.c: The initial implementation will use the above modules to implement a
+buffered pool. Must support creation and destruction of the pool. Creation
+takes parameters: minimum size, mean size, maximum size, reserve depth and
+fragmentation limit. Minimum, mean, and maximum size are used to calculate the
+internal fill and reuse sizes. Reserve depth and mean size are used to
+calculate the ABQ high water mark.  Fragmentation limit is used to set the CBS
+contingency mode.  Must support buffer initialization, filling and emptying.
+Must support freeing. Standard checking and description should be provided.
+[Eventually, it should support scanning, so it can be used with collected
 pools, but no manual pool currently does.]
 
-.impl.c.future: The implementation should not preclude "buffered free" 
+.impl.c.future: The implementation should not preclude "buffered free"
 (mail.ptw.1997-12-05.19-07(0), ff.) being added in the future.
 
-.impl.c.parameters: The pool parameters are calculated as follows from the 
-input parameters: minimum, mean, and maximum size are taked directly from the 
-parameters.  .impl.c.parameter.fill-size: The fill size is set to the maximum 
-size times the reciprocal of the fragmentation limit, aligned to the arena 
-alignment.  .imple.c.parameter.reuse-size: The reuse size is set to twice the 
-fill size (see .arch.abq.return.segment, .impl.c.free.merge.segment).  
-.impl.c.parameter.abq-limit: The ABQ high-water limit is set to the reserve 
-depth times the mean size (that is, the queue should hold as many reuse blocks 
-as would take to cover the population hysteresis if the population consisted 
-solely of mean-sized blocks, see .arch.abq.high-water).  
-.impl.c.parameter.avail-limit: The CBS high-water limit is implemented by 
-comparing the available free space to an "available limit".  The available 
-limit is updated each time a segment is allocated from or returned to the arena 
-by setting it to the total size of the pool times the fragmentation limit 
+.impl.c.parameters: The pool parameters are calculated as follows from the
+input parameters: minimum, mean, and maximum size are taked directly from the
+parameters.  .impl.c.parameter.fill-size: The fill size is set to the maximum
+size times the reciprocal of the fragmentation limit, aligned to the arena
+alignment.  .imple.c.parameter.reuse-size: The reuse size is set to twice the
+fill size (see .arch.abq.return.segment, .impl.c.free.merge.segment).
+.impl.c.parameter.abq-limit: The ABQ high-water limit is set to the reserve
+depth times the mean size (that is, the queue should hold as many reuse blocks
+as would take to cover the population hysteresis if the population consisted
+solely of mean-sized blocks, see .arch.abq.high-water).
+.impl.c.parameter.avail-limit: The CBS high-water limit is implemented by
+comparing the available free space to an "available limit".  The available
+limit is updated each time a segment is allocated from or returned to the arena
+by setting it to the total size of the pool times the fragmentation limit
 divide vy 100 (see .arch.contingency.fallback).
 
 .impl.c.ap.fill: An AP fill request will be handled as follows:
-o If the request is larger than fill size, attempt to request a segment from 
+o If the request is larger than fill size, attempt to request a segment from
 the arena sufficient to satisfy the request
 o Use any previously returned splinter (from .impl.c.ap.empty), if large enough
-o Attempt to retrieve a free block from the head of the ABQ (removing it from 
+o Attempt to retrieve a free block from the head of the ABQ (removing it from
 ABQ and CBS if found).
-o If above fragmentation limit, attempt to find a block on the CBS, using 
+o If above fragmentation limit, attempt to find a block on the CBS, using
 oldest-fit search
 o Attempt to request a segment of fill size from the arena
 o Attempt to find a block on the CBS, using oldest-fit search
@@ -708,57 +708,57 @@ o Otherwise, fail
 
 .impl.c.ap.empty: An AP empty request will be handled as follows:
 o If remaining free is less than min size, return it to the CBS
-o If the remaining free is larger than any previous splinter, return that 
+o If the remaining free is larger than any previous splinter, return that
 splinter to the CBS and save this one for use by a subsequent fill
 o Otherwise return the remaining block to the CBS
 
-.impl.c.free: When blocks are returned to the CBS a search is made for adjacent 
-blocks that can be merged. If not, the block is simply inserted in the CBS. If 
-a merge occurs between two blocks on the ABQ, the ABQ must be adjusted to 
-reflect the merge. .impl.c.free.exception: Exceptional blocks are returned 
+.impl.c.free: When blocks are returned to the CBS a search is made for adjacent
+blocks that can be merged. If not, the block is simply inserted in the CBS. If
+a merge occurs between two blocks on the ABQ, the ABQ must be adjusted to
+reflect the merge. .impl.c.free.exception: Exceptional blocks are returned
 directly to the arena.
 
-.impl.c.free.merge: If a merge occurs and the merged block is larger than reuse 
+.impl.c.free.merge: If a merge occurs and the merged block is larger than reuse
 size:
-o If the ABQ is full, remove the block at the head of the ABQ from the ABQ and 
+o If the ABQ is full, remove the block at the head of the ABQ from the ABQ and
 CBS and return it to the arena(*)
-o Insert the newly merged block at the tail of the ABQ, leaving it on the CBS 
+o Insert the newly merged block at the tail of the ABQ, leaving it on the CBS
 for further merging
 
-.impl.c.free.merge.segment: (*) Merged blocks may not align with arena 
-segments. If necessary, return the interior segments of a block to the arena 
-and return the splinters to the CBS.  .impl.c.free.merge.segment.reuse: If the 
-reuse size (the size at which blocks recycle from the CBS to the ABQ) is at 
-least twice the fill size (the size of segments the pool allocates from the 
-arena), we can guarantee that there will always be a returnable segment in 
-every ABQ block. .impl.c.free.merge.segment.overflow: If the reuse size is set 
-smaller (see .arch.adapt), there may not be a returnable segment in an ABQ 
-block, in which case the ABQ has "overflowed".  Whenever this occurs, the ABQ 
+.impl.c.free.merge.segment: (*) Merged blocks may not align with arena
+segments. If necessary, return the interior segments of a block to the arena
+and return the splinters to the CBS.  .impl.c.free.merge.segment.reuse: If the
+reuse size (the size at which blocks recycle from the CBS to the ABQ) is at
+least twice the fill size (the size of segments the pool allocates from the
+arena), we can guarantee that there will always be a returnable segment in
+every ABQ block. .impl.c.free.merge.segment.overflow: If the reuse size is set
+smaller (see .arch.adapt), there may not be a returnable segment in an ABQ
+block, in which case the ABQ has "overflowed".  Whenever this occurs, the ABQ
 will be refilled by searching the CBS for dropped reusable blocks when needed.
 
-.impl.c.free.merge.segment.risk: The current segment structure does not really 
-support what we would like to do.  Loci should do better:  support reserving 
-contiguous address space and mapping/unmapping any portion of that address 
+.impl.c.free.merge.segment.risk: The current segment structure does not really
+support what we would like to do.  Loci should do better:  support reserving
+contiguous address space and mapping/unmapping any portion of that address
 space.
 
-.impl.c.free.merge.alternative: Alternatively, if the MPS segment substrate 
-permitted mapping/unmapping of pages, the pool could use very large segments 
+.impl.c.free.merge.alternative: Alternatively, if the MPS segment substrate
+permitted mapping/unmapping of pages, the pool could use very large segments
 and map/unmap pages as needed.
 
 
 AP Dispatch
 
-.impl.c.multiap: The initial implementation will be a glue layer that selects 
-among several AP's for allocation according to the predicted deathtime (as 
-approximated by size) of the requested allocation. Each AP will be filled from 
-a pool instance tuned to the range of object sizes expected to be allocated 
-from that AP. [For bonus points provide an interface that creates a batch of 
-pools and AP's according to some set of expected object sizes. Eventually 
+.impl.c.multiap: The initial implementation will be a glue layer that selects
+among several AP's for allocation according to the predicted deathtime (as
+approximated by size) of the requested allocation. Each AP will be filled from
+a pool instance tuned to the range of object sizes expected to be allocated
+from that AP. [For bonus points provide an interface that creates a batch of
+pools and AP's according to some set of expected object sizes. Eventually
 expand to understand object lifetimes and general lifetime prediction keys.]
 
-impl.c.multiap.sample-code: This glue code is not properly part of the pool or 
-MPS interface.  It is a layer on top of the MPS interface, intended as sample 
-code for unsophisticated clients.  Sophisticated clients will likely want to 
+impl.c.multiap.sample-code: This glue code is not properly part of the pool or
+MPS interface.  It is a layer on top of the MPS interface, intended as sample
+code for unsophisticated clients.  Sophisticated clients will likely want to
 choose among multiple AP's more directly.
 
 
@@ -766,27 +766,27 @@ choose among multiple AP's more directly.
 
 TESTING:
 
-.test.component: Components .impl.c.splay, .impl.c.cbs, and .impl.c.abq will be 
+.test.component: Components .impl.c.splay, .impl.c.cbs, and .impl.c.abq will be
 subjected to individual component tests to verify their functionality.
 
-.test.regression: All tests applied to poolmv (design.mps.poolmv(0)) and 
-poolepdl (design.mps.poolepdl(0)) will be applied to poolmv2 to ensure that mv2 
+.test.regression: All tests applied to poolmv (design.mps.poolmv(0)) and
+poolepdl (design.mps.poolepdl(0)) will be applied to poolmvt to ensure that mvt
 is at least as functional as the pools it is replacing.
 
-.test.qa: Once poolmv2 is integrated into the MPS, the standard MPS QA tests 
-will be applied to poolmv2 prior to each release.
+.test.qa: Once poolmvt is integrated into the MPS, the standard MPS QA tests
+will be applied to poolmvt prior to each release.
 
-.test.customer: Customer acceptance tests will be performed on a per-customer 
-basis before release to that customer (cf., proc.release.epcore(2).test) 
+.test.customer: Customer acceptance tests will be performed on a per-customer
+basis before release to that customer (cf., proc.release.epcore(2).test)
 
 
 TEXT:
 
 Possible tweaks (from mail.pekka.1998-04-15.13-10(0)):
 
-1. Try to coalesce splinters returned from AP's with the front (or any) block 
+1. Try to coalesce splinters returned from AP's with the front (or any) block
 on the ABQ.
-2. Sort ABQ in some other way to minimize splitting/splinters. E.g., proximity 
+2. Sort ABQ in some other way to minimize splitting/splinters. E.g., proximity
 to recently allocated blocks.