mirror of
git://git.sv.gnu.org/emacs.git
synced 2025-12-26 15:21:51 -08:00
Miscellaneous minor edits.
Copied from Perforce Change: 179977 ServerID: perforce.ravenbrook.com
This commit is contained in:
Gareth Rees
parent
88bcefa962
commit
76cf7ddd4b
15 changed files with 99 additions and 93 deletions
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -128,6 +128,10 @@ Memory Management Glossary: D
|
|||
|
||||
.. bibref:: [DB76]_.
|
||||
|
||||
dependent object
|
||||
|
||||
.. mps:specific:: ??
|
||||
|
||||
derived pointer
|
||||
|
||||
.. see:: :term:`interior pointer`.
|
||||
|
|
|
|||
|
|
@ -237,10 +237,12 @@ Memory Management Glossary: F
|
|||
that foreign code is not passed the address of a block in
|
||||
a :term:`moving <moving memory manager>` :term:`pools
|
||||
<pool>`, 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -22,8 +22,8 @@ Memory Management Glossary: O
|
|||
|
||||
.. mps:specific::
|
||||
|
||||
The MPS documentation reserves the term *object* for
|
||||
:term:`formatted objects <formatted object>` only. For
|
||||
The MPS documentation generally reserves the term *object*
|
||||
for :term:`formatted objects <formatted object>`. For
|
||||
units of allocation in general, it uses the term
|
||||
:term:`block`.
|
||||
|
||||
|
|
|
|||
|
|
@ -189,13 +189,14 @@ Memory Management Glossary: R
|
|||
with :term:`headers <in-band header>` 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 <tagged reference>`), 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 <tagged
|
||||
reference>`), 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <formatted object>`
|
||||
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 <address>`, and so appear in
|
||||
the :term:`telemetry stream` attached to events concerning
|
||||
those addresses. See :ref:`topic-telemetry`.
|
||||
|
||||
telemetry stream
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<reclaim>`. And that task falls to the :term:`garbage collector`.
|
||||
<reclaim>`. To prove that they are dead, we need a :term:`tracing
|
||||
<trace>` :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 <arena>`, which request
|
||||
memory from (and return it to) the operating system, and :term:`pools
|
||||
<pool>`, which allocate blocks of memory on behalf of your program.
|
||||
<pool>`, 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;
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <weak hash table>`.
|
||||
|
|
@ -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 <scan>` 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 <scan>` 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
|
||||
|
|
|
|||
|
|
@ -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 }};
|
||||
|
|
|
|||
|
|
@ -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 <guide-lang-scan>`) or multiple footnotes (as
|
||||
:ref:`here <pool-properties>`) 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?
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
------ ---------------- -----------------------
|
||||
|
|
|
|||
|
|
@ -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 <https://info.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo/mmdoc/doc/mps/ref-man/concepts/>
|
||||
|
||||
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 <https://info.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo/mmdoc/doc/mps/guide/interface/>
|
||||
|
||||
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 <https://info.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo/mmdoc/doc/mps/guide/appendix/plinth/>
|
||||
|
||||
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 <https://info.ravenbrook.com/project/mps/master/design/io/>
|
||||
|
||||
|
||||
Declared in ``mpsio.h``
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue