mirror of
git://git.sv.gnu.org/emacs.git
synced 2026-03-26 08:41:47 -07:00
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
This commit is contained in:
Gareth Rees
parent
273bfaa70b
commit
aa71bfe1bc
6 changed files with 89 additions and 64 deletions
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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 <incremental garbage
|
||||
collection>`: 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?
|
||||
|
|
|
|||
|
|
@ -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 <automatic memory management>`
|
||||
: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
|
||||
|
|
|
|||
|
|
@ -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 <contact>`.
|
||||
|
||||
|
||||
.. 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<ISO90>` §7.11.7.3).
|
||||
:c:func:`fputc` function of the ANSI C Standard (:ref:`ISO/IEC
|
||||
9899:1990 <ISO90>` §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
|
||||
<ISO90>` §7.11.7.4).
|
||||
:c:func:`fputs` function of the ANSI C Standard (:ref:`ISO/IEC
|
||||
9899:1990 <ISO90>` §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 <ISO90>` §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 <ISO90>` §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 <ISO90>` §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::
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <guide-lang-roots-rehash>` for an example);
|
||||
|
||||
4. in :term:`manually managed <manual memory management>` pools
|
||||
5. in :term:`manually managed <manual memory management>` 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.
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue