From aa71bfe1bc76f93f7ae99aa772b1052c22f046de Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Tue, 28 May 2013 16:47:58 +0100 Subject: [PATCH] Describe the fact that the collector works across pools in several places where people are likely to look for this information. Improve wording of assertion handling section. Copied from Perforce Change: 182278 ServerID: perforce.ravenbrook.com --- mps/manual/source/guide/advanced.rst | 6 ++- mps/manual/source/guide/overview.rst | 23 ++++++----- mps/manual/source/topic/collection.rst | 7 ++++ mps/manual/source/topic/error.rst | 56 ++++++++++++++------------ mps/manual/source/topic/plinth.rst | 49 +++++++++++----------- mps/manual/source/topic/root.rst | 12 +++--- 6 files changed, 89 insertions(+), 64 deletions(-) diff --git a/mps/manual/source/guide/advanced.rst b/mps/manual/source/guide/advanced.rst index a6604daf573..6835359e717 100644 --- a/mps/manual/source/guide/advanced.rst +++ b/mps/manual/source/guide/advanced.rst @@ -876,7 +876,11 @@ Segregation of objects When objects of different types have different properties (different sizes, lifetimes, references, layouts) it makes sense to segregate -them into pools of appropriate classes. +them into pools of appropriate classes. The garbage collector in the +MPS is designed to work efficiently with many pools: it traces +references between objects in different pools, and it coordinates the +scanning of the :term:`registers` and :term:`control stacks` (see +:ref:`topic-root-thread`). For example, the toy Scheme interpreter has a mixture of object types, some of which contain references to other objects (for example, pairs) diff --git a/mps/manual/source/guide/overview.rst b/mps/manual/source/guide/overview.rst index 322d9ea6258..02925361069 100644 --- a/mps/manual/source/guide/overview.rst +++ b/mps/manual/source/guide/overview.rst @@ -111,21 +111,24 @@ for example by calling :c:func:`mps_free`) and others are **scan** for :term:`references` to allocated blocks. See :ref:`topic-scanning`. -The arena needs you to tell it how to find your **roots**: references to -allocated blocks that are stored in static data, in memory not managed -by the MPS, or on your program's :term:`registers` or +The arena needs you to tell it how to find your **roots**: references +to allocated blocks that are stored in static data, in memory not +managed by the MPS, in your program's :term:`registers`, or on its :term:`control stack`. See :ref:`topic-root`. The MPS is designed to work with multi-threaded programs. Functions in -the C interface are thread safe, except in a few documented -cases. See :ref:`topic-thread`. The :term:`allocation point -protocol` provides fast lock-free allocation on multiple threads -simultaneously. See :ref:`topic-allocation`. +the C interface are thread safe, except in a few documented cases. See +:ref:`topic-thread`. The :term:`allocation point protocol` provides +fast lock-free allocation on multiple threads simultaneously. See +:ref:`topic-allocation`. The garbage collector is :term:`incremental `: it proceeds in small steps interleaved with the execution -of your program, so there are no long waits. See -:ref:`topic-collection`. +collection>`: it proceeds in small steps interleaved with the +execution of your program, so there are no long waits. The garbage +collector is designed to work efficiently with multiple pools, and +in cases where there are many references between objects in different +pools. See :ref:`topic-collection`. + What next? diff --git a/mps/manual/source/topic/collection.rst b/mps/manual/source/topic/collection.rst index bad646ea8e5..af1c18dfce9 100644 --- a/mps/manual/source/topic/collection.rst +++ b/mps/manual/source/topic/collection.rst @@ -13,6 +13,13 @@ Garbage collection ================== +The :term:`arena` contains a :term:`garbage collector` that +coordinates the collection of garbage in all of its +:term:`automatically managed ` +:term:`pools`. The collector efficiently traces references between +:term:`roots` and pools, and between objects in different pools. It is +capable of collecting many automatically managed pools simultaneously. + .. index:: single: chain; generation diff --git a/mps/manual/source/topic/error.rst b/mps/manual/source/topic/error.rst index 805f50af3bf..abf1a1c2600 100644 --- a/mps/manual/source/topic/error.rst +++ b/mps/manual/source/topic/error.rst @@ -188,13 +188,43 @@ than the client program, but it is not unknown, so if you have made every effort to track down the cause (see :ref:`guide-debug`) without luck, :ref:`get in touch `. + +.. index:: + single: assertion + single: error handling; assertion; assertion handling + +.. _topic-error-assertion-handling: + +Assertion handling +.................. + +When the MPS detects an assertion failure, it calls the :term:`plinth` +function :c:func:`mps_lib_assert_fail`. Unless you have replaced the plinth, this behaves as follows: + +- In the :term:`cool` :term:`variety`, print the assertion message to + standard error and terminate the program by calling :c:func:`abort`. + +- In the :term:`hot` and :term:`rash` varieties, print the assertion + message to standard error and do *not* terminate the program. + +You can change this behaviour by providing your own plinth, or using +:c:func:`mps_lib_assert_fail_install`. + +In many applications, users don't want their program terminated when +the MPS detects an error, no matter how severe. A lot of MPS +assertions indicate that the program is going to crash very soon, but +there still may be a chance for a user to get some useful results or +save their work. This is why the default assertion handler only +terminates in the :term:`cool` :term:`variety`. + + .. index:: single: assertion; common causes .. _topic-error-cause: Common assertions and their causes ----------------------------------- +.................................. This section lists some commonly encountered assertions and suggests likely causes. If you encounter an assertion not listed here (or an @@ -264,30 +294,6 @@ this documentation. condition? -.. index:: - single: assertion - single: error handling; assertion; assertion handling - -.. _topic-error-assertion-handling: - -Assertion Handling ------------------- - -When the MPS detects an assertion failure, it calls the :term:`plinth` -function :c:func:`mps_lib_assert_fail`. If you have not replaced the -plinth, this will print the assertion message and terminate the program -in the :term:`cool` :term:`variety`, but *not* in the :term:`hot` or -:term:`rash` varieties. You can change this behaviour by providing your -own plinth, or using :c:func:`mps_lib_assert_fail_install`. - -In many applications, users don't want their program terminated when the -MPS detects an error, no matter how severe. A lot of MPS assertions -indicate that the program is going to crash very soon, but there still -may be a chance for a user to get some useful results or save their -work. This is why the default assertion handler only terminates in the -:term:`cool` :term:`variety`. - - .. index:: single: error handling; varieties single: variety diff --git a/mps/manual/source/topic/plinth.rst b/mps/manual/source/topic/plinth.rst index fc50e847a0e..41866ed76e0 100644 --- a/mps/manual/source/topic/plinth.rst +++ b/mps/manual/source/topic/plinth.rst @@ -116,8 +116,8 @@ I/O module .. note:: - In the ANSI I/O module, ``mpsioan.c``, this calls ``fopen`` on - the file named by the environment variable + In the ANSI I/O module, ``mpsioan.c``, this calls + :c:func:`fopen` on the file named by the environment variable :envvar:`MPS_TELEMETRY_FILENAME`. @@ -134,7 +134,8 @@ I/O module .. note:: - In the ANSI I/O module, ``mpsioan.c``, this calls ``fclose``. + In the ANSI I/O module, ``mpsioan.c``, this calls + :c:func:`fclose`. .. c:function:: mps_res_t mps_io_write(mps_io_t io, void *buf, size_t size) @@ -153,7 +154,8 @@ I/O module .. note:: - In the ANSI I/O module, ``mpsioan.c``, this calls ``fwrite``. + In the ANSI I/O module, ``mpsioan.c``, this calls + :c:func:`fwrite`. .. c:function:: mps_res_t mps_io_flush(mps_io_t io) @@ -177,7 +179,8 @@ I/O module .. note:: - In the ANSI I/O module, ``mpsioan.c``, this calls ``fflush``. + In the ANSI I/O module, ``mpsioan.c``, this calls + :c:func:`fflush`. .. index:: @@ -246,9 +249,9 @@ Library module In the ANSI Library module, ``mpsliban.c``, this reports the failure using ``fprintf(stderr, "...%s...", message)`` and, in the :term:`cool` :term:`variety`, terminates the program by - calling ``abort``. You can change this behaviour with - :c:func:`mps_lib_assert_fail_install`. For a discussion of - the default behaviour, see :ref:`topic-error-assertion-handling`. + calling :c:func:`abort`. You can change this behaviour with + :c:func:`mps_lib_assert_fail_install`. For a discussion of the + default behaviour, see :ref:`topic-error-assertion-handling`. .. c:function:: extern mps_lib_assert_fail_t mps_lib_assert_fail_install(mps_lib_assert_fail_t handler) @@ -292,13 +295,13 @@ Library module :c:func:`mps_lib_get_EOF` if not. This function is intended to have the same semantics as the - ``fputc`` function of the ANSI C Standard (:ref:`ISO/IEC 9899:1990 - ` §7.11.7.3). + :c:func:`fputc` function of the ANSI C Standard (:ref:`ISO/IEC + 9899:1990 ` §7.11.7.3). .. note:: In the ANSI Library module, ``mpsliban.c``, this is a simple - wrapper around ``fputc``. + wrapper around :c:func:`fputc`. .. c:function:: int mps_lib_fputs(const char *s, mps_lib_FILE *stream) @@ -310,8 +313,8 @@ Library module ``stream`` is the stream. This function is intended to have the same semantics as the - ``fputs`` function of the ANSI C Standard (:ref:`ISO/IEC 9899:1990 - ` §7.11.7.4). + :c:func:`fputs` function of the ANSI C Standard (:ref:`ISO/IEC + 9899:1990 ` §7.11.7.4). Return a non-negative integer if successful, or :c:func:`mps_lib_get_EOF` if not. @@ -319,7 +322,7 @@ Library module .. note:: In the ANSI Library module, ``mpsliban.c``, this is a simple - wrapper around ``fputs``. + wrapper around :c:func:`fputs`. .. c:function:: int mps_lib_get_EOF(void) @@ -367,7 +370,7 @@ Library module .. c:function:: int mps_lib_memcmp(const void *s1, const void *s2, size_t n) A :term:`plinth` function similar to the standard :term:`C` - function ``memcmp``. + function :c:func:`memcmp`. ``s1`` and ``s2`` point to :term:`blocks` of memory to be compared. @@ -379,19 +382,19 @@ Library module equal to, or less than the block pointed to by ``s2``. This function is intended to have the same semantics as the - ``memcmp`` function of the ANSI C Standard (:ref:`ISO/IEC + :c:func:`memcmp` function of the ANSI C Standard (:ref:`ISO/IEC 9899:1990 ` §7.11.4.1). .. note:: In the ANSI Library module, ``mpsliban.c``, this is a simple - wrapper around ``memcmp``. + wrapper around :c:func:`memcmp`. .. c:function:: void *mps_lib_memcpy(void *dest, const void *source, size_t n) A :term:`plinth` function similar to the standard :term:`C` - function ``memcpy``. + function :c:func:`memcpy`. ``dest`` points to the destination. @@ -402,7 +405,7 @@ Library module Returns ``dest``. This function is intended to have the same semantics as the - ``memcpy`` function of the ANSI C Standard (:ref:`ISO/IEC + :c:func:`memcpy` function of the ANSI C Standard (:ref:`ISO/IEC 9899:1990 ` §7.11.2.1). The MPS never passes overlapping blocks to @@ -411,13 +414,13 @@ Library module .. note:: In the ANSI Library module, ``mpsliban.c``, this is a simple - wrapper around ``memcpy``. + wrapper around :c:func:`memcpy`. .. c:function:: void *mps_lib_memset(void *s, int c, size_t n) A :term:`plinth` function similar to the standard :term:`C` - function ``memset``. + function :c:func:`memset`. ``s`` points to the :term:`block` to fill with the byte ``c``. @@ -428,13 +431,13 @@ Library module Returns ``s``. This function is intended to have the same semantics as the - ``memset`` function of the ANSI C Standard (:ref:`ISO/IEC + :c:func:`memset` function of the ANSI C Standard (:ref:`ISO/IEC 9899:1990 ` §7.11.6.1). .. note:: In the ANSI Library module, ``mpsliban.c``, this is a simple - wrapper around ``memset``. + wrapper around :c:func:`memset`. .. note:: diff --git a/mps/manual/source/topic/root.rst b/mps/manual/source/topic/root.rst index 823996f0d0e..28e2d08ada3 100644 --- a/mps/manual/source/topic/root.rst +++ b/mps/manual/source/topic/root.rst @@ -37,15 +37,17 @@ You can register a root at any time by calling one of the no two roots may overlap (that is, each reference is :term:`fixed` by at most one root). Roots may be: -1. on the program's :term:`control stack`; +1. in :term:`registers`; -2. in the program's static data; +2. on the program's :term:`control stack`; -3. in :term:`heap` not managed by the MPS (provided that you destroy +3. in the program's static data; + +4. in :term:`heap` not managed by the MPS (provided that you destroy the root before freeing it; see :ref:`the Scheme interpreter's global symbol table ` for an example); -4. in :term:`manually managed ` pools +5. in :term:`manually managed ` pools (provided that you remove the root before freeing it). Roots must not be in memory that is subject to :term:`garbage @@ -99,7 +101,7 @@ scan it for references: table of :term:`tagged references`; 5. :c:func:`mps_root_create_reg` if the root consists of the - registers and control stack of a thread. See + :term:`registers` and :term:`control stack` of a thread. See :ref:`topic-root-thread` below.