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.