diff --git a/mps/manual/build.txt b/mps/manual/build.txt index 69c99271243..6e51c2e83c4 100644 --- a/mps/manual/build.txt +++ b/mps/manual/build.txt @@ -53,7 +53,7 @@ Optimizing for your object format ................................. If you are using your own :term:`object format`, you will also get -improved performance by allowing the compiler to do global optimisations +improved performance by allowing the compiler to do global optimizations between it and the MPS. So if your format implementation is in, say, ``myformat.c``, then you could make a file ``mymps.c`` containing:: @@ -127,18 +127,19 @@ architecture, and ``CT`` the compiler toolchain. Here are the platforms that we have regular access to and on which the MPS works well: -========= ============= ============ ================= -OS Architecture Compiler Makefile -========= ============= ============ ================= -FreeBSD Intel i386 GCC ``fri3gc.gmk`` -FreeBSD Intel x86_64 GCC ``fri6gc.gmk`` -Linux Intel i386 GCC ``lii3gc.gmk`` -Linux Intel x86_64 GCC ``lii6gc.gmk`` -Mac OS X i386 + x86_64 Clang ``mps.xcodeproj`` -Mac OS X i386 GCC (legacy) ``xci3gc.gmk`` -Windows Intel i386 Microsoft C ``w3i3mv.nmk`` -Windows Intel x86_64 Microsoft C ``w3i6mv.nmk`` -========= ============= ============ ================= +========== ========= ============= ============ ================= +Platform OS Architecture Compiler Makefile +========== ========= ============= ============ ================= +``fri3gc`` FreeBSD IA-32 GCC ``fri3gc.gmk`` +``fri6gc`` FreeBSD x86_64 GCC ``fri6gc.gmk`` +``lii3gc`` Linux IA-32 GCC ``lii3gc.gmk`` +``lii6gc`` Linux x86_64 GCC ``lii6gc.gmk`` +``xci3ll`` Mac OS X IA-32 Clang ``mps.xcodeproj`` +``xci6ll`` Mac OS X x86_64 Clang ``mps.xcodeproj`` +``xci3gc`` Mac OS X IA-32 GCC (legacy) ``xci3gc.gmk`` +``w3i3mv`` Windows IA-32 Microsoft C ``w3i3mv.nmk`` +``w3i6mv`` Windows x86_64 Microsoft C ``w3i6mv.nmk`` +========== ========= ============= ============ ================= Historically, the MPS worked on a much wider variety of platforms, and still could: IRIX, OSF/1 (Tru64), Solaris, SunOS, Classic Mac OS; diff --git a/mps/manual/source/glossary/a.rst b/mps/manual/source/glossary/a.rst index c176a06b0a6..ecfa6bdfffd 100644 --- a/mps/manual/source/glossary/a.rst +++ b/mps/manual/source/glossary/a.rst @@ -400,10 +400,6 @@ Memory Management Glossary: A possible, when there may still be enough evidence in the :term:`heap` to debug them. See :ref:`topic-error`. - associated object - - .. mps:specific:: ?? - asynchronous garbage collector A :term:`collector (2)` is asynchronous with respect to the diff --git a/mps/manual/source/glossary/d.rst b/mps/manual/source/glossary/d.rst index f5bc7672d22..f345249f893 100644 --- a/mps/manual/source/glossary/d.rst +++ b/mps/manual/source/glossary/d.rst @@ -128,6 +128,10 @@ Memory Management Glossary: D .. bibref:: [DB76]_. + dependent object + + .. mps:specific:: ?? + derived pointer .. see:: :term:`interior pointer`. diff --git a/mps/manual/source/glossary/f.rst b/mps/manual/source/glossary/f.rst index 9ec3d123ae4..65ae0d989de 100644 --- a/mps/manual/source/glossary/f.rst +++ b/mps/manual/source/glossary/f.rst @@ -237,10 +237,12 @@ Memory Management Glossary: F that foreign code is not passed the address of a block in a :term:`moving ` :term:`pools `, or which contain references to blocks in moving - pools. The :ref:`pool-lo` :term:`pool class` is designed - for this use case: blocks allocated from this pool do not - move and are never protected, and so may be passed safely - to foreign code. + pools. + + The :ref:`pool-lo` :term:`pool class` is designed for this + use case: blocks allocated from this pool do not move and + are never protected, and so may be passed safely to + foreign code. format diff --git a/mps/manual/source/glossary/n.rst b/mps/manual/source/glossary/n.rst index 1cae5dc6003..473f85566e2 100644 --- a/mps/manual/source/glossary/n.rst +++ b/mps/manual/source/glossary/n.rst @@ -22,9 +22,9 @@ Memory Management Glossary: N .. mps:specific:: - The MPS defines the :term:`C` preprocessor macro - :c:macro:`MPS_PF_ALIGN` to be the natural alignment of the - platform. + The MPS platform interface defines the :term:`C` + preprocessor macro :c:macro:`MPS_PF_ALIGN` to be the + natural alignment of the platform. nepotism diff --git a/mps/manual/source/glossary/o.rst b/mps/manual/source/glossary/o.rst index 7838b3dd901..982edd2d69f 100644 --- a/mps/manual/source/glossary/o.rst +++ b/mps/manual/source/glossary/o.rst @@ -22,8 +22,8 @@ Memory Management Glossary: O .. mps:specific:: - The MPS documentation reserves the term *object* for - :term:`formatted objects ` only. For + The MPS documentation generally reserves the term *object* + for :term:`formatted objects `. For units of allocation in general, it uses the term :term:`block`. diff --git a/mps/manual/source/glossary/r.rst b/mps/manual/source/glossary/r.rst index 28ea3ff6d61..50db2eabeaa 100644 --- a/mps/manual/source/glossary/r.rst +++ b/mps/manual/source/glossary/r.rst @@ -189,13 +189,14 @@ Memory Management Glossary: R with :term:`headers ` this may not be the case). The pointer returned by :c:func:`mps_alloc` and :c:func:`mps_reserve` is a reference to the object - allocated. The :term:`client program` is free to represent - references as it chooses (for example as :term:`tagged - pointer `), provided that it is able to - decode a reference from its representation into the MPS - interface representation and encode a reference from the - MPS into its representation. + allocated. + The :term:`client program` is free to represent references + as it chooses (for example, with :term:`tags `), provided that it is able to decode a + reference from its representation into the MPS interface + representation and encode a reference from the MPS into + its representation. reference counting diff --git a/mps/manual/source/glossary/t.rst b/mps/manual/source/glossary/t.rst index d969b5be911..324676055c9 100644 --- a/mps/manual/source/glossary/t.rst +++ b/mps/manual/source/glossary/t.rst @@ -101,10 +101,9 @@ Memory Management Glossary: T An indentifier representing a string, returned from :c:func:`mps_telemetry_intern`, that can be associated - with certain :term:`formatted objects ` - of variant B, and so appear in the :term:`telemetry - stream` attached to events concerning those objects. See - :ref:`topic-telemetry`. + with certain :term:`addresses
`, and so appear in + the :term:`telemetry stream` attached to events concerning + those addresses. See :ref:`topic-telemetry`. telemetry stream diff --git a/mps/manual/source/glossary/v.rst b/mps/manual/source/glossary/v.rst index e291c75f047..8bd97b87617 100644 --- a/mps/manual/source/glossary/v.rst +++ b/mps/manual/source/glossary/v.rst @@ -161,8 +161,7 @@ Memory Management Glossary: V An :term:`arena class` which gets its :term:`memory (2)` from the operating system's :term:`virtual memory` - interface. See :c:func:`mps_arena_class_vm` and - :c:func:`mps_arena_class_vmnz`. + interface. See :c:func:`mps_arena_class_vm`. visitor function diff --git a/mps/manual/source/guide/lang.rst b/mps/manual/source/guide/lang.rst index 6f2d22fd448..b4f24578151 100644 --- a/mps/manual/source/guide/lang.rst +++ b/mps/manual/source/guide/lang.rst @@ -95,13 +95,12 @@ operate on objects generically, testing ``TYPE(obj)`` as necessary } Each constructor allocates memory for the new object by calling -``malloc``. For example ``make_pair`` is the constructor for pairs:: +``malloc``. For example, ``make_pair`` is the constructor for pairs:: static obj_t make_pair(obj_t car, obj_t cdr) { obj_t obj = (obj_t)malloc(sizeof(pair_s)); if (obj == NULL) error("out of memory"); - total += sizeof(pair_s); obj->pair.type = TYPE_PAIR; CAR(obj) = car; CDR(obj) = cdr; @@ -110,7 +109,8 @@ Each constructor allocates memory for the new object by calling Objects are never freed, because it is necessary to prove that they are :term:`dead` before their memory can be :term:`reclaimed -`. And that task falls to the :term:`garbage collector`. +`. To prove that they are dead, we need a :term:`tracing +` :term:`garbage collector`. Which the MPS will provide Choosing an arena class @@ -119,7 +119,7 @@ Choosing an arena class You'll recall from the :ref:`guide-overview` that the functionality of the MPS is divided between the :term:`arenas `, which request memory from (and return it to) the operating system, and :term:`pools -`, which allocate blocks of memory on behalf of your program. +`, which allocate blocks of memory for your program. There are two main classes of arena: the :term:`client arena`, :c:func:`mps_arena_class_cl`, which gets its memory from your program, @@ -130,11 +130,11 @@ memory` interface. The client arena is intended for use on embedded systems where there is no virtual memory, and has a couple of disadvantages (you have to decide how much memory you are going to use; and the MPS can't return -memory to the operating system for use by other processes) so in most -situations you'll want to use the virtual memory arena. +memory to the operating system for use by other processes) so for +general-purpose programs you'll want to use the virtual memory arena. -You'll need a couple of headers (``mps.h`` for the MPS interface, and -``mpsavm.h`` for the virtual memory arena class):: +You'll need a couple of headers: ``mps.h`` for the MPS interface, and +``mpsavm.h`` for the virtual memory arena class:: #include "mps.h" #include "mpsavm.h" @@ -1035,10 +1035,9 @@ MPS attempts to scan ``obj`` at the indicated point, the object's ``type`` field will be uninitialized, and so the :term:`scan method` may abort. -The MPS solves this problem via the :term:`reserve/commit -protocol`. This needs an additional structure, an :term:`allocation -point`, to be attached to the pool by calling -:c:func:`mps_ap_create`:: +The MPS solves this problem via the :term:`allocation point protocol`. +This needs an additional structure, an :term:`allocation point`, to be +attached to the pool by calling :c:func:`mps_ap_create`:: static mps_ap_t obj_ap; diff --git a/mps/manual/source/pool/index.rst b/mps/manual/source/pool/index.rst index 2f9a110e69a..a28cdcf08d1 100644 --- a/mps/manual/source/pool/index.rst +++ b/mps/manual/source/pool/index.rst @@ -1,13 +1,8 @@ .. _pool: -************** Pool reference ************** -==================== -List of pool classes -==================== - .. toctree:: :maxdepth: 1 :glob: @@ -17,7 +12,6 @@ List of pool classes .. _pool-choose: -===================== Choosing a pool class ===================== @@ -80,7 +74,8 @@ no *any* weak :ref:`pool-mvt` [1]_ them. -===================== +.. _pool-properties: + Pool class properties ===================== @@ -96,28 +91,28 @@ example, if blocks in a pool may not contain :term:`references ============================================= ===== ===== ===== ===== ===== ===== ===== ===== ===== Property AMC AMCZ AMS AWL LO MV MVFF MVT SNC ============================================= ===== ===== ===== ===== ===== ===== ===== ===== ===== -Supports :c:func:`mps_alloc`? no no ?? no no yes yes no ?? -Supports :c:func:`mps_free`? no no ?? no no yes yes yes ?? -Supports allocation points? yes yes ?? yes yes no no yes ?? -Timing of collections? [2]_ auto auto ?? auto auto --- --- --- ?? -May contain references? [3]_ yes no ?? yes no no no no ?? -May contain exact references? [4]_ yes --- ?? yes --- --- --- --- ?? -May contain ambiguous references? [4]_ no --- ?? no --- --- --- --- ?? -May contain weak references? [4]_ no --- ?? yes --- --- --- --- ?? -Allocations fixed or variable in size? var var ?? var var var var var ?? -Alignment? [5]_ conf conf ?? conf conf [6]_ [7]_ [6]_ ?? -Associated objects? [8]_ no --- ?? yes --- --- --- --- ?? +Supports :c:func:`mps_alloc`? no no no no no yes yes no ?? +Supports :c:func:`mps_free`? no no no no no yes yes yes ?? +Supports allocation points? yes yes yes yes yes no no yes ?? +Timing of collections? [2]_ auto auto yes auto auto --- --- --- ?? +May contain references? [3]_ yes no yes yes no no no no ?? +May contain exact references? [4]_ yes --- yes yes --- --- --- --- ?? +May contain ambiguous references? [4]_ no --- no no --- --- --- --- ?? +May contain weak references? [4]_ no --- no yes --- --- --- --- ?? +Allocations fixed or variable in size? var var var var var var var var ?? +Alignment? [5]_ conf conf conf conf conf [6]_ [7]_ [6]_ ?? +Dependent objects? [8]_ no --- no yes --- --- --- --- ?? May use remote references? [9]_ no --- ?? no --- --- --- --- ?? Ambiguous references keep blocks alive? no no ?? no no --- --- --- ?? -Blocks are automatically managed? [10]_ yes yes ?? yes yes no no no ?? -Blocks are manually managed? [10]_ no no ?? no no yes yes yes ?? -Blocks are scanned? [11]_ yes no ?? yes no no no no ?? +Blocks are automatically managed? [10]_ yes yes yes yes yes no no no ?? +Blocks are manually managed? [10]_ no no no no no yes yes yes ?? +Blocks are scanned? [11]_ yes no yes yes no no no no ?? Blocks support base references only? [12]_ yes yes ?? yes yes --- --- --- ?? Blocks support internal references? [12]_ no no ?? no no --- --- --- ?? Blocks may be protected by barriers? yes no ?? yes no no no no ?? -Blocks may move? yes yes ?? no no no no no ?? +Blocks may move? yes yes no no no no no no ?? Blocks may be finalized? yes yes ?? yes yes no no no ?? -Blocks must be formatted? [11]_ yes yes ?? yes yes no no no ?? +Blocks must be formatted? [11]_ yes yes yes yes yes no no no ?? ============================================= ===== ===== ===== ===== ===== ===== ===== ===== ===== .. note:: @@ -148,7 +143,7 @@ Blocks must be formatted? [11]_ yes yes ?? yes yes alignment` for the :term:`platform`). .. [8] In pools with this property, each object may specify an - :term:`associated object` which the client program guarantees + :term:`dependent object` which the client program guarantees will be accessible during the scanning of the first object. This may be used in the implementation of :term:`weak hash tables `. @@ -165,11 +160,12 @@ Blocks must be formatted? [11]_ yes yes ?? yes yes that these properties are not mutually exclusive, although the MPS does not provide a pool class that satisfies both. - .. [11] Blocks "are scanned" if the MPS :term:`scans ` them for - references; blocks "must be formatted" if they are described to - the MPS by an :term:`object format`. At present, the MPS only - knows how to scan blocks using the :term:`scan method` from an - object format, but it is in theory possible to scan unformatted + .. [11] Blocks "are scanned" if the MPS :term:`scans ` them + for references; blocks "must be formatted" if they are + described to the MPS by an :term:`object format`. At + present, the MPS only knows how to scan blocks using the + :term:`scan method` from an object format, but the MPS + design does not preclude pools that scan unformatted blocks. .. [12] A block "supports internal references" if a reference to any diff --git a/mps/manual/source/themes/mps/static/mps.css_t b/mps/manual/source/themes/mps/static/mps.css_t index 31acc216894..ce354ff9eef 100644 --- a/mps/manual/source/themes/mps/static/mps.css_t +++ b/mps/manual/source/themes/mps/static/mps.css_t @@ -87,6 +87,10 @@ div.seealso, div.admonition { border: none; } +div.admonition p.admonition-title + p + p { + margin-top: 5px; +} + .xref.std-term { font-style: normal; color: {{ theme_textcolor }}; diff --git a/mps/manual/source/todo.rst b/mps/manual/source/todo.rst index 744d66729b1..3a92ae19e5c 100644 --- a/mps/manual/source/todo.rst +++ b/mps/manual/source/todo.rst @@ -18,8 +18,9 @@ Outstanding .. _sphinx-natbib: http://wnielson.bitbucket.org/projects/sphinx-natbib/ -9. Hyphenate long function names across line endings (but what if you - copy them?) +9.  Hyphenate long function names across line endings. It would be + possible to do this by inserting soft hyphens but if you copied + the function name you'd copy the soft hyphens too. 11. Support MMREF-style anchors to the glossary (``#garbage.collection`` as well as ``#garbage-collection``). @@ -33,6 +34,10 @@ Outstanding 61. Start adding index entries. +72. When a ``.. note::`` block contains a numbered list with multiple + items (as :ref:`here `) or multiple footnotes (as + :ref:`here `) the heading should say "Notes". + Complete @@ -217,7 +222,7 @@ Complete typedef void (*mps_amc_apply_stepper_t)(mps_addr_t object, void *p, size_t s) - *Answer:* Richard says I can make this change since it's + *Answer:* RB says I can make this change since it's backwards-compatible. 28. Wouldn't the Scheme example be better without TAB characters? diff --git a/mps/manual/source/topic/platform.rst b/mps/manual/source/topic/platform.rst index ccadb02d3ab..f440054c33f 100644 --- a/mps/manual/source/topic/platform.rst +++ b/mps/manual/source/topic/platform.rst @@ -110,12 +110,12 @@ Declared in ``mpstd.h`` A :term:`C` preprocessor macro that names the :term:`platform` for which the MPS was built. - It expands to a string "``abcdef``" consisting of six characters + It expands to a string "``OSARCT``" consisting of six characters that are digits or lower-case letters. The first two characters name the operating system: ====== ================ ==================== - ``ab`` Operating system Constant + ``OS`` Operating system Constant ====== ================ ==================== ``fr`` FreeBSD :c:macro:`MPS_OS_FR` ------ ---------------- -------------------- @@ -129,17 +129,17 @@ Declared in ``mpstd.h`` The second pair of characters name the processor architecture: ====== ====================== ====================== - ``cd`` Processor architecture Constant + ``AR`` Processor architecture Constant ====== ====================== ====================== ``i3`` Intel/AMD IA-32 :c:macro:`MPS_ARCH_I3` ------ ---------------------- ---------------------- ``i6`` Intel/AMD x86-64 :c:macro:`MPS_ARCH_I6` ====== ====================== ====================== - The third pair of characters name the compiler: + The third pair of characters name the compiler toolchain: ====== ================ ======================= - ``ef`` Compiler Constant + ``CT`` Compiler Constant ====== ================ ======================= ``gc`` GCC :c:macro:`MPS_BUILD_GC` ------ ---------------- ----------------------- diff --git a/mps/manual/source/topic/plinth.rst b/mps/manual/source/topic/plinth.rst index 49d30a4bb7c..455507bf909 100644 --- a/mps/manual/source/topic/plinth.rst +++ b/mps/manual/source/topic/plinth.rst @@ -1,16 +1,16 @@ .. _topic-plinth: -The plinth -========== +Plinth +====== -From //info.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo/mmdoc/doc/mps/ref-man/concepts/index.html +From A program module providing the MPS with all the support it needs from the execution environment. Mainly this includes simple I/O facilities to support debugging. The plinth is provided by the client application; however, a sample implementation of the plinth using standard ANSI C library facilities is included with the MPS, and this is good enough for most applications. -From //info.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo/mmdoc/doc/mps/guide/interface/index.html +From To perform its various duties, the MPS needs very little external support. Indeed, there is a way of using it so that it needs none at all, making it possible to use the MPS in embedded applications. There are two key components to this: the client arena and the plinth . This section concerns the plinth; for more information about the client arena, see mps_arena_class_cl in the Reference Manual. @@ -22,12 +22,12 @@ However, before you panic, a sample implementation of a plinth using standard IS There are many reasons why you might want to write your own plinth. For embedded applications, the MPS will work in what the C standard calls a freestanding environment, as long as you provide it with a plinth that works in that environment, and use the client arena (virtual memory arenas contain OS-specific code that calls the VM interfaces of the OS). Programmers of GUI applications might want a plinth that directs debugging output to a convenient window. -See //info.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo/mmdoc/doc/mps/guide/appendix/plinth/index.html +See The example ANSI plinth, ``mpsliban.c``, implements :c:func:`mps_clock` by calling the ISO C function ``clock`` in ``time.h``. The difference between two of these clock values may be converted to seconds by dividing by the ``CLOCKS_PER_SEC`` conversion factor. -See also //info.ravenbrook.com/project/mps/master/design/io/index.html +See also Declared in ``mpsio.h``