From 9c5eec19b22115031001fbdfc02aaaecc117c511 Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Thu, 18 Oct 2012 15:00:41 +0100 Subject: [PATCH] New glossary entry: "allocation frame". Document symbols mps_addr_fmt, mps_addr_pool, mps_arena_destroy, mps_arena_extend, mps_arena_reserved, mps_fmt_destroy, mps_frame_t, mps_pool_destroy, mps_rm_t, mps_root_destroy, mps_word_t. Copied from Perforce Change: 179940 ServerID: perforce.ravenbrook.com --- mps/manual/source/glossary/a.rst | 13 +- mps/manual/source/glossary/f.rst | 2 +- mps/manual/source/glossary/r.rst | 4 +- mps/manual/source/guide/index.rst | 7 +- mps/manual/source/guide/lang.rst | 31 +-- mps/manual/source/guide/perf.rst | 2 + mps/manual/source/notes.txt | 57 +++-- mps/manual/source/reference/index.rst | 300 +++++++++++++++++++++----- mps/manual/source/topic/index.rst | 2 +- mps/manual/source/topic/platform.rst | 23 +- 10 files changed, 338 insertions(+), 103 deletions(-) diff --git a/mps/manual/source/glossary/a.rst b/mps/manual/source/glossary/a.rst index b0a5de861a2..4fba923fac5 100644 --- a/mps/manual/source/glossary/a.rst +++ b/mps/manual/source/glossary/a.rst @@ -234,7 +234,18 @@ Memory Management Glossary: A allocation frame - .. mps:specific:: ?? + .. mps:specific:: + + An allocation frame is a marker that can pushed onto an + :term:`allocation point` by calling + :c:func:`mps_ap_frame_push`, and then popped by calling + :c:func:`mps_ap_frame_pop` to indicate that all blocks + allocated on the allocation point are :term:`dead` (in the + case of :term:`manual ` pools), or + very likely dead (in the case of :term:`automatic + ` pools). Allocation frames can + be used by the :term:`client program` to efficiently + implement stack-like patterns of allocation. allocation mechanism diff --git a/mps/manual/source/glossary/f.rst b/mps/manual/source/glossary/f.rst index fc9c7a6a34b..68dc8d82392 100644 --- a/mps/manual/source/glossary/f.rst +++ b/mps/manual/source/glossary/f.rst @@ -235,7 +235,7 @@ Memory Management Glossary: F program, or the MPS), which is not aware of and does not co-operate with the MPS. The client program must take care that foreign code is not passed the address of a block in - a :term:`moving ` :term:`pools + a :term:`moving ` :term:`pools `, 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 diff --git a/mps/manual/source/glossary/r.rst b/mps/manual/source/glossary/r.rst index 4b3bad1e212..60369ef559b 100644 --- a/mps/manual/source/glossary/r.rst +++ b/mps/manual/source/glossary/r.rst @@ -528,8 +528,8 @@ Memory Management Glossary: R A value of type :c:type:`mps_rm_t` describing whether a :term:`root` is :term:`constant `, :term:`protectable `, or both. The root - mode tells the MPS whether it may place a :term:`barrier` - on the root. + mode tells the MPS whether it may place a :term:`barrier + (1)` on the root. root set diff --git a/mps/manual/source/guide/index.rst b/mps/manual/source/guide/index.rst index e7cc7897492..bef39d37fc4 100644 --- a/mps/manual/source/guide/index.rst +++ b/mps/manual/source/guide/index.rst @@ -1,8 +1,9 @@ -*********** -User guides -*********** +********** +User guide +********** .. toctree:: + :numbered: install overview diff --git a/mps/manual/source/guide/lang.rst b/mps/manual/source/guide/lang.rst index 50575fe66e8..1fdb531b89e 100644 --- a/mps/manual/source/guide/lang.rst +++ b/mps/manual/source/guide/lang.rst @@ -15,9 +15,9 @@ In this guide, I'll explain how to use the MPS to add incremental, moving, generational garbage collection to the runtime system for a programming language. -I'm assuming that you've downloaded and built the MPS (see +I'm assuming that you've downloaded and built the MPS (see the chapter :ref:`guide-install`), and that you are familiar with the overall -architecture of the MPS (see :ref:`guide-overview`). +architecture of the MPS (see the chapter :ref:`guide-overview`). ---------------------- @@ -625,16 +625,17 @@ The AMC pool requires not only an object format but a the :term:`generational garbage collection`. You create a generation chain by constructing an array of structures -of type :c:type:`mps_gen_param_s` and passing them to -:c:func:`mps_chain_create`. Each of these structures contains two -values, the *capacity* of the generation in :term:`kilobytes -`, and the *mortality*, the proportion of objects in the -generation that you expect to survive a collection of that generation. +of type :c:type:`mps_gen_param_s`, one for each generation, and +passing them to :c:func:`mps_chain_create`. Each of these structures +contains two values, the *capacity* of the generation in +:term:`kilobytes `, and the *mortality*, the proportion of +objects in the generation that you expect to survive a collection of +that generation. -These numbers are hints to the MPS that it may use to make decisions +These numbers are *hints* to the MPS that it may use to make decisions about when and what to collect: nothing will go wrong (other than suboptimal performance) if you make poor choices. Making good choices -for the capacity and mortality of each generation is not easy, and is postponed to the guide :ref:`guide-perf`. +for the capacity and mortality of each generation is not easy, and is postponed to the chapter :ref:`guide-perf`. Here's the code for creating the generation chain for the Scheme interpreter:: @@ -1143,7 +1144,11 @@ these rules: 4. Objects must remain scannable throughout their :term:`lifetime`. - See :ref:`guide-debug`. + .. fixme: refer to example here when written. + +Explanations of what happens if your code breaks these rules, together +with tactics for tracking down the causes, appear in the chapter +:ref:`guide-debug`. ---------- @@ -1183,8 +1188,8 @@ incremental, moving, generational garbage collection to the runtime system for a programming language. If everything is working for your language, then the next step is -:ref:`guide-perf`. +the chapter :ref:`guide-perf`. But if things don't work out quite as smoothly for your language as -they did in the Scheme example, then you'll be more interested in -:ref:`guide-debug`. +they did in the Scheme example, then you'll be more interested in the +chapter :ref:`guide-debug`. diff --git a/mps/manual/source/guide/perf.rst b/mps/manual/source/guide/perf.rst index b8a4029530c..e2832576ff1 100644 --- a/mps/manual/source/guide/perf.rst +++ b/mps/manual/source/guide/perf.rst @@ -5,3 +5,5 @@ ============================== Tuning the MPS for performance ============================== + +See diff --git a/mps/manual/source/notes.txt b/mps/manual/source/notes.txt index e0936b0ab5d..19e248e89b3 100644 --- a/mps/manual/source/notes.txt +++ b/mps/manual/source/notes.txt @@ -19,17 +19,6 @@ TODO, QUERIES AND SUGGESTIONS 11. Support MMREF-style anchors to the glossary (#garbage.collection instead of #garbage-collection). -26. I need to document the values in mps_gen_param_s. I believe they - are the capacity (size of the generation in kilobytes) and the - mortality (the proportion of objects in this generation that are - expected to die in a collection). But what do they mean to the - MPS? And how should one go about choosing values? - - ANSWER: requires a whole document. Talk to RB. The intro document - should say, "take these values on trust". There's a design - document about this based on the Lisp Machine: - analysis.strategy.lisp-machine or something. - 27. Wouldn't it make mps_amc_apply easier to document if there were a typedef for the stepper function type, something like this? @@ -53,9 +42,6 @@ TODO, QUERIES AND SUGGESTIONS "mps_tramp needs to wrap any code that might handle references into a pool class that requires it." [All the ones with A.] -33. Status. At what point will the work be "good enough" to merge back - to the master sources? - 37. Some of the Scheme objects could be moved to a leaf-only pool (e.g. AMCZ). @@ -92,6 +78,33 @@ TODO, QUERIES AND SUGGESTIONS (It seems from looking at the implementation that it puts the arena into the unclamped state, like mps_arena_release.) +44. How do I explain the condition on mps_addr_pool and mps_addr_fmt? + It's clear what this is if the address is the address of an + allocated block? But do we guarantee anything if it isn't? The + implementation succeeds if the address points anywhere within a + page allocated to a pool. + +45. Constraints on order of _destroy functions. Is it an error to + destroy an object format while there are still pools that refer to + it? + +46. mps.h declares the type mps_shift_t for a "shift amount" but this + is not used anywhere in the MPS. Remove? + +47. The structures mps_sac_s and mps_sac_freelist_block_s are declared + in mps.h. I presume that this is so for the benefit of the macros + MPS_SAC_ALLOC_FAST and MPS_SAC_FREE_FAST, and the details of these + structues are not actually part of the public interface. + +48. mps_fmt_fixed_s is just like mps_fmt_A_s but with no "skip". I + presume it's for fixed-size pools. But the only fixed-size pool is + MFS, which has no public header, so I presume it's for MPS + internal use only. What should I say about this? + +49. It's rather unfortunate that mps_arena_create take arguments + (size, base) but mps_arena_extend takes (base, size). I guess + there's nothing to be done about this now. + DONE, ANSWERED @@ -238,6 +251,17 @@ DONE, ANSWERED ANSWER: take it out. +26. I need to document the values in mps_gen_param_s. I believe they + are the capacity (size of the generation in kilobytes) and the + mortality (the proportion of objects in this generation that are + expected to die in a collection). But what do they mean to the + MPS? And how should one go about choosing values? + + ANSWER: requires a whole document. Talk to RB. The intro document + should say, "take these values on trust". There's a design + document about this based on the Lisp Machine: + analysis.strategy.lisp-machine or something. + 28. Wouldn't the Scheme example be better without TAB characters? ANSWER: maybe, but it would lead to merge conflicts. So no change. @@ -264,6 +288,11 @@ DONE, ANSWERED whether it's OK for the MPS to put a barrier on the root. Recommend pass zero. For future expansion. +33. Status. At what point will the work be "good enough" to merge back + to the master sources? + + ANSWER: After RB reviews it. + 34. The generic example of using mps_tramp need to pass argv and argc, and return an exit code, so maybe it would make sense to do that in the Scheme example, even though Scheme doesn't use these diff --git a/mps/manual/source/reference/index.rst b/mps/manual/source/reference/index.rst index f4794271191..d3f0c515bbc 100644 --- a/mps/manual/source/reference/index.rst +++ b/mps/manual/source/reference/index.rst @@ -19,6 +19,53 @@ Symbol reference Declared in ``mps.h`` ===================== +.. c:function:: mps_bool_t mps_addr_fmt(mps_fmt_t *fmt_o, mps_arena_t arena, mps_addr_t addr) + + Determine the :term:`object format` to which an address belongs. + + ``fmt_o`` points to a location that will hold the address of the + object format, if one is found. + + ``arena`` is the arena whose object formats will be considered. + + ``addr`` is the address. + + If ``addr`` is the address of a location inside a block allocated + from a pool in ``arena``, and that pool has an object format, then + update the location pointed to by ``fmt_o`` with the address of + the object format, and return true. If the pool has no object + format, or ``addr`` points to a location that is not managed by + ``arena``, return false. (There is no guaranteed behaviour if + neither of these conditions is satisfied.) + + .. topics:: + + :ref:`topic-format` + + +.. c:function:: mps_bool_t mps_addr_pool(mps_pool_t *pool_o, mps_arena_t arena, mps_addr_t addr) + + Determine the :term:`pool` to which an address belongs. + + ``pool_o`` points to a location that will hold the address of the + pool, if one is found. + + ``arena`` is the arena whose pools will be considered. + + ``addr`` is the address. + + If ``addr`` is the address of a location inside a block allocated + from a pool in ``arena``, then update the location pointed to by + ``pool_o`` with the address of the pool, and return true. If + ``addr`` points to a location that is not managed by ``arena``, + return false. (There is no guaranteed behaviour if neither of + these conditions is satisfied.) + + .. topics:: + + :ref:`pool` + + .. c:type:: mps_addr_t The type of :term:`addresses
` managed by the MPS, and @@ -523,6 +570,45 @@ Declared in ``mps.h`` :ref:`topic-arena`. +.. c:function:: void mps_arena_destroy(mps_arena_t arena) + + Destroy an :term:`arena`. + + ``arena`` is the arena to destroy. + + This function checks the consistency of the arena, flushes the + :term:`telemetry stream` and destroys the arena's internal control + structures. Additionally, :term:`virtual memory arenas ` return their reserved address space to the + operating system if possible. + + It is an error to destroy an arena without first destroying all + :term:`generation chains `, :term:`object + formats `, :term:`pools `, :term:`roots + `, and :term:`threads ` created in the arena. + + .. topics:: + + :ref:`topic-arena`. + + +.. c:function:: mps_res_t mps_arena_extend(mps_arena_t arena, mps_addr_t base, size_t size) + + Extend a :term:`client arena` with another block of memory. + + ``base`` is the :term:`address` of the block of memory that will be + managed by the arena. + + ``size`` is its :term:`size`. + + Return :c:macro:`MPS_RES_OK` if successful, or another + :term:`result code` if it fails. + + .. topics:: + + :ref:`topic-arena`. + + .. c:function:: void mps_arena_formatted_objects_walk(mps_arena_t arena, mps_formatted_objects_stepper_t f, void *p, size_t s) Visit all :term:`formatted objects ` in an @@ -623,6 +709,34 @@ Declared in ``mps.h`` :ref:`topic-arena`, :ref:`topic-collection`. +.. c:function:: size_t mps_arena_reserved(mps_arena_t arena) + + Return the total :term:`address space` reserved by an + :term:`arena`, in :term:`bytes `. + + ``arena`` is the arena. + + For a :term:`virtual memory arena`, this is the total address space + reserved via the operating system's virtual memory interface. + + For a :term:`client arena`, this is the sum of the usable portions + of the chunks of memory passed to the arena by the :term:`client + program` via :c:func:`mps_arena_create` and + :c:func:`mps_arena_extend`. + + .. topics:: + + :ref:`topic-arena`. + + .. note:: + + For a client arena, the reserved address may be lower than the + sum of the ``size`` arguments passed to + :c:func:`mps_arena_create` and :c:func:`mps_arena_extend`, + because the arena may be unable to use the whole of each chunk + for reasons of alignment. + + .. c:function:: void mps_arena_roots_walk(mps_arena_t arena, mps_roots_stepper_t f, void *p, size_t s) Visit references in registered :term:`roots ` in an @@ -752,15 +866,15 @@ Declared in ``mps.h`` collection to proceed incrementally (as for a collection that is scheduled automatically). + .. topics:: + + :ref:`topic-arena`. + .. note:: Contrast with :c:func:`mps_arena_collect`, which does not return until the collection has completed. - .. topics:: - - :ref:`topic-arena`. - .. c::function:: mps_bool_t mps_arena_step(mps_arena_t arena, double interval, double multiplier) @@ -1239,8 +1353,6 @@ Declared in ``mps.h`` method` must still be able to create :term:`padding objects ` down to the alignment size. - .. note:: - The auto_header format is only supported by :ref:`pool-amc` and :ref:`pool-amcz`. @@ -1268,8 +1380,8 @@ Declared in ``mps.h`` in :term:`copying ` or :term:`moving ` :term:`pools ` (just like variant A); the addition of a :term:`class method` allows more - information to be passed to various support tools (such as - graphical browsers). See :c:type:`mps_fmt_class_t`. + information to be passed to support tools. See + :c:type:`mps_fmt_class_t`. .. topics:: @@ -1283,8 +1395,8 @@ Declared in ``mps.h`` ``addr`` is the address of the object whose class is of interest. Returns an address that is related to the class or type of the - object, for passing on to support tools (such as graphical - browsers), or a null pointer if this is not possible. + object, for passing on to support tools, or a null pointer if this + is not possible. It is recommended that a null pointer be returned for :term:`padding objects ` and :term:`forwarding @@ -1369,6 +1481,20 @@ Declared in ``mps.h`` :ref:`topic-format`. +.. c:function:: void mps_fmt_destroy(mps_fmt_t fmt) + + Destroy an :term:`object format`. + + ``fmt`` is the object format to destroy. + + It is an error to destroy an object format if there exists a + :term:`pool` using the format. The pool must be destroyed first. + + .. topics:: + + :ref:`topic-format`. + + .. c:type:: void (*mps_fmt_fwd_t)(mps_addr_t old, mps_addr_t new) The type of the :term:`forward method` of an :term:`object format`. @@ -1509,16 +1635,16 @@ Declared in ``mps.h`` A skip method is not allowed to fail. + .. topics:: + + :ref:`topic-format`, :ref:`topic-scanning`. + .. note:: The MPS uses this method to determine the size of objects (by subtracting ``addr`` from the result) as well as skipping over them. - .. topics:: - - :ref:`topic-format`, :ref:`topic-scanning`. - .. c:type:: mps_fmt_t @@ -1553,6 +1679,26 @@ Declared in ``mps.h`` :ref:`topic-arena`, :ref:`topic-format`. +.. c:type:: mps_frame_t + + The type of :term:`allocation frames `. + + An allocation frame is a marker that can pushed onto an + :term:`allocation point` by calling :c:func:`mps_ap_frame_push`, + and then popped by calling :c:func:`mps_ap_frame_pop` to indicate + that all blocks allocated on the allocation point are :term:`dead` + (in the case of :term:`manual ` pools), + or very likely dead (in the case of :term:`automatic ` pools). + + Allocation frames can be used by the :term:`client program` to + efficiently implement stack-like patterns of allocation. + + .. topics:: + + :ref:`topic-frame`. + + .. c:function:: void mps_free(mps_pool_t pool, mps_addr_t addr, size_t size) Free a :term:`block` of memory to a :term:`pool`. @@ -1627,6 +1773,10 @@ Declared in ``mps.h`` will return true if the block has moved. + .. topics:: + + :ref:`topic-location`. + .. note:: It is an error to call :c:func:`mps_ld_add` on the same @@ -1644,10 +1794,6 @@ Declared in ``mps.h`` this is that there should be a lock associated with each location dependency. - .. topics:: - - :ref:`topic-location`. - .. c:function:: mps_bool_t mps_ld_isstale(mps_ld_t ld, mps_arena_t arena, mps_addr_t addr) @@ -1676,6 +1822,10 @@ Declared in ``mps.h`` circumstances (but will strive to return false if the objects encapsulated in the location dependency have not moved). + .. topics:: + + :ref:`topic-location`. + .. note:: :c:func:`mps_ld_isstale` may report a false positive @@ -1687,10 +1837,6 @@ Declared in ``mps.h`` and with respect to :c:func:`mps_ld_add`, but not with respect to :c:func:`mps_ld_reset`. - .. topics:: - - :ref:`topic-location`. - .. c:function:: void mps_ld_merge(mps_ld_t dest_ld, mps_arena_t arena, mps_ld_t src_ld) @@ -1871,8 +2017,6 @@ Declared in ``mps.h`` scanned memory, without imposing the restriction that the C stack be a :term:`root`. - .. note:: - The message itself is not affected by invoking this method. Until the client program calls :c:func:`mps_message_discard` to discard the message, it will refer to the object and @@ -2280,6 +2424,28 @@ Declared in ``mps.h`` :ref:`topic-debugging`. +.. c:function:: void mps_pool_destroy(mps_pool_t pool) + + Destroy a :term:`pool`. + + ``pool`` is the pool to destroy. + + This function checks the consistency of the pool, destroys the + pool's internal control structures and causes the pool's memory to + be returned to the :term:`arena` for reuse by other pools, or to + be returned to the operating system. Blocks allocated from the + pool may no longer be used. + + It is an error to destroy a pool without first destroying all + :term:`allocation points ` and :term:`segregated + allocation caches ` created in the + pool. + + .. topics:: + + :ref:`pool`. + + .. c:function:: mps_rank_t mps_rank_ambig(void) Return the :term:`rank` of :term:`ambiguous roots `. + + A root mode describes whether a :term:`root` is :term:`constant + `, :term:`protectable `, or both, + and lets the MPS know whether it may place a :term:`barrier (1)` + on the root. + + It should be the sum of some subset of :c:macro:`MPS_RM_CONST` and + :c:macro:`MPS_RM_PROT`, or zero (meaning neither constant or + protectable). + + .. topics:: + + :ref:`topic-root`. + + .. note:: + + As of version 1.110, the MPS does not place barriers on roots, + and so does not make use of the root mode. The feature may be + added in a future release. + + .. c:function:: mps_res_t mps_root_create(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_root_scan_t root_scan, void *p, size_t s) Register a :term:`root` that consists of the :term:`references @@ -2767,6 +2953,17 @@ Declared in ``mps.h`` :ref:`topic-root`. +.. c:function:: void mps_root_destroy(mps_root_t root) + + Deregister a :term:`root` and destroy its description. + + ``root`` is the root. + + .. topics:: + + :ref:`topic-root`. + + .. c:type:: typedef mps_res_t (*mps_root_scan_t)(mps_ss_t ss, void *p, size_t s) The type of root scanning functions for :c:func:`mps_root_create`. @@ -2870,16 +3067,12 @@ Declared in ``mps.h`` the same thing. The macro is faster, but generates more code and does less checking. - .. note:: - The :term:`client program` is responsible for synchronizing the access to the cache, but if the cache decides to access the pool, the MPS will properly synchronize with any other :term:`threads ` that might be accessing the same pool. - .. note:: - Blocks allocated through a segregated allocation cache should only be freed through a segregated allocation cache with the same :term:`class structure`. Using :c:func:`mps_free` on them @@ -2947,14 +3140,10 @@ Declared in ``mps.h`` :term:`threads ` that might be accessing the same pool. - .. note:: - There's also a macro :c:func:`MPS_SAC_FREE_FAST` that does the same thing. The macro is faster, but generates more code and does no checking. - .. note:: - :c:func:`mps_sac_free` does very little checking: it's optimized for speed. :term:`Double frees ` and other mistakes will only be detected when the cache is flushed @@ -3196,8 +3385,6 @@ Declared in ``mps.h`` case of an error it is allowed to return from the scan method without invoking :c:func:`MPS_SCAN_END`. - .. note:: - Between :c:func:`MPS_SCAN_BEGIN` and :c:func:`MPS_SCAN_END`, the scan state is in a special state, and must not be passed to a function. If you really need to do so, for example because you @@ -3384,6 +3571,17 @@ Declared in ``mps.h`` :ref:`topic-root`. +.. c:type:: mps_word_t + + An unsigned integral type that is the same size as an + :term:`object pointer`, so that ``sizeof(mps_word_t) == + sizeof(void*)``. + + The exact identity of this type is + :term:`platform`\-dependent. Typical identities are ``unsigned + long`` and ``unsigned __int_64``.2 + + ======================== Declared in ``mpsacl.h`` ======================== @@ -3393,24 +3591,23 @@ Declared in ``mpsacl.h`` Return the :term:`arena class` for a :term:`client arena`. A client arena gets its managed memory from the :term:`client - program`. This memory block is passed when the arena is created. + program`. This memory chunk is passed when the arena is created. When creating a client arena, :c:func:`mps_arena_create` takes two extra arguments:: mps_res_t mps_arena_create(mps_arena_t *arena_o, mps_arena_class_t mps_arena_class_cl, - size_t size, void *block) + size_t size, mps_addr_t base) - ``block`` is the :term:`address` of the block of memory that will be - managed by the arena. + ``base`` is the :term:`address` of the chunk of memory that will + be managed by the arena. ``size`` is its :term:`size`. - If the block is too small to hold the internal arena structures, + If the chunk is too small to hold the internal arena structures, :c:func:`mps_arena_create` returns :c:macro:`MPS_RES_MEMORY`. In - this case, you should allocate a (much) larger block, and try - again. + this case, you need to use a (much) larger chunk. .. topics:: @@ -3497,22 +3694,10 @@ Declared in ``mpsavm.h`` Undocumented in ``mps.h`` ========================= -.. c:type:: mps_frame_t -.. c:type:: mps_word_t -.. c:type:: mps_shift_t -.. c:type:: mps_rm_t -.. c:type:: mps_sac_freelist_block_s .. c:type:: mps_fmt_fixed_s -.. c:function:: void mps_arena_destroy(mps_arena_t arena) -.. c:function:: size_t mps_arena_reserved(mps_arena_t arena) -.. c:function:: mps_res_t mps_arena_extend(mps_arena_t arena, mps_addr_t base, size_t size) .. c:function:: mps_res_t mps_fmt_create_fixed(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_fixed_s *fmt_fixed) -.. c:function:: void mps_fmt_destroy(mps_fmt_t format) -.. c:function:: mps_bool_t mps_addr_pool(mps_pool_t *pool_o, mps_arena_t arena, mps_addr_t addr) -.. c:function:: mps_bool_t mps_addr_fmt(mps_fmt_t *fmt_o, mps_arena_t arena, mps_addr_t addr) .. c:function:: mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena, mps_class_t class, ...) .. c:function:: mps_res_t mps_pool_create_v(mps_pool_t *pool_o, mps_arena_t arena, mps_class_t class, va_list args) -.. c:function:: void mps_pool_destroy(mps_pool_t pool) .. c:function:: mps_res_t mps_ap_create(mps_ap_t *ap_o, mps_pool_t pool, ...) .. c:function:: mps_res_t mps_ap_create_v(mps_ap_t *ap_o, mps_pool_t pool, va_list args) .. c:function:: void mps_ap_destroy(mps_ap_t mps_ap) @@ -3524,7 +3709,6 @@ Undocumented in ``mps.h`` .. c:function:: size_t mps_reservoir_available(mps_arena_t arena) .. c:function:: MPS_RESERVE_BLOCK(mps_res_t res_v, mps_addr_t p_v, mps_ap_t ap, size_t size) .. c:function:: MPS_RESERVE_WITH_RESERVOIR_PERMIT_BLOCK(mps_res_t res_v, mps_addr_t p_v, mps_ap_t ap, size_t size) -.. c:function:: void mps_root_destroy(mps_root_t mps_root) .. c:type:: void *(*mps_tramp_t)(void *p, size_t s) .. c:function:: void mps_tramp(void **r_o, mps_tramp_t tramp, void *p, size_t s) .. c:function:: mps_res_t mps_thread_reg(mps_thr_t *mps_thr_o, mps_arena_t arena) diff --git a/mps/manual/source/topic/index.rst b/mps/manual/source/topic/index.rst index 0ad06e39753..203d310babc 100644 --- a/mps/manual/source/topic/index.rst +++ b/mps/manual/source/topic/index.rst @@ -3,7 +3,7 @@ Topic reference *************** .. toctree:: - :maxdepth: 2 + :numbered: arena allocation diff --git a/mps/manual/source/topic/platform.rst b/mps/manual/source/topic/platform.rst index 9eea2bb4440..ccadb02d3ab 100644 --- a/mps/manual/source/topic/platform.rst +++ b/mps/manual/source/topic/platform.rst @@ -196,20 +196,21 @@ Declared in ``mpstd.h`` x86-64 processor architecture, and the LLVM compiler. -.. c:type:: MPS_T_ULONGEST +.. c:macro:: MPS_T_ULONGEST - The largest unsigned integral type. + A :term:`C` preprocessor macro that expands to the name of the + largest unsigned integral type. The exact identity of this type is :term:`platform`\-dependent. Typical identities are ``unsigned long`` and ``unsigned __int_64``. -.. c:type:: MPS_T_WORD +.. c:macro:: MPS_T_WORD - An unsigned integral type that is the same size as an - :term:`object pointer`, so that ``sizeof(MPS_T_WORD) == - sizeof(void*)``. + A :term:`C` preprocessor macro that expands to the name of an + unsigned integral type that is the same size as an :term:`object + pointer`, so that ``sizeof(MPS_T_WORD) == sizeof(void*)``. The exact identity of this type is :term:`platform`\-dependent. Typical identities are ``unsigned @@ -218,16 +219,18 @@ Declared in ``mpstd.h`` .. c:macro:: MPS_WORD_SHIFT - The logarithm to base 2 of the constant :c:macro:`MPS_WORD_WIDTH`, - so that ``1 << MPS_WORD_SHIFT == MPS_WORD_WIDTH``. + A :term:`C` preprocessor macro that expands to the logarithm to + base 2 of the constant :c:macro:`MPS_WORD_WIDTH`, so that ``1 << + MPS_WORD_SHIFT == MPS_WORD_WIDTH``. The value is platform-dependent. Typical values are 5 and 6. .. c:macro:: MPS_WORD_WIDTH - The width in bits of the type :c:type:`MPS_T_WORD`, so that - ``MPS_WORD_WIDTH == sizeof(MPS_T_WORD) * CHAR_BIT``. + A :term:`C` preprocessor macro that expands to the width in bits + of the type :c:type:`MPS_T_WORD`, so that ``MPS_WORD_WIDTH == + sizeof(MPS_T_WORD) * CHAR_BIT``. This value is platform-dependent. It is always a power of 2: typical values are 32 and 64.