mirror of
git://git.sv.gnu.org/emacs.git
synced 2025-12-26 15:21:51 -08:00
Documentation corrections and improvements.
Copied from Perforce Change: 187479 ServerID: perforce.ravenbrook.com
This commit is contained in:
Gareth Rees
parent
4ff7916121
commit
d5ca3dd653
7 changed files with 76 additions and 75 deletions
|
|
@ -108,7 +108,7 @@ MV interface
|
|||
class.
|
||||
|
||||
When creating a debugging MV pool, :c:func:`mps_pool_create_k`
|
||||
takes four optional keyword arguments: :c:macro:`MPS_KEY_ALIGN`,
|
||||
takes five optional keyword arguments: :c:macro:`MPS_KEY_ALIGN`,
|
||||
:c:macro:`MPS_KEY_EXTEND_SIZE`, :c:macro:`MPS_KEY_MEAN_SIZE`,
|
||||
:c:macro:`MPS_KEY_MAX_SIZE` are as described above, and
|
||||
:c:macro:`MPS_KEY_POOL_DEBUG_OPTIONS` specifies the debugging
|
||||
|
|
|
|||
|
|
@ -215,7 +215,8 @@ is thus::
|
|||
size_t aligned_size = ALIGN(size); /* see note 1 */
|
||||
do {
|
||||
mps_res_t res = mps_reserve(&p, ap, aligned_size);
|
||||
if (res != MPS_RES_OK) /* handle the error */;
|
||||
if (res != MPS_RES_OK)
|
||||
/* handle the error */;
|
||||
/* p is now an ambiguous reference to the reserved block */
|
||||
obj = p;
|
||||
/* initialize obj */
|
||||
|
|
|
|||
|
|
@ -218,7 +218,7 @@ Deprecated in version 1.112
|
|||
|
||||
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
|
||||
mps_pool_class_t mps_class_ams_debug(),
|
||||
mps_pool_debug_option_s pool_debug_options,
|
||||
mps_pool_debug_option_s *pool_debug_options,
|
||||
mps_fmt_t format,
|
||||
mps_chain_t chain,
|
||||
mps_bool_t ams_support_ambiguous)
|
||||
|
|
@ -268,7 +268,7 @@ Deprecated in version 1.112
|
|||
|
||||
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
|
||||
mps_pool_class_t mps_class_mv_debug(),
|
||||
mps_pool_debug_option_s pool_debug_options,
|
||||
mps_pool_debug_option_s *pool_debug_options,
|
||||
size_t extend_by,
|
||||
size_t mean_size,
|
||||
size_t max_size)
|
||||
|
|
@ -299,7 +299,7 @@ Deprecated in version 1.112
|
|||
|
||||
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
|
||||
mps_pool_class_t mps_class_mvff_debug(),
|
||||
mps_pool_debug_option_s pool_debug_options,
|
||||
mps_pool_debug_option_s *pool_debug_options,
|
||||
size_t extend_by,
|
||||
size_t mean_size,
|
||||
mps_align_t align,
|
||||
|
|
|
|||
|
|
@ -76,7 +76,8 @@ Result codes
|
|||
A :term:`result code` indicating that an operation could not be
|
||||
completed as requested without exceeding the :term:`commit limit`.
|
||||
|
||||
You need to deallocate something to make more space, or increase
|
||||
You need to deallocate something or allow the :term:`garbage
|
||||
collector` to reclaim something, to make more space, or increase
|
||||
the commit limit by calling :c:func:`mps_arena_commit_limit_set`.
|
||||
|
||||
|
||||
|
|
@ -109,7 +110,7 @@ Result codes
|
|||
completed because there wasn't enough memory available.
|
||||
|
||||
You need to deallocate something or allow the :term:`garbage
|
||||
collector` to reclaim something to free enough memory, or expand
|
||||
collector` to reclaim something to free enough memory, or extend
|
||||
the :term:`arena` (if you're using an arena for which that does
|
||||
not happen automatically).
|
||||
|
||||
|
|
@ -148,19 +149,16 @@ Result codes
|
|||
|
||||
A :term:`result code` indicating that an operation could not be
|
||||
completed as requested because the MPS could not obtain a needed
|
||||
resource. The resource in question depends on the operation.
|
||||
resource. The resource in question depends on the operation, but
|
||||
it can be returned when the MPS runs out of :term:`address space`.
|
||||
If this happens, you need to reclaim memory within your process
|
||||
(as for the result code :c:macro:`MPS_RES_MEMORY`).
|
||||
|
||||
Two special cases have their own result codes: when the MPS runs
|
||||
out of committed memory, it returns :c:macro:`MPS_RES_MEMORY`, and
|
||||
when it cannot proceed without exceeding the :term:`commit limit`,
|
||||
it returns :c:macro:`MPS_RES_COMMIT_LIMIT`.
|
||||
|
||||
This result code can be returned when the MPS runs out of
|
||||
:term:`virtual memory`. If this happens, you need to reclaim
|
||||
memory within your process (as for the result code
|
||||
:c:macro:`MPS_RES_MEMORY`), or terminate other processes running
|
||||
on the same machine.
|
||||
|
||||
|
||||
.. c:macro:: MPS_RES_UNIMPL
|
||||
|
||||
|
|
@ -277,8 +275,8 @@ this documentation.
|
|||
``lockw3.c: lock->claims == 0``
|
||||
|
||||
The client program has made a re-entrant call into the MPS. Look
|
||||
at the backtrace to see what it was. Common culprits are
|
||||
:term:`format methods` and :term:`stepper functions`.
|
||||
at the backtrace to see what it was. Common culprits are signal
|
||||
handlers, :term:`format methods` and :term:`stepper functions`.
|
||||
|
||||
|
||||
``locus.c: chain->activeTraces == TraceSetEMPTY``
|
||||
|
|
@ -307,11 +305,11 @@ this documentation.
|
|||
|
||||
``ring.c: ring->next == ring``
|
||||
|
||||
The client program destroyed an object without having destroyed
|
||||
all the objects that it owns first. For example, it destroyed an
|
||||
arena without first destroying all pools in that arena, or it
|
||||
destroyed a pool without first destroying all allocation points
|
||||
created on that pool.
|
||||
The client program destroyed an MPS data structure without having
|
||||
destroyed all the data structures that it owns first. For example,
|
||||
it destroyed an arena without first destroying all pools in that
|
||||
arena, or it destroyed a pool without first destroying all
|
||||
allocation points created on that pool.
|
||||
|
||||
|
||||
``trace.c: ss->rank < RankEXACT``
|
||||
|
|
@ -320,7 +318,7 @@ this documentation.
|
|||
for finalization, and then continued to run the garbage collector.
|
||||
See :ref:`topic-finalization-cautions` under
|
||||
:ref:`topic-finalization`, which says, "You must destroy these
|
||||
pools by following the “safe tear-down” procedure described under
|
||||
pools by following the ‘safe tear-down’ procedure described under
|
||||
:c:func:`mps_pool_destroy`."
|
||||
|
||||
|
||||
|
|
@ -330,8 +328,8 @@ this documentation.
|
|||
reference to an object that moved. See
|
||||
:ref:`topic-scanning-protocol`, which says, "If :c:func:`MPS_FIX2`
|
||||
returns :c:macro:`MPS_RES_OK`, it may have updated the reference.
|
||||
If necessary, make sure that the updated reference is stored back
|
||||
to the region being scanned."
|
||||
Make sure that the updated reference is stored back to the region
|
||||
being scanned."
|
||||
|
||||
|
||||
.. index::
|
||||
|
|
@ -341,11 +339,11 @@ this documentation.
|
|||
Varieties
|
||||
---------
|
||||
|
||||
The MPS has three behaviours with respect to internal checking and
|
||||
:ref:`telemetry <topic-telemetry>`, which need to be selected at
|
||||
compile time, by defining one of the following preprocessor
|
||||
constants. If none is specified then :c:macro:`CONFIG_VAR_HOT` is the
|
||||
default.
|
||||
The MPS has three *varieties* which have different levels of internal
|
||||
checking and :ref:`telemetry <topic-telemetry>`. The variety can be
|
||||
selected at compile time, by defining one of the following
|
||||
preprocessor constants. If none is specified then
|
||||
:c:macro:`CONFIG_VAR_HOT` is the default.
|
||||
|
||||
|
||||
.. index::
|
||||
|
|
@ -354,7 +352,7 @@ default.
|
|||
|
||||
.. c:macro:: CONFIG_VAR_COOL
|
||||
|
||||
The cool variety is intended for development and testing.
|
||||
The *cool variety* is intended for development and testing.
|
||||
|
||||
All functions check the consistency of their data structures and may
|
||||
assert, including functions on the :term:`critical path`.
|
||||
|
|
@ -372,7 +370,7 @@ default.
|
|||
|
||||
.. c:macro:: CONFIG_VAR_HOT
|
||||
|
||||
The hot variety is intended for production and deployment.
|
||||
The *hot variety* is intended for production and deployment.
|
||||
|
||||
Some functions check the consistency of their data structures and
|
||||
may assert, namely those not on the :term:`critical path`. However,
|
||||
|
|
@ -389,7 +387,7 @@ default.
|
|||
|
||||
.. c:macro:: CONFIG_VAR_RASH
|
||||
|
||||
The rash variety is intended for mature integrations, or for
|
||||
The *rash variety* is intended for mature integrations, or for
|
||||
developers who like living dangerously.
|
||||
|
||||
No functions check the consistency of their data structures and
|
||||
|
|
|
|||
|
|
@ -208,7 +208,8 @@ Instead, we recommend this approach::
|
|||
mps_addr_t p;
|
||||
struct foo *fp;
|
||||
res = mps_alloc(&p, pool, sizeof(struct foo));
|
||||
if(res) /* handle error case */;
|
||||
if (res != MPS_RES_OK)
|
||||
/* handle error case */;
|
||||
fp = p;
|
||||
|
||||
This has defined behaviour because conversion from ``void *`` to any
|
||||
|
|
|
|||
|
|
@ -82,43 +82,43 @@ now :c:macro:`MPS_KEY_ARGS_END`.
|
|||
The type of :term:`keyword argument` keys. Must take one of the
|
||||
following values:
|
||||
|
||||
======================================== ====================================================== ==========================================================
|
||||
Keyword Type & field in ``arg.val`` See
|
||||
======================================== ====================================================== ==========================================================
|
||||
:c:macro:`MPS_KEY_ARGS_END` *none* *see above*
|
||||
:c:macro:`MPS_KEY_ALIGN` :c:type:`mps_align_t` ``align`` :c:func:`mps_class_mv`, :c:func:`mps_class_mvff`, :c:func:`mps_class_mvt`
|
||||
:c:macro:`MPS_KEY_AMS_SUPPORT_AMBIGUOUS` :c:type:`mps_bool_t` ``b`` :c:func:`mps_class_ams`
|
||||
:c:macro:`MPS_KEY_ARENA_CL_BASE` :c:type:`mps_addr_t` ``addr`` :c:func:`mps_arena_class_cl`
|
||||
:c:macro:`MPS_KEY_ARENA_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_arena_class_vm`, :c:func:`mps_arena_class_cl`
|
||||
:c:macro:`MPS_KEY_ARENA_GRAIN_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_arena_class_vm`, :c:func:`mps_arena_class_cl`
|
||||
:c:macro:`MPS_KEY_AWL_FIND_DEPENDENT` ``void *(*)(void *)`` ``addr_method`` :c:func:`mps_class_awl`
|
||||
:c:macro:`MPS_KEY_CHAIN` :c:type:`mps_chain_t` ``chain`` :c:func:`mps_class_amc`, :c:func:`mps_class_amcz`, :c:func:`mps_class_ams`, :c:func:`mps_class_awl`, :c:func:`mps_class_lo`
|
||||
:c:macro:`MPS_KEY_EXTEND_BY` :c:type:`size_t` ``size`` :c:func:`mps_class_amc`, :c:func:`mps_class_amcz`, :c:func:`mps_class_mfs`, :c:func:`mps_class_mv`, :c:func:`mps_class_mvff`
|
||||
:c:macro:`MPS_KEY_FMT_ALIGN` :c:type:`mps_align_t` ``align`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_CLASS` :c:type:`mps_fmt_class_t` ``fmt_class`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_FWD` :c:type:`mps_fmt_fwd_t` ``fmt_fwd`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_HEADER_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_ISFWD` :c:type:`mps_fmt_isfwd_t` ``fmt_isfwd`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_PAD` :c:type:`mps_fmt_pad_t` ``fmt_pad`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_SCAN` :c:type:`mps_fmt_scan_t` ``fmt_scan`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_SKIP` :c:type:`mps_fmt_skip_t` ``fmt_skip`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FORMAT` :c:type:`mps_fmt_t` ``format`` :c:func:`mps_class_amc`, :c:func:`mps_class_amcz`, :c:func:`mps_class_ams`, :c:func:`mps_class_awl`, :c:func:`mps_class_lo` , :c:func:`mps_class_snc`
|
||||
:c:macro:`MPS_KEY_GEN` :c:type:`unsigned` ``u`` :c:func:`mps_class_ams`, :c:func:`mps_class_awl`, :c:func:`mps_class_lo`
|
||||
:c:macro:`MPS_KEY_INTERIOR` :c:type:`mps_bool_t` ``b`` :c:func:`mps_class_amc`, :c:func:`mps_class_amcz`
|
||||
:c:macro:`MPS_KEY_MAX_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_class_mv`
|
||||
:c:macro:`MPS_KEY_MEAN_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_class_mv`, :c:func:`mps_class_mvt`, :c:func:`mps_class_mvff`
|
||||
:c:macro:`MPS_KEY_MFS_UNIT_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_class_mfs`
|
||||
:c:macro:`MPS_KEY_MIN_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_class_mvt`
|
||||
:c:macro:`MPS_KEY_MVFF_ARENA_HIGH` :c:type:`mps_bool_t` ``b`` :c:func:`mps_class_mvff`
|
||||
:c:macro:`MPS_KEY_MVFF_FIRST_FIT` :c:type:`mps_bool_t` ``b`` :c:func:`mps_class_mvff`
|
||||
:c:macro:`MPS_KEY_MVFF_SLOT_HIGH` :c:type:`mps_bool_t` ``b`` :c:func:`mps_class_mvff`
|
||||
:c:macro:`MPS_KEY_MVT_FRAG_LIMIT` :c:type:`mps_word_t` ``count`` :c:func:`mps_class_mvt`
|
||||
:c:macro:`MPS_KEY_MVT_RESERVE_DEPTH` :c:type:`mps_word_t` ``count`` :c:func:`mps_class_mvt`
|
||||
:c:macro:`MPS_KEY_POOL_DEBUG_OPTIONS` ``mps_pool_debug_options_s *`` ``pool_debug_options`` :c:func:`mps_class_ams_debug`, :c:func:`mps_class_mv_debug`, :c:func:`mps_class_mvff_debug`
|
||||
:c:macro:`MPS_KEY_RANK` :c:type:`mps_rank_t` ``rank`` :c:func:`mps_class_ams`, :c:func:`mps_class_awl`, :c:func:`mps_class_snc`
|
||||
:c:macro:`MPS_KEY_SPARE` :c:type:`double` ``d`` :c:func:`mps_class_mvff`
|
||||
:c:macro:`MPS_KEY_VMW3_TOP_DOWN` :c:type:`mps_bool_t` ``b`` :c:func:`mps_arena_class_vm`
|
||||
======================================== ====================================================== ==========================================================
|
||||
======================================== ========================================================= ==========================================================
|
||||
Keyword Type & field in ``arg.val`` See
|
||||
======================================== ========================================================= ==========================================================
|
||||
:c:macro:`MPS_KEY_ARGS_END` *none* *see above*
|
||||
:c:macro:`MPS_KEY_ALIGN` :c:type:`mps_align_t` ``align`` :c:func:`mps_class_mv`, :c:func:`mps_class_mvff`, :c:func:`mps_class_mvt`
|
||||
:c:macro:`MPS_KEY_AMS_SUPPORT_AMBIGUOUS` :c:type:`mps_bool_t` ``b`` :c:func:`mps_class_ams`
|
||||
:c:macro:`MPS_KEY_ARENA_CL_BASE` :c:type:`mps_addr_t` ``addr`` :c:func:`mps_arena_class_cl`
|
||||
:c:macro:`MPS_KEY_ARENA_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_arena_class_vm`, :c:func:`mps_arena_class_cl`
|
||||
:c:macro:`MPS_KEY_ARENA_GRAIN_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_arena_class_vm`, :c:func:`mps_arena_class_cl`
|
||||
:c:macro:`MPS_KEY_AWL_FIND_DEPENDENT` ``void *(*)(void *)`` ``addr_method`` :c:func:`mps_class_awl`
|
||||
:c:macro:`MPS_KEY_CHAIN` :c:type:`mps_chain_t` ``chain`` :c:func:`mps_class_amc`, :c:func:`mps_class_amcz`, :c:func:`mps_class_ams`, :c:func:`mps_class_awl`, :c:func:`mps_class_lo`
|
||||
:c:macro:`MPS_KEY_EXTEND_BY` :c:type:`size_t` ``size`` :c:func:`mps_class_amc`, :c:func:`mps_class_amcz`, :c:func:`mps_class_mfs`, :c:func:`mps_class_mv`, :c:func:`mps_class_mvff`
|
||||
:c:macro:`MPS_KEY_FMT_ALIGN` :c:type:`mps_align_t` ``align`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_CLASS` :c:type:`mps_fmt_class_t` ``fmt_class`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_FWD` :c:type:`mps_fmt_fwd_t` ``fmt_fwd`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_HEADER_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_ISFWD` :c:type:`mps_fmt_isfwd_t` ``fmt_isfwd`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_PAD` :c:type:`mps_fmt_pad_t` ``fmt_pad`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_SCAN` :c:type:`mps_fmt_scan_t` ``fmt_scan`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FMT_SKIP` :c:type:`mps_fmt_skip_t` ``fmt_skip`` :c:func:`mps_fmt_create_k`
|
||||
:c:macro:`MPS_KEY_FORMAT` :c:type:`mps_fmt_t` ``format`` :c:func:`mps_class_amc`, :c:func:`mps_class_amcz`, :c:func:`mps_class_ams`, :c:func:`mps_class_awl`, :c:func:`mps_class_lo` , :c:func:`mps_class_snc`
|
||||
:c:macro:`MPS_KEY_GEN` :c:type:`unsigned` ``u`` :c:func:`mps_class_ams`, :c:func:`mps_class_awl`, :c:func:`mps_class_lo`
|
||||
:c:macro:`MPS_KEY_INTERIOR` :c:type:`mps_bool_t` ``b`` :c:func:`mps_class_amc`, :c:func:`mps_class_amcz`
|
||||
:c:macro:`MPS_KEY_MAX_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_class_mv`
|
||||
:c:macro:`MPS_KEY_MEAN_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_class_mv`, :c:func:`mps_class_mvt`, :c:func:`mps_class_mvff`
|
||||
:c:macro:`MPS_KEY_MFS_UNIT_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_class_mfs`
|
||||
:c:macro:`MPS_KEY_MIN_SIZE` :c:type:`size_t` ``size`` :c:func:`mps_class_mvt`
|
||||
:c:macro:`MPS_KEY_MVFF_ARENA_HIGH` :c:type:`mps_bool_t` ``b`` :c:func:`mps_class_mvff`
|
||||
:c:macro:`MPS_KEY_MVFF_FIRST_FIT` :c:type:`mps_bool_t` ``b`` :c:func:`mps_class_mvff`
|
||||
:c:macro:`MPS_KEY_MVFF_SLOT_HIGH` :c:type:`mps_bool_t` ``b`` :c:func:`mps_class_mvff`
|
||||
:c:macro:`MPS_KEY_MVT_FRAG_LIMIT` :c:type:`mps_word_t` ``count`` :c:func:`mps_class_mvt`
|
||||
:c:macro:`MPS_KEY_MVT_RESERVE_DEPTH` :c:type:`mps_word_t` ``count`` :c:func:`mps_class_mvt`
|
||||
:c:macro:`MPS_KEY_POOL_DEBUG_OPTIONS` :c:type:`mps_pool_debug_option_s` ``*pool_debug_options`` :c:func:`mps_class_ams_debug`, :c:func:`mps_class_mv_debug`, :c:func:`mps_class_mvff_debug`
|
||||
:c:macro:`MPS_KEY_RANK` :c:type:`mps_rank_t` ``rank`` :c:func:`mps_class_ams`, :c:func:`mps_class_awl`, :c:func:`mps_class_snc`
|
||||
:c:macro:`MPS_KEY_SPARE` :c:type:`double` ``d`` :c:func:`mps_class_mvff`
|
||||
:c:macro:`MPS_KEY_VMW3_TOP_DOWN` :c:type:`mps_bool_t` ``b`` :c:func:`mps_arena_class_vm`
|
||||
======================================== ========================================================= ==========================================================
|
||||
|
||||
|
||||
.. c:function:: MPS_ARGS_BEGIN(args)
|
||||
|
|
|
|||
|
|
@ -279,11 +279,12 @@ Then check that the "smoke tests" pass, by running::
|
|||
|
||||
Most or all of the test cases should pass at this point. If you're
|
||||
using the generic threading implementation, then the multi-threaded
|
||||
test cases ``amcssth`` and ``awlutth`` are expected to fail. If you're
|
||||
using the generic lock implementation, then the lock utilization test
|
||||
case ``lockut`` is expected to fail. If you're using the generic
|
||||
memory protection implementation, performance is expected to be poor,
|
||||
as it does not support incremental collection.
|
||||
test cases are expected to fail. If you're using the generic lock
|
||||
implementation, then the lock utilization test case ``lockut`` is
|
||||
expected to fail. If you're using the generic memory protection
|
||||
implementation, all the tests that rely on incremental collection are
|
||||
expected to fail. See ``tool/testcases.txt`` for a database of test
|
||||
cases and the configurations in which they are expected to pass.
|
||||
|
||||
Now that there is a working system to build on, porting the necessary
|
||||
modules to the new platform can be done incrementally. It's a good
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue