diff --git a/mps/manual/source/pool/mv.rst b/mps/manual/source/pool/mv.rst index f7c3c68cf38..27e691ed3af 100644 --- a/mps/manual/source/pool/mv.rst +++ b/mps/manual/source/pool/mv.rst @@ -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 diff --git a/mps/manual/source/topic/allocation.rst b/mps/manual/source/topic/allocation.rst index 4565812da78..4075cfe006a 100644 --- a/mps/manual/source/topic/allocation.rst +++ b/mps/manual/source/topic/allocation.rst @@ -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 */ diff --git a/mps/manual/source/topic/deprecated.rst b/mps/manual/source/topic/deprecated.rst index 7e915252db5..dfd4d8d74cb 100644 --- a/mps/manual/source/topic/deprecated.rst +++ b/mps/manual/source/topic/deprecated.rst @@ -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, diff --git a/mps/manual/source/topic/error.rst b/mps/manual/source/topic/error.rst index 82efa2e5e3c..210be2950b2 100644 --- a/mps/manual/source/topic/error.rst +++ b/mps/manual/source/topic/error.rst @@ -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 `, 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 `. 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 diff --git a/mps/manual/source/topic/interface.rst b/mps/manual/source/topic/interface.rst index 47be85de43a..e7715181836 100644 --- a/mps/manual/source/topic/interface.rst +++ b/mps/manual/source/topic/interface.rst @@ -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 diff --git a/mps/manual/source/topic/keyword.rst b/mps/manual/source/topic/keyword.rst index 1652d11e20f..ac80333ba36 100644 --- a/mps/manual/source/topic/keyword.rst +++ b/mps/manual/source/topic/keyword.rst @@ -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) diff --git a/mps/manual/source/topic/porting.rst b/mps/manual/source/topic/porting.rst index 064ada7eea3..26c663f58f9 100644 --- a/mps/manual/source/topic/porting.rst +++ b/mps/manual/source/topic/porting.rst @@ -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