From 378fe1723cb6e425e38af067ef8d820bd3885f4e Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Sun, 6 Sep 2020 20:41:43 +0100 Subject: [PATCH] Minor documentation improvements. * Remove references to MV pool class. * Typo: "indentifier" for "identifier". * Use :py:func: to format a Python function. * Switch out broken link for LinuxThreads. * Remove doubtful claim about "useful to have two active arenas". * Document how to have unlimited commited memory. * Fix cross-reference to mps_arena_commit_limit(). * Clarify what format methods are allowed to access. * Complete list of functions callable by format methods. --- mps/design/poolmvt.txt | 6 ------ mps/manual/source/glossary/t.rst | 2 +- mps/manual/source/release.rst | 8 ++++---- mps/manual/source/topic/arena.rst | 12 +++++++----- mps/manual/source/topic/format.rst | 18 +++++++++--------- mps/manual/source/topic/keyword.rst | 2 +- 6 files changed, 22 insertions(+), 26 deletions(-) diff --git a/mps/design/poolmvt.txt b/mps/design/poolmvt.txt index 18d3da0945d..4857e9ed9be 100644 --- a/mps/design/poolmvt.txt +++ b/mps/design/poolmvt.txt @@ -109,8 +109,6 @@ _`.abbr.cbs`: CBS = Coalescing Block Structure _`.abbr.mps`: MPS = Memory Pool System -_`.abbr.mv`: MV = Manual-Variable - _`.abbr.ps`: PS = PostScript @@ -954,10 +952,6 @@ _`.test.component`: Components `.impl.c.splay`_, `.impl.c.cbs`_, and `.impl.c.abq`_ will be subjected to individual component tests to verify their functionality. -_`.test.regression`: All tests applied to MV (design.mps.poolmv) and -EPDL (design.mps.poolepdl(0)) will be applied to poolmvt to ensure -that mvt is at least as functional as the pools it is replacing. - _`.test.qa`: Once poolmvt is integrated into the MPS, the standard MPS QA tests will be applied to poolmvt prior to each release. diff --git a/mps/manual/source/glossary/t.rst b/mps/manual/source/glossary/t.rst index 7111e83863f..420a0b42cf7 100644 --- a/mps/manual/source/glossary/t.rst +++ b/mps/manual/source/glossary/t.rst @@ -108,7 +108,7 @@ Memory Management Glossary: T .. mps:specific:: - An indentifier representing a string, returned from + An identifier representing a string, returned from :c:func:`mps_telemetry_intern`, that can be associated with certain :term:`addresses`, and so appear in the :term:`telemetry stream` attached to events concerning diff --git a/mps/manual/source/release.rst b/mps/manual/source/release.rst index f6cfc4d8acc..a16ccc1ca75 100644 --- a/mps/manual/source/release.rst +++ b/mps/manual/source/release.rst @@ -51,10 +51,10 @@ Interface changes #. The format of the :term:`telemetry stream` has changed: Booleans are no longer packed into bitfields, but are emitted as unsigned bytes. This makes it possible to decode the telemetry stream using - the Python function |struct|_. + the Python function |unpack|_. - .. |struct| replace:: ``struct.unpack`` - .. _struct: https://docs.python.org/3/library/struct.html#struct.unpack + .. |unpack| replace:: :py:func:`struct.unpack` + .. _unpack: https://docs.python.org/3/library/struct.html#struct.unpack Other changes @@ -149,7 +149,7 @@ New features longer convenient to test against them.) See :ref:`guide-overview-platforms`. - .. _LinuxThreads: http://pauillac.inria.fr/~xleroy/linuxthreads/ + .. _LinuxThreads: https://en.wikipedia.org/wiki/LinuxThreads #. New function :c:func:`mps_arena_postmortem` assists with postmortem debugging. diff --git a/mps/manual/source/topic/arena.rst b/mps/manual/source/topic/arena.rst index 8ef2ed22407..7c48ebee2b1 100644 --- a/mps/manual/source/topic/arena.rst +++ b/mps/manual/source/topic/arena.rst @@ -36,10 +36,8 @@ other. .. note:: The MPS allows creation of multiple arenas, but you would only do - this in unusual circumstances. It might be useful to have two - active arenas and to try different things out in them, or you - might be in the process of integrating two pieces of software that - each independently uses the MPS. + this in unusual circumstances, for example during the integration + of two pieces of software that each independently uses the MPS. Arenas do not normally interact, but they compete with each other for resources, and references from one arena to another are not @@ -389,7 +387,11 @@ Arena properties Returns :c:macro:`MPS_RES_OK` if successful, or another :term:`result code` if not. - See :c:func:`mps_arena_spare` for details. + To effectively remove any commit limit, pass the maximum value of + the :c:type:`size_t` type for the :c:var:`limit` argument, that + is, ``((size_t)-1)``, or :c:macro:`SIZE_MAX` in C99 or later. + + See :c:func:`mps_arena_commit_limit` for details. .. c:function:: size_t mps_arena_committed(mps_arena_t arena) diff --git a/mps/manual/source/topic/format.rst b/mps/manual/source/topic/format.rst index 1ee992fbd4e..91f1e0035e3 100644 --- a/mps/manual/source/topic/format.rst +++ b/mps/manual/source/topic/format.rst @@ -244,12 +244,15 @@ Cautions a. call library code; - b. perform a non-local exit (for example, by throwing an exception, + b. access MPS-managed memory in pools that protect their contents; + + c. perform a non-local exit (for example, by throwing an exception, or calling :c:func:`longjmp`); - c. call any functions or macros in the MPS other than the fix - macros :c:func:`MPS_FIX1`, :c:func:`MPS_FIX12`, and - :c:func:`MPS_FIX2`. + d. call any functions or macros in the MPS other than + :c:func:`MPS_SCAN_BEGIN`, :c:func:`MPS_SCAN_END`, + :c:func:`MPS_FIX1`, :c:func:`MPS_FIX12`, :c:func:`MPS_FIX2`, and + :c:func:`MPS_FIX_CALL`. It's permissible to call other functions in the client program, but see :c:func:`MPS_FIX_CALL` for a restriction on passing the @@ -260,12 +263,9 @@ Cautions a. memory inside the object or block that they have been asked to look at; - b. memory managed by the MPS that is in pools that do not protect - their contents; + b. MPS-managed memory in pools that do not protect their contents; - c. memory not managed by the MPS; - - They must not access other memory managed by the MPS. + c. memory not managed by the MPS. .. index:: diff --git a/mps/manual/source/topic/keyword.rst b/mps/manual/source/topic/keyword.rst index 7dadee60b66..863530172a3 100644 --- a/mps/manual/source/topic/keyword.rst +++ b/mps/manual/source/topic/keyword.rst @@ -115,7 +115,7 @@ now :c:macro:`MPS_KEY_ARGS_END`. :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_PAUSE_TIME` :c:type:`double` ``d`` :c:func:`mps_arena_class_vm`, :c:func:`mps_arena_class_cl` - :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_POOL_DEBUG_OPTIONS` :c:type:`mps_pool_debug_option_s` ``*pool_debug_options`` :c:func:`mps_class_ams_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_arena_class_vm`, :c:func:`mps_class_mvff` :c:macro:`MPS_KEY_SPARE_COMMIT_LIMIT` :c:type:`size_t` ``size`` :c:func:`mps_arena_class_vm`