From 52236aae84bd4bf3580b13e4fe94bc122924b2bd Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Mon, 5 Nov 2012 22:29:36 +0000 Subject: [PATCH] Minor edits. Copied from Perforce Change: 180350 ServerID: perforce.ravenbrook.com --- mps/manual/source/diagrams/symbol-table.svg | 115 +++++++++++++++----- mps/manual/source/guide/advanced.rst | 10 +- mps/manual/source/pool/amc.rst | 4 +- mps/manual/source/pool/amcz.rst | 4 +- mps/manual/source/pool/ams.rst | 3 +- mps/manual/source/pool/awl.rst | 3 +- mps/manual/source/pool/lo.rst | 10 +- mps/manual/source/pool/mv.rst | 2 +- mps/manual/source/pool/mvff.rst | 10 +- mps/manual/source/pool/mvt.rst | 34 +++--- mps/manual/source/pool/snc.rst | 4 +- mps/manual/source/topic/allocation.rst | 2 + mps/manual/source/topic/error.rst | 2 +- mps/manual/source/topic/plinth.rst | 12 +- 14 files changed, 142 insertions(+), 73 deletions(-) diff --git a/mps/manual/source/diagrams/symbol-table.svg b/mps/manual/source/diagrams/symbol-table.svg index 44ee9f6094c..2873753e743 100644 --- a/mps/manual/source/diagrams/symbol-table.svg +++ b/mps/manual/source/diagrams/symbol-table.svg @@ -14,7 +14,7 @@ id="svg2" version="1.1" inkscape:version="0.48.2 r9819" - sodipodi:docname="New document 1"> + sodipodi:docname="symbol-table.svg"> image/svg+xml - + @@ -94,23 +94,23 @@ id="rect2987" width="90" height="20" - x="80" + x="120" y="672.36218" /> TABLE keys values name - - values + + dependent + + dependent + + + symtab + diff --git a/mps/manual/source/guide/advanced.rst b/mps/manual/source/guide/advanced.rst index c71ec65f1aa..1f72c9dd020 100644 --- a/mps/manual/source/guide/advanced.rst +++ b/mps/manual/source/guide/advanced.rst @@ -582,7 +582,11 @@ A one-bit tag suffices here:: obj_t bucket[1]; /* hash buckets */ } buckets_s, *buckets_t; -Now the full details of the scan method can be given:: +Now the full details of the scan method can be given, with the revised +code highlighted: + +.. code-block:: c + :emphasize-lines: 6-9, 16-22 static mps_res_t buckets_scan(mps_ss_t ss, mps_addr_t base, mps_addr_t limit) { @@ -730,9 +734,9 @@ as a string object, instead of containing the name itself. .. figure:: ../diagrams/symbol-table.svg :align: center - :alt: Diagram: Global symbol table design. + :alt: Diagram: Global symbol table design (weak references shown as dashed lines). - Global symbol table design. + Global symbol table design (weak references shown as dashed lines). This design depends on the string object containing the symbol name being immutable. As it happens, all strings are immutable, because the diff --git a/mps/manual/source/pool/amc.rst b/mps/manual/source/pool/amc.rst index e0d48205684..8cdb7cc24c9 100644 --- a/mps/manual/source/pool/amc.rst +++ b/mps/manual/source/pool/amc.rst @@ -112,7 +112,9 @@ AMC interface mps_chain_t chain) ``fmt`` specifies the :term:`object format` for the objects - allocated in the pool. + allocated in the pool. The format must provide a :term:`scan + method`, a :term:`skip method`, a :term:`forward method`, an + :term:`is-forwarded method` and a :term:`padding method`. ``chain`` specifies the :term:`generation chain` for the pool. diff --git a/mps/manual/source/pool/amcz.rst b/mps/manual/source/pool/amcz.rst index f4e1a3f2108..355f24736ee 100644 --- a/mps/manual/source/pool/amcz.rst +++ b/mps/manual/source/pool/amcz.rst @@ -65,6 +65,8 @@ AMCZ interface mps_chain_t chain) ``fmt`` specifies the :term:`object format` for the objects - allocated in the pool. + allocated in the pool. The format must provide a :term:`skip + method`, a :term:`forward method`, an :term:`is-forwarded method` + and a :term:`padding method`. ``chain`` specifies the :term:`generation chain` for the pool. diff --git a/mps/manual/source/pool/ams.rst b/mps/manual/source/pool/ams.rst index 24c6e617a3b..ec0a9799b7b 100644 --- a/mps/manual/source/pool/ams.rst +++ b/mps/manual/source/pool/ams.rst @@ -112,7 +112,8 @@ AMS interface mps_chain_t chain) ``fmt`` specifies the :term:`object format` for the objects - allocated in the pool. + allocated in the pool. The format must provide a :term:`scan + method` and a :term:`skip method`. ``chain`` specifies the :term:`generation chain` for the pool. It must have a single generation. diff --git a/mps/manual/source/pool/awl.rst b/mps/manual/source/pool/awl.rst index e9007710e0d..4adb55b6516 100644 --- a/mps/manual/source/pool/awl.rst +++ b/mps/manual/source/pool/awl.rst @@ -324,7 +324,8 @@ AWL interface mps_awl_find_dependent_t find_dependent) ``fmt`` specifies the :term:`object format` for the objects - allocated in the pool. + allocated in the pool. The format must provide a :term:`scan + method` and a :term:`skip method`. ``find_dependent`` is a function of type :c:type:`mps_awl_find_dependent_t` that specifies how to find the diff --git a/mps/manual/source/pool/lo.rst b/mps/manual/source/pool/lo.rst index 26882ae267e..822b373aeb3 100644 --- a/mps/manual/source/pool/lo.rst +++ b/mps/manual/source/pool/lo.rst @@ -9,8 +9,8 @@ .. _pool-lo: -LO (Leaf Only) -============== +LO (Leaf Object) +================ **LO** is an :term:`automatically managed ` :term:`pool class` for :term:`leaf objects` (objects that @@ -101,7 +101,8 @@ LO interface .. c:function:: mps_class_t mps_class_lo(void) - Return the :term:`pool class` for an LO (Leaf Only) :term:`pool`. + Return the :term:`pool class` for an LO (Leaf Object) + :term:`pool`. When creating an LO pool, :c:func:`mps_pool_create` takes one extra argument:: @@ -111,4 +112,5 @@ LO interface mps_fmt_t fmt) ``fmt`` specifies the :term:`object format` for the objects - allocated in the pool. + allocated in the pool. The format must provide a :term:`skip + method`. diff --git a/mps/manual/source/pool/mv.rst b/mps/manual/source/pool/mv.rst index a4ed476dcbb..c0a5f90cc39 100644 --- a/mps/manual/source/pool/mv.rst +++ b/mps/manual/source/pool/mv.rst @@ -108,7 +108,7 @@ MV interface ``debug_option`` specifies the debugging options. See :c:type:`mps_debug_option_s`. - ``extend_szie``, ``average_size`` and ``maximum_size`` are as + ``extend_size``, ``average_size`` and ``maximum_size`` are as documented in :c:func:`mps_class_mv`. diff --git a/mps/manual/source/pool/mvff.rst b/mps/manual/source/pool/mvff.rst index db4163893aa..85453e547c8 100644 --- a/mps/manual/source/pool/mvff.rst +++ b/mps/manual/source/pool/mvff.rst @@ -30,10 +30,10 @@ on the same pool, because the worst-fit policy of buffer filling will grab all the large blocks, leading to severe fragmentation. If you need both forms of allocation, use two separate pools. -Note that using buffered allocation prevents (for obscure technical -reasons) the pool from allocating across segment boundaries. This can -cause added external fragmentation if objects are allocated that are a -significant fraction of the segment size. +Note that buffered allocation can't allocate across segment boundaries +(see :ref:`topic-allocation-point-implementation` for the technical +reason). This can cause added external fragmentation if objects are +allocated that are a significant fraction of the segment size. .. note:: @@ -167,7 +167,7 @@ MVFF introspection #include "mpscmvff.h" -.. c:function:: size_t mps_mvff_free_size(mps_pool_t mpspool) +.. c:function:: size_t mps_mvff_free_size(mps_pool_t pool) Return the total amount of free space in an MVFF pool. diff --git a/mps/manual/source/pool/mvt.rst b/mps/manual/source/pool/mvt.rst index 1d8439a5a1e..cf58cab9e05 100644 --- a/mps/manual/source/pool/mvt.rst +++ b/mps/manual/source/pool/mvt.rst @@ -12,8 +12,8 @@ MVT (Manual Variable Temporal) ============================== **MVT** :term:`manually manages ` -variable-sized, unformatted objects. It uses an :term:`allocation -policy` termed :dfn:`temporal fit`. +variable-sized, unformatted objects. It uses the :dfn:`temporal fit` +:term:`allocation policy`. .. index:: @@ -24,14 +24,14 @@ Temporal fit ------------ Temporal fit attempts to place consecutive allocations next to each -other. It relies on delaying reuse as long as possible to permit freed +other. It relies on delaying re-use as long as possible to permit freed blocks to :term:`coalesce`, thus maximizing the number of consecutive allocations that can be co-located. Temporal fit permits 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 -:term:`lifetimes`, either *a priori* knowledge, or knowledge acquired +:term:`lifetimes`: either *a priori* knowledge, or knowledge acquired by profiling. The best performance will be achieved by allocating objects with similar expected death times together. @@ -45,10 +45,10 @@ An application that has several classes of objects of widely differing life expectancy will best be served by creating a different MVT pool instance for each life-expectancy class. A more sophisticated 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 pool instance to allocate in. +an object, or any characteristic of objects that correlates with +lifetime, to choose an appropriate pool to allocate in. -Allocating objects with unknown or very different deathtimes together +Allocating objects with unknown or very different death times together will pessimize the space performance of MVT. @@ -158,8 +158,8 @@ MVT interface object population does vary, at a slight cost in efficiency. The reserve does not guarantee any particular amount of allocation. - ``fragmentation_limit`` is a percentage in (0, 100] that can be used - to set an upper limit on the space overhead of MVT in case block + ``fragmentation_limit`` is a percentage from 1 to 100 (inclusive). + It sets an upper limit on the space overhead of MVT, in case block death times and allocations do not correlate well. If the free space managed by the pool as a ratio of all the space managed by the pool exceeds ``fragmentation_limit``, the pool falls back to a @@ -168,14 +168,14 @@ MVT interface the pool to operate as a first-fit pool, at a significant cost in time efficiency: therefore this is not permitted. - A fragmentation limit of 100 will cause the pool to use temporal - fit (unless resources are exhausted). If the objects allocated in - the pool have similar lifetime expectancies, this mode will have - 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 used - to limit the space-inefficiency of temporal fit due to varying - object life expectancies. + A fragmentation limit of 100 causes the pool to always use + temporal fit (unless resources are exhausted). If the objects + allocated in the pool have similar lifetime expectancies, this + mode will have 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 used to limit the space-inefficiency of temporal + fit due to varying object life expectancies. .. index:: diff --git a/mps/manual/source/pool/snc.rst b/mps/manual/source/pool/snc.rst index d51c5805a3c..e9b5003e91a 100644 --- a/mps/manual/source/pool/snc.rst +++ b/mps/manual/source/pool/snc.rst @@ -103,8 +103,8 @@ SNC introspection mps_fmt_t fmt) ``fmt`` specifies the :term:`object format` for the objects - allocated in the pool. The format should provide at least the - methods scan, skip, and pad. + allocated in the pool. The format must provide a :term:`scan + method`, a :term:`skip method`, and a :term:`padding method`. When creating an allocation point on an SNC pool, :c:func:`mps_ap_create` takes one extra argument:: diff --git a/mps/manual/source/topic/allocation.rst b/mps/manual/source/topic/allocation.rst index 93d2b95060f..7bff1e40cb0 100644 --- a/mps/manual/source/topic/allocation.rst +++ b/mps/manual/source/topic/allocation.rst @@ -506,6 +506,8 @@ A correct version of ``insert_link`` looks like this:: .. index:: single: allocation points; implementation +.. _topic-allocation-point-implementation: + Allocation point implementation ------------------------------- diff --git a/mps/manual/source/topic/error.rst b/mps/manual/source/topic/error.rst index 02317e29f31..b584fcd7f5e 100644 --- a/mps/manual/source/topic/error.rst +++ b/mps/manual/source/topic/error.rst @@ -295,7 +295,7 @@ default. The cool variety is intended for development and testing. All functions check the consistency of their data structures and - may assert, including function on the :term:`critical path`. + may assert, including functions on the :term:`critical path`. All events are sent to the :term:`telemetry stream`, including events on the :term:`critical path`. diff --git a/mps/manual/source/topic/plinth.rst b/mps/manual/source/topic/plinth.rst index 5cc7d6fae86..39ebc56edbc 100644 --- a/mps/manual/source/topic/plinth.rst +++ b/mps/manual/source/topic/plinth.rst @@ -18,15 +18,15 @@ Plinth ====== -The :dfn:`plinth` is a program module providing the MPS with all the -support it needs from the execution environment. It serves two -purposes, both relating to operating system support: +The :dfn:`plinth` is a program module that provides the MPS with the +support it needs from the execution environment. The MPS uses the plinth instead of (say) the Standard C Library because: 1. The MPS is designed to be portable to systems that have only a *conforming freestanding implementation* of the C language: that - is, systems which potentially lack facilities of the Standard C - Library, such as Standard I/O. The plinth provides all the - necessary facilities. + is, systems which potentially lack some of the facilities of the + Standard C Library, such as standard I/O. The plinth provides a way + to map MPS requirements to the facilities provided on the platform, + whatever they are. 2. The plinth gives the :term:`client program` complete control of interaction between the MPS and the user, including