From 26cf4ba9546fadeea9d2e494c5a37bd52e6c69bc Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Tue, 9 Oct 2012 17:54:22 +0100 Subject: [PATCH] 12% of the way through converting the mps reference manual to sphinx documentation. Copied from Perforce Change: 179792 ServerID: perforce.ravenbrook.com --- mps/manual/source/copyright.rst | 14 + mps/manual/source/glossary.rst | 186 + mps/manual/source/index.rst | 14 +- mps/manual/source/pool/index.rst | 7 + mps/manual/source/reference/index.rst | 7505 ++++++++++++++++++++++++ mps/manual/source/topic/allocation.rst | 47 + mps/manual/source/topic/cache.rst | 109 + mps/manual/source/topic/error.rst | 35 + mps/manual/source/topic/frame.rst | 5 + mps/manual/source/topic/index.rst | 15 + mps/manual/source/topic/moving.rst | 4 + mps/manual/source/topic/pattern.rst | 110 + mps/manual/source/topic/platform.rst | 5 + mps/manual/source/topic/root.rst | 26 + mps/manual/source/topic/scanning.rst | 129 + 15 files changed, 8205 insertions(+), 6 deletions(-) create mode 100644 mps/manual/source/copyright.rst create mode 100644 mps/manual/source/glossary.rst create mode 100644 mps/manual/source/pool/index.rst create mode 100644 mps/manual/source/reference/index.rst create mode 100644 mps/manual/source/topic/allocation.rst create mode 100644 mps/manual/source/topic/cache.rst create mode 100644 mps/manual/source/topic/error.rst create mode 100644 mps/manual/source/topic/frame.rst create mode 100644 mps/manual/source/topic/index.rst create mode 100644 mps/manual/source/topic/moving.rst create mode 100644 mps/manual/source/topic/pattern.rst create mode 100644 mps/manual/source/topic/platform.rst create mode 100644 mps/manual/source/topic/root.rst create mode 100644 mps/manual/source/topic/scanning.rst diff --git a/mps/manual/source/copyright.rst b/mps/manual/source/copyright.rst new file mode 100644 index 00000000000..cb8c214b504 --- /dev/null +++ b/mps/manual/source/copyright.rst @@ -0,0 +1,14 @@ +Copyright and licence +===================== + +The Memory Pool System documentation is copyright © 1997–2012 by `Ravenbrook Limited `_. All rights reserved. This is an open source license. Contact Ravenbrook for commercial licensing options. + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + +3. Redistributions in any form must be accompanied by information on how to obtain complete source code for this software and any accompanying software that uses this software. The source code must either be included in the distribution or be available for no more than the cost of distribution plus a nominal fee, and must be freely redistributable under reasonable conditions. For an executable file, complete source code means the source code for all modules it contains. It does not include source code for modules or files that typically accompany the major components of the operating system on which the executable file runs. + +**This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement, are disclaimed. In no event shall the copyright holders and contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.** diff --git a/mps/manual/source/glossary.rst b/mps/manual/source/glossary.rst new file mode 100644 index 00000000000..055b4c394c4 --- /dev/null +++ b/mps/manual/source/glossary.rst @@ -0,0 +1,186 @@ +.. _glossary: + +Glossary +======== + +.. glossary:: + + address + + ?? + + address space + + ?? + + alignment + + The address modulus to which all :term:`objects ` in + an :term:`object format` must be aligned. That is, if an + alignment of 4 is specified for a format, then the + :term:`address` of any object in that format will always be 0, + modulo 4. In the MPS, an alignment must be a positive power of + 2. + + allocation frame + + ?? + + allocation pattern + + ?? + + allocation point + + ?? + + arena commit limit + + ?? + + block + + ?? + + class structure + + ?? + + client program + + ?? + + constant root + + ?? + + data object + + ?? + + dead + + ?? + + double free + + ?? + + format method + + ?? + + formatted object + + ?? + + formatted root + + ?? + + hardware write barrier + + ?? + + live + + ?? + + object + + A contiguous region of memory forming a single logical structure. + + object format + + ?? See the topic :ref:`topic-scanning`. + + object pointer + + ?? + + pad object + + ?? + + page + + ?? + + parked + + ?? + + pointer + + ?? + + pool + + ?? + + protectable root + + ?? + + ramp pattern + + ?? + + rank + + ?? + + reference + + A link from one :term:`object` to another, usually in the form + of a :term:`pointer`. + + reservoir + + ?? + + result code + + A value returned from an MPS function, represented by the type + :c:type:`mps_res_t`. The result code :c:macro:`MPS_RES_OK` + indicates success; other values indicate errors. See the topic + :ref:`topic-errors`. + + root + + ?? + + root mode + + ?? + + scan function + + A function that examines a block of memory to find + :term:`references ` and indicate them to the MPS. A + scan function forms part of an :term:`object format`. See + the topic :ref:`topic-scanning`. + + scan state + + ?? See the topic :ref:`topic-scanning`. + + segregated allocation cache + + ?? + + size + + ?? + + size class + + ?? + + table root + + ?? + + virtual memory + + ?? diff --git a/mps/manual/source/index.rst b/mps/manual/source/index.rst index 58b0c443284..d44c7359fdf 100644 --- a/mps/manual/source/index.rst +++ b/mps/manual/source/index.rst @@ -1,22 +1,24 @@ .. Memory Pool System documentation master file, created by sphinx-quickstart on Tue Oct 9 11:21:17 2012. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. -Welcome to Memory Pool System's documentation! -============================================== -Contents: +Memory Pool System +================== .. toctree:: :maxdepth: 2 + guide/index + topic/index + pool/index + reference/index + glossary + copyright Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search` diff --git a/mps/manual/source/pool/index.rst b/mps/manual/source/pool/index.rst new file mode 100644 index 00000000000..0cde74d7464 --- /dev/null +++ b/mps/manual/source/pool/index.rst @@ -0,0 +1,7 @@ +Pool reference +============== + +.. toctree:: + :maxdepth: 2 + + pool-amc diff --git a/mps/manual/source/reference/index.rst b/mps/manual/source/reference/index.rst new file mode 100644 index 00000000000..ea8414fd22c --- /dev/null +++ b/mps/manual/source/reference/index.rst @@ -0,0 +1,7505 @@ +.. highlight:: c + +.. Checklist of things to say about a symbol + + Signature + Summary + Arguments + Result + Status (deprecated?) + Topic + + +================ +Symbol reference +================ + + +.. c:type:: mps_addr_t + + The type of :term:`addresses
` managed by the MPS, and + also the type of :term:`references `. + + It is used in the MPS interface for any pointer that is under the + control of the MPS. In accordance with standard C practice, the + value ``NULL`` of type :c:type:`mps_addr_t` will never be used to + represent a reference to a block. + + .. seealso:: + + :ref:`topic-allocation` and :ref:`topic-platform`. + + +.. c:type:: mps_align_t + + The type of an :term:`alignment`. It is an integral type + equivalent to the standard C type ``size_t``. An alignment must be + a positive powers of 2. + + .. seealso:: + + :ref:`topic-allocation`. + + +.. c:function:: mps_res_t mps_alloc(mps_addr_t *p_o, mps_pool_t pool, size_t size, ...) + + Allocate a :term:`block` of memory in a :term:`pool`. + + *p_o* points to a location that will hold the address of the + allocated block. + + *pool* the pool to allocate in. + + *size* is the :term:`size` of the block to allocate. + + Some pools require additional arguments to be passed to + :c:func:`mps_alloc`. See the documentation for the pool class. + + .. seealso:: + + :ref:`topic-allocation`. + + +.. c:function:: mps_alloc_pattern_t mps_alloc_pattern_ramp(void) + + Return an :term:`allocation pattern` indicating that allocation + will follow a :term:`ramp pattern`. + + This indicates to the MPS that most of the blocks allocated after + the call to :c:func:`mps_ap_alloc_pattern_begin` are likely to be + :term:`dead` by the time of the corresponding call to + :c:func:`mps_ap_alloc_pattern_end`. + + .. seealso:: + + :ref:`topic-pattern`. + + +.. c:function:: mps_alloc_pattern_t mps_alloc_pattern_ramp_collect_all(void) + + Return an :term:`allocation pattern` indicating that allocation + will follow a :term:`ramp pattern`, and that the next + :term:`garbage collection` following the ramp should be a full + collection. + + This indicates to the MPS that most of the blocks allocated after + the call to :c:func:`mps_ap_alloc_pattern_begin` are likely to be + :term:`dead` by the time of the corresponding call to + :c:func:`mps_ap_alloc_pattern_end`. + + This allocation pattern may nest with, but should not otherwise + overlap with, allocation patterns of type + :c:func:`mps_alloc_pattern_ramp`. In this case, the MPS may defer + the full collection until after all ramp allocation patterns have + ended. + + .. seealso:: + + :ref:`topic-pattern`. + + +.. c:function:: void mps_amc_apply(mps_pool_t pool, void (*f)(mps_addr_t object, void *p, size_t s), void *p, size_t s) + + Inspect :term:`formatted objects ` in an + :ref:`AMC pool `. + + *pool* is the pool whose formatted objects you want to inspect. + + *f* is a function that will be called for each formatted object in + the pool. It takes three arguments: *object* is the address of the + object; *p* and *s* are the corresponding arguments that were + passed to :c:func:`mps_amc_apply`. + + *p* and *s* are arguments that will be passed to *f* each time it + is called. This is intended to make it easy to pass, for example, + an array and its size as parameters. + + You may only call this function when the :term:`arena` is + :term:`parked`, for example, after calling + :c:func:`mps_arena_collect` or :c:func:`mps_arena_park`. + + The function *f* will be called on both :term:`data ` + and :term:`pad objects `. It is the job of *f* to + distinguish, if necessary, between the two. It may also be called + on :term:`dead` objects that the collector has not recycled or has + been unable to recycle. + + The function *f* may not allocate memory or access any + automatically-managed memory except within *object*. + + .. seealso:: + + :ref:`topic-scanning`. + + .. notes:: + + There is no equivalent function for other pool classes, but + there is a more general function + :c:func:`mps_arena_formatted_objects_walk` that inspects all + formatted objects in the arena. + + +.. c:function:: mps_res_t mps_fix(mps_ss_t ss, mps_addr_t *ref_io) + + Tell the MPS about a :term:`reference`, and possibly update it. This + function must only be called from within a :term:`scan function`. + + *ss* is the :term:`scan state` that was passed to the scan + function. + + *ref_io* points to the reference. + + Returns :c:macro:`MPS_RES_OK` if successful: in this case the reference + may have been updated (see the topic :ref:`topic-moving`), and the + scan function must continue to scan the :term:`block`. If it + returns any other result, the scan function must return that + result as soon as possible, without fixing any further references. + + .. deprecated:: 1.110 + + Use :c:func:`MPS_FIX12` instead. + + .. seealso:: + + :ref:`topic-scanning` and :ref:`topic-moving`. + + .. note:: + + If you want to call this between :c:func:`MPS_SCAN_BEGIN` and + :c:func:`MPS_SCAN_END`, you must use :c:func:`MPS_FIX_CALL` + to ensure that the scan state is passed correctly. + + +.. c:function:: mps_bool_t MPS_FIX1(mps_ss_t mps_ss, mps_addr_t ref) + + Tell the MPS about a :term:`reference`. This macro must only be + used within a :term:`scan function`, between + :c:func:`MPS_SCAN_BEGIN` and :c:func:`MPS_SCAN_END`. + + *ss* is the :term:`scan state` that was passed to the scan function. + + *ref* is the reference. + + Returns a truth value (:c:type:`mps_bool_t`) indicating whether + the reference is likely to be interesting to the MPS. If it + returns false, the scan function must continue scanning the + :term:`block`. If it returns true, the scan function must invoke + :c:func:`MPS_FIX2`, to fix the reference. + + .. seealso:: + + :ref:`topic-scanning`. + + .. note:: + + In the common case where the scan function does not need to do + anything between :c:func:`MPS_FIX1` and :c:func:`MPS_FIX2`, you can + use the convenience macro :c:func:`MPS_FIX12`. + + +.. c:function:: MPS_FIX12(mps_ss_t mps_ss, mps_addr_t *ref_io) + + Tell the MPS about a :term:`reference`, and possibly update it. This + macro must only be used within a :term:`scan function`, between + :c:func:`MPS_SCAN_BEGIN` and :c:func:`MPS_SCAN_END`. + + *ss* is the :term:`scan state` that was passed to the scan function. + + *ref_io* points to the reference. + + Returns :c:macro:`MPS_RES_OK` if successful: in this case the reference + may have been updated (see the topic :ref:`topic-moving`), and the + scan function must continue to scan the :term:`block`. If it + returns any other result, the scan function must return that + result as soon as possible, without fixing any further references. + + .. seealso:: + + :ref:`topic-scanning`. + + .. note:: + + The macro :c:func:`MPS_FIX12` is a convenience for the common + case where :c:func:`MPS_FIX1` is immediately followed by + :c:func:`MPS_FIX2`. + + +.. c:function:: MPS_FIX2(mps_ss_t mps_ss, mps_addr_t *ref_io) + + Tell the MPS about a :term:`reference`, and possibly update it. + This macro must only be used within a :term:`scan function`, + between :c:func:`MPS_SCAN_BEGIN` and :c:func:`MPS_SCAN_END`. + + *ss* is the :term:`scan state` that was passed to the scan function. + + *ref_io* points to the reference. + + Returns :c:macro:`MPS_RES_OK` if successful: in this case the reference + may have been updated (see the topic :ref:`topic-moving`), and the + scan function must continue to scan the :term:`block`. If it + returns any other result, the scan function must return that + result as soon as possible, without fixing any further references. + + .. seealso:: + + :ref:`topic-scanning`. + + .. note:: + + In the common case where the scan function does not need to do + anything between :c:func:`MPS_FIX1` and :c:func:`MPS_FIX2`, + you can use the convenience macro :c:func:`MPS_FIX12`. + + +.. c:function:: MPS_FIX_CALL(ss, call) + + Call a function from within a :term:`scan function`, between + :c:func:`MPS_SCAN_BEGIN` and :c:func:`MPS_SCAN_END`, passing + scan state correctly. + + *ss* is the :term:`scan state` that was passed to the scan function. + + *call* is an expression containing a call to a scan function. + + Returns the result of evaluating the expression *call*. + + 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 + have an embedded structure shared between two scan methods, you + must wrap the call with :c:func:`MPS_FIX_CALL` to ensure that the + scan state is passed correctly. + + In this example, the scan function ``obj_scan`` fixes the object's + ``left`` and ``right`` references, but delegates the scanning of + references inside the object's ``data`` member to the function + ``scan_data``. In order to ensure that the scan state is passed + correctly to ``scan_data``, the call must be wrapped in + ``MPS_FIX_CALL``. :: + + mps_res_t obj_scan(mps_ss_t ss, mps_addr_t base, mps_addr_t limit) + { + Object *obj; + mps_res_t res; + MPS_SCAN_BEGIN(ss) { + for (obj = base; obj < limit; obj++) { + if (MPS_FIX12(ss, &obj->left) != MPS_RES_OK) + return res; + MPS_FIX_CALL(ss, res = scan_data(ss, &obj->data)); + if (res != MPS_RES_OK) + return res; + if (MPS_FIX12(ss, &obj->right) != MPS_RES_OK) + return res; + } + } MPS_SCAN_END(ss); + return MPS_RES_OK; + } + + .. seealso:: + + :ref:`topic-scanning`. + + +.. c:macro:: MPS_RES_COMMIT_LIMIT + + A :term:`result code` indicating that an operation could not be + completed as requested without exceeding the :term:`arena commit + limit`. + + You need to deallocate something to make more space, or increase + the arena commit limit by calling + :c:func:`mps_arena_commit_limit_set`. + + .. seealso:: + + :ref:`topic-error`. + + +.. c:macro:: MPS_RES_LIMIT + + A :term:`result code` indicating that an operation could not be + completed as requested because of an internal limitation of the + MPS. The precise meaning depends on the function that returned the + code. Refer to the documentation of that function for details. + + .. seealso:: + + :ref:`topic-error`. + + +.. c:macro:: MPS_RES_MEMORY + + A :term:`result code` indicating that an operation could not be + 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 + the :term:`arena` (if you're using an arena for which that does + not happen automatically). + + .. seealso:: + + :ref:`topic-error`. + + .. note:: + + Failing to acquire enough memory because the :term:`arena + commit limit` would have been exceeded is indicated by + returning :c:macro:`MPS_RES_COMMIT_LIMIT`, not + ``MPS_RES_MEMORY``. + + .. note:: + + Running out of :term:`address space` (as might happen in + :term:`virtual memory` systems) is indicated by returning + :c:macro:`MPS_RES_RESOURCE`, not ``MPS_RES_MEMORY``. + + +.. c:macro:: MPS_RES_PARAM + + A :term:`result code` indicating that an operation could not be + completed as requested because an invalid parameter was specified + for the operation. The precise meaning depends on the function + that returned this result code. Refer to the documentation of that + function for details. + + .. seealso:: + + :ref:`topic-error`. + + +.. c:macro:: MPS_RES_RESOURCE + + A :term:`result code` indicating that an operation could not be + completed as requested because the MPS ran out of :term:`virtual + memory`. + + 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. + + .. seealso:: + + :ref:`topic-error`. + + +.. c:macro:: MPS_RM_CONST + + The :term:`root mode` for :term:`constant roots `. This tells the MPS that the :term:`client program` will + not change the :term:`root` after it is declared: tat is, scanning + the root will produce the same set of :term:`references + ` every time. Furthermore, for :term:`formatted roots + ` and :term:`table roots `, the client + program will not write to the root at all. + + .. seealso:: + + :ref:`topic-root`. + + .. note:: + + Currently ignored by the MPS. + + +.. c:macro:: MPS_RM_PROT + + The :term:`root mode` for :term:`protectable roots `. This tells the MPS that it may place a :term:`hardware + write barrier` on any :term:`pages ` which any part of the + :term:`root` covers. No :term:`format method` or :term:`scan + function` (except for the one for this root) may write data in + this root. They may read it. + + .. seealso:: + + :ref:`topic-root`. + + .. note:: + + You must not specify ``MPS_RM_PROT`` on a root allocated by + the MPS. + + .. note:: + + No page may contain parts of two or more protectable + roots. You mustn't specify ``MPS_RM_PROT`` if the client + program or anything other than (this instance of) the MPS is + going to protect or unprotect the relevant pages. + + +.. c:function:: mps_res_t mps_sac_alloc(mps_addr_t *p_o, mps_sac_t sac, size_t size, mps_bool_t has_reservoir_permit) + + Allocate a :term:`block` using a :term:`segregated allocation + cache`. If no suitable block exists in the cache, ask for more + memory from the associated :term:`pool`. + + *p_o* points to a location that will hold the address of the + allocated block. + + *sac* is the segregated allocation cache. + + *size* is the :term:`size` of the block to allocate. It does not + have to be one of the :term:`sizes classes ` of the + cache; nor does it have to be aligned. + + If *has_reservoir_permit* is true, the pool has permission to get + more memory from the :term:`reservoir` to satisfy this request. + + Returns :c:macro:`MPS_RES_OK` if successful: in this case the + address of the allocated block is ``*p_o``. The allocated block + can be larger than requested. Blocks not matching any size class + are allocated from the next largest class, and blocks larger than + the largest size class are simply allocated at the requested size + (rounded up to alignment, as usual). + + Returns :c:macro:`MPS_RES_MEMORY` if there wasn't enough memory, + :c:macro:`MPS_RES_COMMIT_LIMIT` if the :term:`arena commit limit` + was exceeded, or :c:macro:`MPS_RES_RESOURCE` if it ran out of + :term:`virtual memory`. + + .. seealso:: + + :ref:`topic-cache`. + + .. note:: + + There's also a macro :c:func:`MPS_SAC_ALLOC_FAST` that does + the same thing. The macro is faster, but generates more code + and does less checking. + + .. note:: + + The client 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 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 + can cause :term:`memory leaks `, because the size + of the block might be larger than you think. Naturally, the + cache must also be attached to the same pool. + + +.. c:function:: MPS_SAC_ALLOC_FAST(mps_res_t res_o, mps_addr_t *p_o, mps_sac_t sac, size_t size, mps_bool_t has_reservoir_permit) + + A macro alternative to :c:func:`mps_sac_alloc` that is faster + than the function but does less checking. The arguments are + identical to the function, except that the macro takes an + additional first argument, *res_o*, which must be an lvalue that + will store the :term:`result code`, and the macro doesn't evaluate + ``has_reservoir_permit`` unless it decides to access the pool. + + .. seealso:: + + :ref:`topic-cache`. + + +.. c:macro:: MPS_SAC_CLASS_LIMIT + + The number of :term:`size classes ` that + :c:func:`mps_sac_create` is guaranteed to accept. + + .. seealso:: + + :ref:`topic-cache`. + + +.. c:function:: void mps_sac_free(mps_sac_t sac, mps_addr_t p, size_t size) + + Free a :term:`block` using a :term:`segregated allocation + cache`. If the cache would become too full, some blocks may be + returned to the associated :term:`pool`. + + *sac* is the segregated allocation cache. + + *p* points to the block to be freed. This block must have been + allocated through a segregated allocation cache with the same + :term:`class structure`, attached to the same pool. (Usually, + you'd use the same cache to allocate and deallocate a block, but + the MPS is more flexible.) + + *size* is the :term:`size` of the block. It should be the size + that was specified when the block was allocated (the cache knows + what the real size of the block is). + + .. seealso:: + + :ref:`topic-cache`. + + .. note:: + + The client 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 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:: + + ``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 (either by + calling :c:func:`mps_sac_flush` or automatically), and may not + be detected at all, if intervening operations have obscured + symptoms. + + +.. c:function:: MPS_SAC_FREE_FAST(mps_sac_t sac, mps_addr_t p, size_t size) + + A macro alternative to :c:func:`mps_sac_free` that is faster than + the function but does no checking. The arguments are identical to + the function. + + .. seealso:: + + :ref:`topic-cache`. + + +.. c:function:: MPS_SCAN_BEGIN(mps_ss_t ss) + + Within a :term:`scan function`, set up local information required + by :c:func:`MPS_FIX1`, :c:func:`MPS_FIX2` and + :c:func:`MPS_FIX12`. The local information persists until + :c:func:`MPS_SCAN_END`. + + *ss* is the :term:`scan state` that was passed to the scan + function. + + .. seealso:: + + :ref:`topic-scanning`. + + .. 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 + have an embedded structure shared between two scan methods, you + must wrap the call with :c:func:`MPS_FIX_CALL` to ensure that the + scan state is passed correctly. + + +.. c:function:: MPS_SCAN_END(mps_ss_t ss) + + Within a :term:`scan function`, terminate a block started by + :c:func:`MPS_SCAN_BEGIN`. + + *ss* is the :term:`scan state` that was passed to the scan + function. + + .. seealso:: + + :ref:`topic-scanning`. + + .. note:: + + :c:func:`MPS_SCAN_END` ensures that the scan is completed, so + successful termination of a scan must invoke it. However, in + case of an error it is allowed to return from the scan + function 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 + have an embedded structure shared between two scan methods, you + must wrap the call with :c:func:`MPS_FIX_CALL` to ensure that the + scan state is passed correctly. + + +.. c:type:: 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*)``. + + The exact identity of this type is platform-dependent. Typical + identities are ``unsigned long`` and ``unsigned __int_64``. + + .. seealso:: + + :ref:`topic-platform`. + + +.. 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``. + + The value is platform-dependent. Typical values are 5 and 6. + + .. seealso:: + + :ref:`topic-platform`. + + +.. 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``. + + This value is platform-dependent. It is always a power of 2: + typical values are 32 and 64. + + .. seealso:: + + :ref:`topic-platform`. + + +.. c:function:: mps_res_t mps_ap_alloc_pattern_begin(mps_ap_t ap, mps_alloc_pattern_t alloc_pattern) + + Start a period of allocation that behaves according to an + :term:`allocation pattern`. The period persists until a + corresponding call to :c:func:`mps_ap_alloc_pattern_end`. + + *ap* is the :term:`allocation point` in which the patterned + allocation will occur. + + *alloc_pattern* is the allocation pattern. + + Returns :c:macro:`MPS_RES_OK` if the allocation pattern is + supported by this allocation point. At present this is always the + case, but in future this function may return another :term:`result + code` if the allocation pattern is not supported by the allocation + point. + + If :c:func:`mps_ap_alloc_pattern_begin` is used multiple times on + the same allocation point without intervening calls to + :c:func:`mps_ap_alloc_pattern_end`, the calls match in a + stack-like way, outermost and innermost: that is, allocation + patterns may nest, but not otherwise overlap. + + Some allocation patterns may additionally support overlap: if so, + the documentation for the individual pattern types will specify + this. + + .. seealso:: + + :ref:`topic-pattern`. + + +.. c:function:: mps_res_t mps_ap_alloc_pattern_end(mps_ap_t ap, mps_alloc_pattern_t alloc_pattern) + + End a period of allocation on an :term:`allocation point` that + behaves according to an :term:`allocation pattern`. + + *ap* is the allocation point in which the patterned allocation + occurred. + + *alloc_pattern* is the allocation pattern. + + Returns :c:macro:`MPS_RES_OK` if the period of allocation was + successfully ended, or :c:macro:`MPS_RES_FAIL` if there was no + corresponding call to :c:func:`mps_ap_alloc_pattern_begin`. + + .. seealso:: + + :ref:`topic-pattern`. + + +.. c:function:: mps_res_t mps_ap_alloc_pattern_reset(mps_ap_t ap); + + End all :term:`patterned allocation ` on an + :term:`allocation point`. + + *ap* is the allocation point on which to end all patterned + allocation. + + Returns :c:macro:`MPS_RES_OK`. It may fail in future if certain + allocation patterns cannot be ended for that allocation point at + that point in time. + + This function may be used to recover from error conditions. + + .. seealso:: + + :ref:`topic-pattern`. + + +.. c:function:: mps_res_t mps_ap_frame_pop(mps_ap_t ap, mps_frame_t frame) + + Declare that a set of :term:`blocks ` in a + :term:`allocation frame` are :term:`dead` or likely to be dead, + and pop the frame from the :term:`allocation point's ` frame stack. + + *ap* is the allocation point in which *frame* was pushed. + + *frame* is the allocation frame whose blocks are likely to be + dead. + + Returns a :term:`result code`. + + This function pops *frame*, making its parent the current + frame. Popping invalidates *frame* and all frames pushed since + *frame*. Popping *frame* also makes a declaration about the set of + blocks which were allocated in *frame* and all frames which were + pushed since *frame*. + + The interpretation of this declaration depends on the :term:`pool` + that the allocation point belongs to. Typically, :term:`manual + pool classes ` use this declaration to mean + that the blocks are dead and their space can be reclaimed + immediately, whereas :term:`automatic pool classes ` use this declaration to mean that the objects are likely + to be mostly dead, and may use this declaration to alter its + collection decisions. See the documentation for the pool class. + + In general a frame other than the current frame can be popped (all + frames pushed more recently will be invalidated as well, as + described above), but a pool class may impose the restriction that + only the current frame may be popped. This restriction means that + every push must have a corresponding pop. See the documentation + for the pool class. + + It is illegal to pass an invalid frame to any MPS function. In + particular, it is illegal to pop frames out of order (so the + sequence "A = push; B = push; pop A; pop B" is illegal) or to pop + the same frame twice (so the sequence "A = push, pop A, pop A" is + illegal). + + .. seealso:: + + :ref:`topic-frame`. + + +.. c:function:: mps_res_t mps_ap_frame_push(mps_frame_t *frame_o, mps_ap_t ap) + + Push a new :term:`allocation frame` onto an :term:`allocation + point's ` frame stack. + + .. seealso:: + + :ref:`topic-frame`. + + + + +

Arguments

+ +

mps_frame_t *frameReturn The frame return parameter. A new frame (declared by this function) is stored in this location if this function is successful.

+ +

mps_ap_t ap The allocation point in which the new frame is declared.

+ + +

Returned Values

+ +

A result code in the usual way. The creation of new frame objects (which is implicit in the action of this function) can consume resources, so this function can fail because there are insufficient resources. This function may fail if the correct protocol is not followed by the client.

+ + +

Description

+ +

This function declares a new frame in the specified allocation point, makes that new frame a child of the current frame, changes the current frame to be the newly created frame, and returns a handle to the frame. Frames have two important features: A single frame identifies a set of objects(those objects that are "allocated in the frame") which can be destroyed (or declared dead) in a pop operation (see mps_ap_frame_pop); They are arranged in a partially ordered sequence (this is important when the pop operation is used). A fuller and more useful description is found in the APstack protocol document (protocol.mps.alloc-point.stack).

+ + +

Example

+ +

[missing]

+ + +

Error Handling

+ +

Errors can either be because the client hasn't followed the correct protocol in which case there isn't much that we can recommend or else because some needed resource isn't available. The usual course of actions when short of resources is recommended.

+ + +

See Also

+ +

+ +mps_ap_frame_pop, +protocol.mps.alloc-point.stack

+ + +

Notes

+ + +.. c:function:: extern void mps_arena_clamp(mps_arena_t); + + +

Summary

+ +

mps_arena_clamp puts the specified arena into the clamped state.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ +

arena -- the arena to be put into the clamped state

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

mps_arena_clamp puts the specified arena into the clamped state. In the clamped state, no object motion will occur and the staleness of location dependencies will not change. All references to objects loaded while the arena is clamped will keep the same binary representation until after it is released.

+ +

In a clamped arena, incremental collection may still occur, but it will not be visible to the mutator and no new collections will begin. Space used by unreachable objects will not be recycled until the arena becomes unclamped.

+ + +

Example

+ + +

Error Handling

+ + +

See Also

+ +

+ +mps_arena_park, + +mps_arena_release

+ + +

Notes

+ + +.. c:function:: mps_arena_class_t mps_arena_class_cl(void) + + +

Summary

+ +

mps_arena_class_cl returns the client arena class.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ +

None.

+ + +

Returned Values

+ +

Returns the client arena class.

+ + +

Resources

+ +

mpsacl.h

+ + +

Description

+ +

This function is used to get hold of the client arena class, for the purpose of passing it to mps_arena_create.

+ + +

Example

+ +
+mps_arena_t arena;
+
+int main(void)
+{
+  void *block;
+  mps_res_t res;
+
+  block = malloc(ARENA_SIZE);
+  if(block == NULL) {
+    printf("Not enough memory!");
+    exit(1);
+  }
+
+  res = mps_arena_create(&arena, mps_arena_class_cl(), ARENA_SIZE, block);
+  if(res != MPS_RES_OK) {
+    printf("ARENA_SIZE too small");
+    exit(2);
+  }
+
+  /* rest of program */
+}
+
+ + +

Error Handling

+ +

None.

+ + +

See Also

+ +

+ +mps_arena_create

+ + +

Notes

+ +

A client arena gets its managed memory from the client. This memory block is passed when the arena is created. When creating a client arena, mps_arena_create takes two extra arguments:

+ +

mps_res_t mps_arena_create(mps_arena_t *mps_arena_o, mps_arena_class_t mps_arena_class_cl, size_t size, void *block)

+ +

block is the address of the memory block managed by the arena, andsize is its size in bytes. If mps_arena_create returns MPS_RES_MEMORY, then the block was too small to hold the internal arena structures.Allocate a (much) larger one, and try again. mps_arena_create returns MPS_RES_FAIL, if the MPS library is copy-protected by a security device, such as a dongle, and a valid security device cannot be found.

+ + +.. c:type:: mps_arena_class_t + + +

Summary

+ +

"m ps_arena_class_t " is the type of arena classes.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Type

+ +

typedef struct mps_arena_s *mps_arena_t;

+ +

mps_arena_class_s is an incomplete structure type used only to declare the opaque type mps_arena_class_t.

+ + +

Description

+ +

mps_arena_class_t is the type of arena classes. It is opaque.

+ + +

Example

+ +

The definition of the client arena class in the "mpsacl.h" header:

+ +

extern mps_arena_class_t mps_arena_class_cl(void);

+ + +

See Also

+ + +

Notes

+ +

None.

+ + +.. c:function:: mps_arena_class_t mps_arena_class_vm(void) + + +

Summary

+ +

mps_arena_class_vm returns the virtual memory arena class.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ +

None.

+ + +

Returned Values

+ +

Returns the virtual memory arena class.

+ + +

Resources

+ +

mpsavm.h

+ + +

Description

+ +

This function is used to get hold of the virtual memory arena class, for the purpose of passing it to mps_arena_create. The VM arenas use the OS virtual memory interfaces to allocate memory. The chief consequence of this is that the arena can manage many more virtual addresses than it needs to commit memory to. This gives it flexibility as to where to place objects, which reduces fragmentation and helps make garbage collection more efficient.

+ +

This class is similar to mps_arena_class_vmnz but uses a more complex placement policy, which is more suited to copying garbage collection.

+ + +

Example

+ +
+mps_arena_t arena;
+
+int main(void)
+{
+  mps_res_t res;
+
+  res = mps_arena_create(&arena, mps_arena_class_vm(), ARENA_SIZE);
+  if(res != MPS_RES_OK) {
+    printf("Not enough memory!");
+    exit(1);
+  }
+
+  /* rest of program */
+
+}
+
+ + +

Error Handling

+ +

None.

+ + +

See Also

+ +

+ +mps_arena_create, + +mps_arena_class_vmnz

+ + +

Notes

+ +

A virtual memory arena gets its managed memory from the operating system's virtual memory services. An initial address space size is passed when the arena is created. When creating a virtual memory arena, mps_arena_create takes one extra argument:

+ +
mps_res_t mps_arena_create(mps_arena_t *arena_o,
+
+                           mps_arena_class_t arena_class_vm,
+
+                           size_t size)
+ +

size is the initial amount of virtual address space, in bytes, that the arena will reserve (this space is initially reserved so that the arena can subsequently use it without interference from other parts of the program, but most of it is not committed, so it don't require any RAM or backing store). The arena may allocate more virtual address space beyond this initial reservation as and when it deems it necessary. The MPS is most efficient if you reserve an address space that is several times larger than your peak memory usage.

+ +

mps_arena_create returns MPS_RES_RESOURCE if it fails to reserveadequate address space to place the arena in; possibly other parts of the program are reserving too much virtual memory. It returns MPS_RES_MEMORY when it fails to allocate memory for the internal arena structures; either size was far too small or you ran out of swap space.It returns MPS_RES_FAIL, if the library is copy-protected by a security device, such as a dongle, and a valid security device cannot be found.

+ +

Virtual memory arenas are not available on the Mac platforms, other than MacOS X. You will get a linking error, if you attempt to use this function.

+ + +.. c:function:: mps_arena_class_t mps_arena_class_vmnz(void); + + +

Summary

+ +

An arena class like mps_arena_class_vm but with a different placement policy.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ +

None.

+ + +

Returned Values

+ +

Returns the VMNZ arena class.

+ + +

Resources

+ +

mpsavm.h

+ + +

Description

+ +

Returns the VMNZ arena class (stands for Virtual Memory No Zones, if you really care.) This class can be passed to mps_arena_create in order to create a VMNZ arena. The VMNZ arenas use the OS virtual memory interfaces to allocate memory. The chief consequence of this is that the arena can manage many more virtual addresses than it needs to commit memory to. This gives it flexibility as to where to place objects.

+ +

This class is similar to mps_arena_class_vm but uses a simpler placement policy, that makes it slightly faster.

+ + +

Example

+ +
+mps_arena_t arena;
+
+int main(void)
+{
+  mps_res_t res;
+
+  res = mps_arena_create(&arena, mps_arena_class_vmnz(), ARENA_SIZE);
+  if(res != MPS_RES_OK) {
+    printf("Not enough memory!");
+    exit(1);
+  }
+
+  /* rest of program */
+
+}
+
+ +

+ + +

Error Handling

+ +

No errors.

+ + +

See Also

+ +

+ +mps_arena_create, + +mps_arena_class_vm

+ + +

Notes

+ +

This class takes an extra argument when used in mps_arena_create (see example).The extra parameter should be of type size_t. It specifies the amount of virtual address space, in bytes, that this arena should use. The arena will reserve this amount of virtual address space from the OS during initialization. It will not subsequently use any more address space(compare with mps_arena_class_vm which can grow).

+ +

mps_arena_create returns MPS_RES_RESOURCE if it fails to reserve adequate address space to place the arena in; possibly other parts of the program are reserving too much virtual memory. It returns MPS_RES_MEMORY when it fails to allocate memory for the internal arena structures; either size was far too small or you ran out of swap space.It returns MPS_RES_FAIL, if the library is copy-protected by a security device, such as a dongle, and a valid security device cannot be found.

+ +

Virtual memory arenas are not available on the Mac platforms, other than MacOS X. You will get a linking error, if you attempt to use this function.

+ + +.. c:function:: void mps_arena_collect(mps_arena_t arena); + + +

Summary

+ +

mps_arena_collect collects the arena and puts it in the parked state.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ +

arena the arena to collect

+ + +

Description

+ +

mps_arena_collect collects the arena and puts it in the parked state. Collecting the arena attempts to recycle as many unreachable objects as possible and reduce the size of the arena as much as possible (though in some cases it may increase because it becomes more fragmented). If you do not want the arena to be in the parked state, you must explicitly call mps_arena_release aftermps_arena_collect.

+ +

Note that the collector may not be able to recycle some objects (such as those near the destination of ambiguous references) even though they are not reachable.

+ + +

Example

+ +

[missing]

+ + +

Error Handling

+ +

No errors.

+ + +

See Also

+ +

+ +mps_arena_park, + +mps_arena_release

+ + +

Notes

+ +

None.

+ + +.. c:function:: size_t mps_arena_commit_limit(mps_arena_t arena) + + +

Summary

+ +

Returns the current commit limit associated with the arena in bytes.

+ + +

Associated Protocols

+ +

Arena

+ + +

Arguments

+ +

arena -- the arena

+ + +

Returned Values

+ +

Returns the current commit limit as a number of bytes in a size_t

+ + +

Description

+ +

Returns the current commit limit associated with the arena in bytes. The commit limit can be changed using the function mps_commit_limit_set. The commit limit is used to control how much memory the MPS can obtain from the OS. See Arena Protocol for details.

+ + +

Example

+ +

limit = mps_arena_commit_limit(arena);

+ + +

Error Handling

+ +

No errors.

+ + +

See Also

+ +

+ +mps_arena_committed, + +mps_arena_commit_limit_set

+ + +

Notes

+ +

None.

+ + +.. c:function:: mps_res_t mps_arena_commit_limit_set(mps_arena_t arena, size_t limit) + + +

Summary

+ +

Changes the current commit limit associated with the arena.

+ + +

Associated Protocols

+ +

Arena

+ + +

Arguments

+ +

arena -- the arena

+ +

limit -- the new commit limit in bytes

+ + +

Returned Values

+ +

Returns a result code.

+ + +

Description

+ +

The commit limit of the arena is set to the limit given. The commit limit controls how much memory the MPS will obtain from the OS. See Arena Protocol for details. The commit limit cannot beset to a value that is lower than the number of bytes that the MPS is using. If an attempt is made to set the commit limit to a value greater than or equal to that returned bymps_arena_committed then it will succeed. If an attempt is made to set the commit limit to a value less than that returned by mps_arena_committed then it will succeed only if the amount committed by the MPS can be reduced by reducing the amount of spare committed memory; in such a case the spare committed memory will be reduced appropriately and the attempt will succeed.

+ + +

Example

+ +
+do {
+  res = mps_arena_commit_limit_set(arena, limit - 100 * 1024);
+  if(res != MPS_RES_OK)
+    flush_caches();
+} while(res != MPS_RES_OK);
+
+ + +

Error Handling

+ +

Returns MPS_RES_OK when successful, and some other result code when not.

+ + +

See Also

+ +

+ +mps_arena_committed, + +mps_arena_commit_limit, + +mps_arena_spare_commit_limit_set

+ + +

Notes

+ +

mps_arena_commit_limit_set puts a limit on all memory committed by the MPS. The"spare committed" memory can be limited separately with mps_arena_spare_commit_limit_set. Note that "spare committed" memory is subject to both limits; there cannot be more spare committed memory than the spare commit limit, and there can't be so much spare committed memory that there is more committed memory than the commit limit.

+ + +.. c:function:: extern size_t mps_arena_committed(mps_arena_t arena) + + +

Summary

+ +

mps_arena_committed returns the amount of memory (backing store) in use by the arena, both for storing client objects and for its own data structures.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ +

arena -- the arena

+ + +

Returned Values

+ +

Returns a number of bytes (the amount of committed memory) as a size_t.

+ + +

Description

+ +

mps_arena_committed returns the amount of memory (backing store) in use by the arena (also known as "committed memory"). The value returned is a number of bytes.

+ +

Committed memory may be used both for storing client objects and for storing MPS datastructures. In addition the MPS maintains committed memory which is not being used (for either of the above purposes). This memory is known as "spare committed" memory (see mps_arena_spare_committed). The amount of "spare committed" memory can change atany time, in particular in will be reduced as appropriate in order meet client requests.

+ +

The reasons that the committed memory (as return by this function) might be large than the sum of the sizes of client allocated objects are:

+ +
    + +

  • some memory is used internally by the MPS to manage its own data structures and to record information about client objects (such as free lists, page tables, colour tables, statistics, etc).

    • + +

  • operating systems (and hardware) typically restrict programs to requesting and releasing memory with a certain granularity (for example, pages), so extra memory is committed when this rounding is necessary.

    • + +

  • there might be "spare committed" memory.

    • + +
+ +

The amount of committed memory is a good measure of how much virtual memory resource ("swapspace") the MPS is using from the OS.

+ +

This function may be called whether the arena is unclamped, clamped or parked, if called when the arena in unclamped then the value may change after this function returns. A possible use might be to call it just after mps_arena_collect to (over-)estimate the size of the heap.

+ +

If you want to know how much memory the MPS is using then you're probably interested in the value mps_arena_committed() - mps_arena_spare_committed().

+ +

The amount of committed memory can be limited with the function mps_arena_commit_limit.

+ + +

Example

+ + +

Error Handling

+ + +

See Also

+ +

+ +mps_arena_collect, + +mps_arena_clamp, + +mps_arena_park, + +mps_arena_release

+ + +

Notes

+ +

-

+ + +.. c:function:: mps_res_t mps_arena_create(mps_arena_t *mps_arena_o, mps_arena_class_t mps_arena_class, ...) + + +

Summary

+ +

mps_arena_create is used to create an arena.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ +

mps_arena_o pointer to a variable to store the new arena in

+ +

mps_arena_class the arena class

+ +

... initialization arguments for the arena class

+ + +

Initial/Default Values

+ +

Different for each arena class. See mps_arena_class_*.

+ + +

Returned Values

+ +

If the return value is MPS_RES_OK, the new arena is in *mps_arena_o.

+ + +

Description

+ +

mps_arena_create is used to create an arena.

+ + +

Example

+ +
+mps_arena_t arena;
+
+int main(void)
+{
+  mps_res_t res;
+
+  res = mps_arena_create(&arena, mps_arena_class_vm(), ARENA_SIZE);
+  if(res != MPS_ RES_OK) {
+    printf("Not enough memory!");
+    exit(1);
+  }
+
+  /* rest of program */
+}
+
+ + +

Error Handling

+ +

mps_arena_create returns MPS_RES_FAIL, if the MPS library is copy-protected by a security device, such as a dongle, and a valid security device cannot be found.Other error codes are specific to each arena class. See mps_arena_class_*.

+ + +

See Also

+ +

+ +mps_arena_create_v, + +mps_arena_class_*, + +mps_arena_destroy

+ + +.. c:function:: mps_res_t mps_arena_create_v(mps_arena_t *mps_arena_o, mps_arena_class_t mps_arena_class, va_list args) + + +

Summary

+ +

mps_arena_create_v is used to create an arena.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ +

mps_arena_o pointer to a variable to store the new arena in

+ +

mps_arena_class the arena class

+ +

args initialization arguments for the arena class

+ + +

Initial/Default Values

+ +

Different for each arena class. See mps_arena_class_*.

+ + +

Returned Values

+ +

If the return value is MPS_RES_OK, the new arena is in *mps_arena_o.

+ + +

Description

+ +

mps_arena_create_v is used to create an arena. It is exactly the same as mps_arena_create, except that it takes the arena class initialization arguments in a va_list.

+ + +

Error Handling

+ +

mps_arena_create_v returns MPS_RES_FAIL, if the MPS library is copy-protected by a security device, such as a dongle, and a valid security device cannot be found. Other error codes are specific to each arena class. See mps_arena_class_*.

+ + +

See Also

+ +

+ +mps_arena_create, + +mps_arena_class_*, + +mps_arena_destroy

+ +

function mps_arena_expose

+ + +

Summary

+ +

mps_arena_expose ensures that the MPS is not protecting any pages in the arena with read- or write-memory protection barriers.

+ +

Associated Protocols

+ +

Arena, clamp, park, protection

+ +

Syntax

+ +

mps_arena_expose(mps_arena);

+ +

Type

+ +
+extern void mps_arena_expose(mps_arena_t);
+
+ +

Arguments

+ +

(mps_arena_t mps_arena)

+ +

mps_arena is an MPS arena object.

+ +

Returned Values

+ +

None.

+ +

Resources

+ +

mps.h

+ +

Description

+ +

+This function will ensure that the MPS is not protecting (with memory +read/write barriers) any page in the arena. +This is expected to only be useful for debugging. +The arena is left in the clamped state (see mps_arena_clamp). +

+ +

+Since barriers are used during a collection, calling this function has +the same effect as calling mps_arena_park; all collections are +run to completion and the arena is clamped so that no new collections +begin. The MPS also uses barriers to maintain remembered sets (an +optimisation to help avoid scanning work); calling +this function will effectively destroy the remembered sets and any +optimisation gains. +

+ +

+Calling this function will introduce a slow down, primarily for two reasons: +any active collections will be run to completion before this function +returns; the next collection will have to recompute all the remembered +sets by scanning the entire heap. +

+ +

+The second aspect of the slow down, having the next collection recompute +the remembered sets, can be avoided by using mps_arena_unsafe_expose_remember_protection +instead of mps_arena_expose, and calling +mps_arena_unsafe_restore_protection +before calling mps_arena_release. +Those functions have unsafe aspects and place restrictions on what the +client can do (basically no exposed data can be changed). +

+ +

Example

+ +

None.

+ +

Error Handling

+ +

There can be no errors.

+ +

See Also

+ +mps_arena_clamp, +mps_arena_park, +mps_arena_release, +mps_arena_unsafe_expose_remember_protection, +mps_arena_unsafe_restore_protection + + +

function mps_arena_formatted_objects_walk

+ + +

Summary

+ +

mps_arena_formatted_objects_walk is used to iterate over all formatted objects in the MPS heap.

+ + +

Associated Protocols

+ +

None.

+ + +

Syntax

+ +

mps_arena_formatted_objects_walk(mps_arena, client_step_function, client_step_closure_p,client_step_closure_s);

+ + +

Type

+ +
+extern void mps_arena_formatted_objects_walk(mps_arena_t,
+  mps_formatted_objects_stepper_t, void *,
+  size_t);
+
+ + +

Arguments

+ +

(mps_arena_t mps_arena, mps_formatted_objects_stepper_t stepper, void *p, size_t s)

+ +

mps_arena is an MPS arena object.

+ +

stepper is a client-supplied function (pointer) of the right type (see mps_formatted_objects_stepper_t). This function is applied to every object in all formatted pools. This function should take the argument list (mps_addr_t object, mps_fmt_t format,mps_pool_t pool, void *p, size_t s) and return void. object is the object to which the function is being applied. format is the format (an MPS format object) of the object. pool is the pool in which the object resides. p and s are copies of the corresponding values that the client passed into mps_arena_formatted_objects_walk originally.

+ +

p and s are passed into the function specified by the stepper argument whenever the MPS calls that function. See mps_formatted_objects_stepper_t.

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

mps_arena_formatted_objects_walk is used to iterate over all formatted objects in the MPS heap. A client-supplied function is called for every object in all formatted pools; the object, the format, and the pool are passed to the user supplied function, as well as user supplied closure variables.

+ +

Applies stepper function to a pool-class-specific collection of objects (that is, the pool class determines which objects in its instances get walked). Typically pool classes will arrange that all validly formatted objects are walked. During a trace this will in general be only the black objects, though the leaf pool class (LO), for example, will walk all objects since they are validly formatted whether they are black or white. Padding objects may be walked at the pool classes discretion, the client should handle this case.

+ +

The user supplied stepper function is called in a restricted context. It may not in general call any MPS function.

+ +

Example

+ +

[not yet]

+ + +

Error Handling

+ +

There are none.

+ + +

See Also

+ +

+ +mps_amc_apply (the +historical walker), + +mps_formatted_objects_stepper_t

+ + +

Notes

+ + +.. c:function:: extern mps_bool_t mps_arena_has_addr(mps_arena_t arena, mps_addr_t addr); + + +

Summary

+ +

mps_arena_has_addr tests whether an address is managed by a particular arena.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ +

arena an arena

+ +

addr an address

+ + +

Returned Values

+ +

A boolean. Returns true if the address is managed by the arena, false otherwise.

+ + +

Description

+ +

+mps_arena_has_addr determines +whether a particular address is managed by a particular arena. An arena +manages a portion of total address space available on the hardware +architecture. No two arenas overlap so for any particular address this +function will return true for at most one arena. In general not all the +architecture addresses are managed by some arena; some addresses will not +be managed by any arena. This is what allows the MPS to cooperate with +other memory managers, shared object loaders, memory mapped file I/O, +and such like - it does not steal the whole address space. +

+

+The results from this function are true only for the instant at which +the function returned. In some circumstances the results may +immediately become invalidated (for example, a garbage collection may +occur, the address in question may become free, the arena may choose to +unmap the address and return storage to the operating system); for +reliable results call this function whilst the arena is parked. +

+ +

Example

+ + +

Error Handling

+ +

Can't fail.

+ + +

See Also

+ +

+ +mps_arena_park used to park an +arena

+ +

Notes

+ +

None.

+ + +.. c:function:: extern void mps_arena_park(mps_arena_t arena); + + +

Summary

+ +

mps_arena_park puts the specified arena into the parked state.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ +

arena the arena to park

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

mps_arena_park puts the specified arena into the parked state. While an arena is parked,no object motion will occur and the staleness of location dependencies will not change. All references to objects loaded while the arena is parked will keep the same binary representation until after it is released.

+ +

Any current collection is run to completion before the arena is parked, and no new collections will start. When an arena is in the parked state, it is necessarily not in the middle of a collection.

+ + +

Example

+ + +

Error Handling

+ +

Can't fail.

+ + +

See Also

+ +

+ +mps_arena_clamp, + +mps_arena_release

+ + +

Notes

+ +

None.

+ + +.. c:function:: extern void mps_arena_release(mps_arena_t); + + +

Summary

+ +

mps_arena_release puts the specified arena into the unclamped state.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

mps_arena_release puts the specified arena into the unclamped state. While an arena is unclamped, garbage collection, object motion, and other background activity can take place.

+ + +

Example

+ + +

Error Handling

+ +

Can't fail.

+ + +

See Also

+ +

+ +mps_arena_clamp, + +mps_arena_park

+ + +

Notes

+ +

None.

+ + +

function mps_arena_roots_walk

+ + +

Summary

+ +

mps_arena_roots_walk is used to iterate over all roots of the MPS heap.

+ + +

Associated Protocols

+ +

None.

+ + +

Syntax

+ +

mps_arena_roots_walk(mps_arena, client_step_function, client_step_closure_p,client_step_closure_s);

+ + +

Type

+ +
+  extern void mps_arena_roots_walk(mps_arena_t,
+  mps_roots_stepper_t, void *,
+  size_t);
+
+ + +

Arguments

+ +

(mps_arena_t mps_arena, mps_roots_stepper_t stepper, void *p, size_t s)

+ +

mps_arena in an MPS arena object.

+ +

stepper is a client-supplied function (pointer) of the right type (see mps_roots_stepper_t). This function is applied to every reference to the heap from every root object registered with the arena. This function should take the argument list (mps_addr_t *ref, mps_root_t root, void *p, size_t s). ref is the address of a root which references an object in the arena. root is the registered root (an MPS root object) of which ref is a single reference, p and s are copies of the corresponding values that the client passed into mps_arena_roots_walk originally.

+ +

p and s are passed into the function specified by the stepper argument whenever the MPS calls that function. See mps_roots_stepper_t

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

mps_arena_roots_walk is used to iterate over all roots of the MPS heap. A client-supplied function is called for every root reference which points to an object in any automatically managed pools; the address of the root reference and the MPS root object are passed to the user supplied function, as well as some closure variables.

+ +

May only be called when the arena is in the parked state.

+ +

Applies stepper to each reference in any roots registered with the arena and which point to objects in automatically managed pools. If the root has rank MPS_RANK_AMBIG then the reference might not be to the start of an object; the client should handle this case. There is no guarantee that the reference corresponds to the actual location that holds the pointer to the object (since this might be a register, for example) - but the actual location will be passed if possible. This may aid analysis of roots via a debugger.

+ +

+ + +

Example

+ +

[not yet]

+ + +

Error Handling

+ +

There are none.

+ + +

See Also

+ +

+ +mps_roots_stepper_t

+ +

+ +mps_arena_formatted_objects_walk

+ + +

Notes

+ + +.. c:function:: extern size_t mps_arena_spare_commit_limit(mps_arena_t arena) + + +

Summary

+ +

Retrieves the value of the spare commit limit (previously set with mps_arena_spare_commit_limit_set).

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ +

mps_arena_t arena

+ +

Specifies the arena to retrieve the spare commit limit of.

+ + +

Returned Values

+ +

Returns, as a size_t, the value of the spare commit limit.

+ + +

Description

+ +

Returns the current value of the spare commit limit which is the value most recently set with mps_arena_spare_commit_limit_set. (See mps_arena_spare_commit_limit_set fordetails).

+ + +

Example

+ +

[missing]

+ + +

Error Handling

+ +

There are no errors.

+ + +

See Also

+ +

+ +mps_arena_spare_commit_limit_set

+ + +

Notes

+ +

None.

+ + +.. c:function:: extern void mps_arena_spare_commit_limit_set(mps_arena_t arena, size_t limit) + + +

Summary

+ +

Sets the limit of the amount of spare committed memory.

+ + +

Associated Protocols

+ +

Arena.

+ + +

Arguments

+ +

mps_arena_t arena

+ +

The arena to which the new limit should apply.

+ +

size_t limit

+ +

The value of the new limit (specified in bytes).

+ + +

Resources

+ +

mps.h

+ +

+ + +

Description

+ +

The limit argument specifies a new "spare commit limit". The spare commit limit specifies the maximum amount of bytes of "spare committed" memory the MPS is allowed to have. Setting it to a value lower than the current amount of spare committed memory would immediately cause sufficient spare committed memory to be uncommitted so as to bring the value under the limit. In particular setting to 0 will mean that the MPS will have no "spare committed" memory.

+ +

"spare committed" memory is the term for describing memory which the arena is managing as free memory (so not in use by any pool and not otherwise in use for obscure internal reasons) but which remains committed (mapped from the OS). It is used by the arena to (attempt to) avoid calling the OS to repeatedly unmap and map areas of VM. "spare committed" memory is counted as committed memory as counted by mps_arena_committed and restricted by mps_arena_commit_limit.

+ +

Non-VM arenas do not have this concept, but they support the two functions mps_arena_spare_commit_limit and mps_arena_spare_commit_limit_set. The functions simply get and retrieve a value but do nothing else in that case.

+ +

Initially the value is some configuration-dependent value.

+ +

The value of the limit can be retrieved with mps_arena_spare_commit_limit.

+ + +

Example

+ +

[missing]

+ + +

Error Handling

+ +

There are no errors.

+ + +

See Also

+ +

+ +mps_arena_spare_commit_limit

+ + +

Notes

+ +

None.

+ + +.. c:function:: size_t mps_arena_spare_committed(mps_arena_t); + + +

Summary

+ +

Returns the number of bytes of spare committed memory.

+ + +

Associated Protocols

+ +

Memory

+ + +

Arguments

+ +

mps_arena_t mps_arena

+ +

The arena to which the query applies.

+ + +

Returned Values

+ +

Returns the number of bytes of spare committed memory.

+ + +

Description

+ +

"Spare committed" memory is the term for describing memory which the arena is committed from the OS but which is free (so not in use by any pool and not otherwise in use for obscure internal reasons). It is used by the arena to (attempt to) avoid calling the OS to repeatedly uncommit and commit areas of VM (because calling the OS to commit and uncommit memory is typically expensive)."Spare committed" memory can be used for grant client requests; if this is done when the MPS would otherwise have had to call the OS to commit more memory then the MPS has avoid some OS calls.

+ +

"spare committed" memory is counted as part of committed memory. The amount of committed memory can be retrieved with mps_arena_committed (see mps_arena_committed).

+ +

The amount of "spare committed" memory can be limited by using mps_arena_spare_commit_limit_set (see mps_arena_spare_commit_limit_set ), and the value of that limit can be retrieved with mps_arena_spare_commit_limit (see mps_arena_spare_commit_limit ). This is analogous to the functions for limiting the amount of committed memory.

+ + +

Example

+ +

[missing]

+ + +

Error Handling

+ +

[missing]

+ + +

See Also

+ +

+ +mps_arena_spare_commit_limit_set, + +mps_arena_spare_commit_limit

+ + +

Notes

+ +

None.

+ + +

function mps_arena_unsafe_expose_remember_protection

+ + +

Summary

+ +

mps_arena_unsafe_expose_remember_protection is like mps_arena_expose but additionally indicates that the MPS should remember some internal state which can be used later to avoid slow down. This function is potentially unsafe and must be used carefully.

+ +

Associated Protocols

+ +

+Arena, clamp, park, protection +

+ +

Syntax

+ +

mps_arena_unsafe_expose_remember_protection(mps_arena);

+ +

Type

+ +
+extern void mps_arena_unsafe_expose_remember_protection(mps_arena_t);
+
+ +

Arguments

+ +

(mps_arena_t mps_arena)

+ +

mps_arena is an MPS arena object.

+ +

Returned Values

+ +

None.

+ +

Resources

+ +

mps.h

+ +

Description

+ +

+This function does the same as mps_arena_expose in that it ensures +the MPS is not protecting any page in the arena and also clamps the +arena. +Additionally, using this function indicates to the MPS that it should +remember the protection state internally. +Later on the client should indicate that the remembered protection state +should be restored by using the mps_arena_unsafe_restore_protection +function. +Restore the remembered protections is only safe if the contents of the +exposed pages have not been changed; therefore this function should only +be used if you do not intend changing the pages, and the remembered +protection must only be restored if the pages have not been changed. +

+ +

+Releasing the arena from the clamped state, by calling mps_arena_release, will cause the MPS to +forget the remembered state. Restoring the remembered protection state, +using mps_arena_unsafe_restore_protection, +will also cause the MPS to forget the remembered state. +

+ +

+The MPS will remember the protection state if resources (memory) are +available. +If memory is low then only some or possibly none of the protection state +will be remembered, with a corresponding inability to avoid slow down +later. +It is not possible for the client to tell whether the MPS has in fact +remembered the protection state. +

+ + +

Example

+ +

None.

+ +

Error Handling

+ +

There can be no errors.

+ +

See Also

+ +mps_arena_clamp, +mps_arena_unsafe_restore_protection + + +

function mps_arena_unsafe_restore_protection

+ + +

Summary

+ +

mps_arena_unsafe_restore_protection restores the protection state that the MPS remembered when the client called mps_arena_unsafe_expose_remember_protection. If used correctly this should avoid any slow down that would otherwise occur.

+ +

Associated Protocols

+ +

+Arena, clamp, park, protection +

+ +

Syntax

+ +

mps_arena_unsafe_restore_protection(mps_arena);

+ +

Type

+ +
+extern void mps_arena_unsafe_restore_protection(mps_arena_t);
+
+ +

Arguments

+ +

(mps_arena_t mps_arena)

+ +

mps_arena is an MPS arena object.

+ +

Returned Values

+ +

None.

+ +

Resources

+ +

mps.h

+ +

Description

+ +

+This function restores the protection that the MPS has remembered +(during a period when the arena is exposed). +The client can cause the MPS to remember the protection state by using +the mps_arena_unsafe_expose_remember_protection +function. +

+ +

The point of remember and restoring the protection state is to avoid the slow down that happens when mps_arena_expose is used. Normally when this function is used the next garbage collection will be slow because the MPS has to do a lot of work to recover remembered sets; normally the remembered sets are preserved by the MPS protecting the relevant pages, but if the protection is removed then the remembered sets have to be discarded and recomputed. This recomputation of remembered sets can be avoided by using mps_arena_unsafe_expose_remeber_protection instead, and using mps_arena_unsafe_restore_protection to restore the remembered protections instead of recomputing them.

+ +

+This function has unsafe aspects. +In order for it to be used safely the client must not have changed the +exposed data between the call to mps_arena_unsafe_expose_remember_protection +and mps_arena_unsafe_restore_protection. +If the client has changed the exposed data then +mps_arena_unsafe_restore_protection +must not be called - simply call mps_arena_release to continue normal +collections. +

+ +

+Note that this function does not release the arena from the clamped +state; +mps_arena_release should be called to continue normal +collections. +

+ +

+Calling this function causes the MPS to forget the remember protection +state; as a consequence the same remembered state cannot be restored +more than once. +

+ +

Example

+ +

None.

+ +

Error Handling

+ +

There can be no errors.

+ +

See Also

+ +mps_arena_release, +mps_arena_unsafe_expose_remember_protection + + +

function mps_bool_t

+ + +

Summary

+ +

mps_bool_t is a transparent type, equivalent to int, that is used in the MPS C interfaceto indicate that a boolean value is intended.

+ + +

Associated Protocols

+ +

Not applicable.

+ + +

Syntax

+ +

Not applicable.

+ + +

Structure

+ +

Not applicable.

+ + +

Type

+ +

typedef int mps_bool_t;

+ + +

Description

+ +

When used as an input parameter to the MPS, a value of 0 indicates "false" and any other value indicates "true". As an output parameter or function return from the MPS, 0 indicates "false",and 1 indicates "true". Note that an mps_bool_t value can be used in a conditional context, such as in an "if" statement.

+ + +

Example

+ +
+  if(mps_ld_isstale(&ld, space, obj)) {
+    mps_ld_reset(&ld, space);
+    mps_ld_add(&ld, space, obj);
+  }
+
+ + +

See Also

+ + +

Notes

+ +

None.

+ + +

function mps_class_amc

+ + + +

+ + +

Summary

+ +

mps_class_amc returns the pool class object for the Automatic Mostly Copying pool class.

+ + +

Associated Protocols

+ +

Pool

+ + +

Syntax

+ +

mps_class_t mps_class_amc(void)

+ + +

Arguments

+ +

No arguments.

+ + +

Returned Values

+ +

Returns a pool class object.

+ + +

Resources

+ +

mpscamc.h

+ + +

Description

+ +

This function returns an object of type mps_class_t which represents the Automatic MostlyCopying pool class.

+ +

This pool class requires an extra argument when used in mps_pool_create:

+ +
  res = mps_pool_create(&pool, arena, mps_class_amc(), format);
+ +

The extra argument, format, should be of type mps_fmt_t and specifies the format of the objects allocated in the pool.

+ +

An AMC pool is both scannable and collectable. Objects may contain exact references to other objects that will preserve such other objects. Objects may be reclaimed if they are not reachable from a root. Objects may move during collection, unless reachable via a (direct) ambiguous reference. Objects in an AMC pool may be registered for finalization. Exact (that is, non-ambiguous)references into an object in an AMC pool must be to the start of the object.

+ +

The AMC pool class exploits assumptions about object lifetimes and inter-connection variously referred to as "the generational hypothesis". In particular, the following tendencies will be efficiently exploited by such a pool:

+ +

- Most objects die young;

+ +

- Objects that don't die young will live a long time;

+ +

- Most references are backwards in time.

+ +

mps_ap_frame_push and mps_ap_frame_pop may be used on an allocation point in an AMC pool.They do not declare the affected objects to be definitely dead (compare with the SNC pool class),but have an undefined effect on the collection strategy.

+ +

If an allocation point is created in an AMC pool, the call to mps_ap_create will take no additional parameters.

+ +

+ + +

Example

+ + +

See Also

+ +

+ +mps_ap_frame_pop, + +mps_ap_frame_push, + +mps_ap_create

+ + +

function mps_class_mvff

+ + + +

+ + +

Summary

+ +

Used as a parameter to mps_pool_create to create an MVFF pool.

+ + +

Associated Protocols

+ +

Pool, Allocation Points.

+ + +

Type

+ +

mps_class_t mps_class_mvff(void)

+ + +

Arguments

+ +

None.

+ + +

Returned Values

+ +

The function returns a class object that can be passed to mps_pool_create.

+ + +

Resources

+ +

mpscmvff.h

+ + +

Description

+ +

MVFF pools implement a first-fit policy. The pool requires six parameters to pool creation:

+ +
    + +

  • mps_size_t extendBy -- The size of segment to allocate by default;

    • + +

  • mps_size_t avgSize -- The average size of objects to be allocated;

    • + +

  • mps_align_t alignment -- The alignment of addresses for allocation (and freeing) in thepool;

    • + +

  • mps_bool_t slotHigh

    • + +

  • mps_bool_t arenaHigh

    • + +

  • mps_bool_t firstFit

    • + +
+ +

+ The alignment is the alignment of ranges that can be allocated and freed. If an unaligned size is passed to mps_alloc or mps_free, it will be rounded up to the pool's alignment. The minimum alignment supported by pools of this class is + + sizeof(void *). +

+ +

The three boolean parameters may be set to (0, 0, 1) or (1, 1, 1). No other settings of these parameters is currently recommended.

+ +

Buffered allocation (mps_reserve and mps_commit) is also supported, but in that case, the policy is rather different: buffers are filled worst-fit, and allocation is always upwards from the base. The arenaHigh parameter regulates whether new segments are acquired at high or low addresses;the slotHigh and firstFit parameters do not affect buffered allocation. Buffered and unbuffered allocation can be used at the same time, but in that case, the first allocation point must be created before any call to mps_alloc.

+ +

Cached allocation ( MPS_SAC_ALLOC and MPS_SAC_FREE ) is also supported, but in that case,the policy is a little different: allocation from the cache follows its own policy (typicallyfirst-fit), and only when the cache needs to acquire more blocks from the underlying MVFF pool does it use the usual algorithm to choose blocks for the cache.

+ + +

Example

+ +
+  if(mps_pool_create(&pool, arena, mps_class_mvff(), 8 * 1024, 135, 4, 0, 0, 1)
+     != MPS_RES_OK) {
+    printf("Error creating pool!");
+    exit(2);
+  }
+
+ + +

See Also

+ +

+ +mps_pool_create, + +mps_reserve, + +mps_commit.

+ + +

Notes

+ +

It is usually not advisable to use buffered and unbuffered allocation at the same time,because the worst-fit policy of buffer filling will grab all the large blocks, leading to severe fragmentation. Use two separate pools instead.

+ +

Note that using buffered allocation prevents (for obscure technical reasons) the pool from allocating across segment boundaries. This can cause added external fragmentation if objects are allocated that are a significant fraction of the segment size. (This quirk will disappear in a future version.)

+ + +

function mps_class_snc

+ + + +

+ + +

Summary

+ +

Returns the pool class object (of type mps_class_t) for the Stack No Check pool class.

+ + +

Associated Protocols

+ +

Pool.

+ + +

Syntax

+ +

mps_class_t mps_class_snc(void)

+ + +

Arguments

+ +

No arguments.

+ + +

Returned Values

+ +

Returns a pool class object.

+ + +

Resources

+ +

mpscsnc.h

+ + +

Description

+ +

This function returns an object of type mps_class_t which represents the Stack No Check pool class.

+ +

This pool class requires an extra argument when used in mps_pool_create:

+ +
  res = mps_pool_create(&pool, arena, mps_class_snc(), format);
+ +

The extra argument, format, should be of type mps_fmt_t and specifies the format of the objects allocated in the pool (in a similar way to mps_class_amc). The format should provide at least the methods: scan, skip, pad.

+ +

An SNC pool is scannable, in that objects may contain references to objects in other pools that will keep those objects alive (depending on rank). In this sense, an SNC pool is a de-facto root.

+ +

Exact references may point to (the start of) objects in an SNC pool, but will have no effect on whether those objects are either scanned or kept alive.

+ +

If mps_ap_frame_pop is used on an allocation point in an SNC pool (after a corresponding call to mps_ap_frame_push), then the objects affected by the pop are effectively declared dead, and may be reclaimed by the collector. Extant references to such objects from reachable or de facto alive objects are safe, but such other objects should be dead; that is, such references must never be used.

+ +

If an allocation point is created in an SNC pool, then the call to mps_ap_create will take as an additional parameter the rank (of type mps_rank_t) of references in the objects to be created in that allocation point. Currently, only rank exact (mps_rank_exact) is supported.

+ +

Objects in an SNC pool may not be registered for finalization.

+ +

Objects in an SNC pool will not move.

+ +

+ + +

Example

+ + +

Nya

+ + +

Error Handling

+ +

Cannot fail.

+ +

+ + +

See Also

+ +

+ +mps_class_amc, + +mps_ap_frame_pop, + +mps_ap_frame_push, + +mps_ap_create

+ + +

mps_class_mvt

+ + +

Summary

+ +

mps_class_mvt is a function that returns the MVT pool class object.

+ + +

Associated Protocols

+ +

Allocation point.

+ + +

Syntax

+ +

mps_class_t mps_class_mvt(void);

+ + +

Type

+ +

C function

+ + +

Arguments

+ +

None.

+ + +

Returned Values

+ +

The MVT pool class object.

+ + +

Resources

+ +

mpscmv2.h

+ + +

Description

+ +

The function mps_class_mvt returns the MVT pool class object, which can be used to create an MVT pool instance by passing the class object as the mps_class_t (third) argument to mps_pool_create.

+ +

The MVT pool class manually manages variable-sized, unformatted objects. The MVT pool uses an allocation policy termed "temporal fit". Temporal fit attempts to place consecutive allocations next to each other. It relies on delaying reuse as long as possible to permit freed blocks to coalesce, thus maximizing the number of consecutive allocations that can be co-located. Temporal fit permits a very fast allocator and a deallocator competitive in speed with all other known policies.

+ +

+ Temporal fit is intended to take advantage of knowledge of object lifetimes, either + + apriori + + knowledge or knowledge acquired by profiling. The best performance of the MVT pool will be achieved by allocating objects with similar expected deathtimes together. +

+ +

A simple policy can be implemented to take advantage of MVT: Object size is typically well-correlated with object life-expectancy, and birthtime plus lifetime gives deathtime, so allocating objects of similar size sequentially from the same pool instance should result in objects allocated close to each other dying at about the same time.

+ +

An application that has several classes of objects of widely differing life expectancy will best be served by creating a different MVT pool instance for each life-expectancy class. A more sophisticated policy can use either the programmer's knowledge of the expected lifetime of an objector any characteristic of objects that correlates with lifetime to choose an appropriate pool instance to allocate in.

+ +

Allocating objects with unknown or very different deathtimes together will pessimize the space performance of MVT.

+ + +

Example

+ +
+  if(mps_pool_create(&pool, arena, mps_class_mvt(), 8, 32, 256, 70, 20)
+     != MPS_RES_OK) {
+   printf("Error creating pool!");
+   exit(2);
+ }
+
+ +

Error Handling

+ +

mps_class_mvt cannot result in an error.

+ + +

See Also

+ +

+ +mps_pool_create

+ + +

Notes

+ +

+ + Creation + +

+ +

The MVT pool class has five creation parameters:

+ +
+  mps_res_t mps_pool_create(mps_pool_t * pool, mps_arena_t arena,
+  mps_class_t mvt_class, size_t minimum_size,
+  size_t mean_size, size_t maximum_size,
+  mps_count_t reserve_depth mps_count_t fragmentation_limit);
+
+ +

Sizes

+ +

minimum_size, mean_size, and maximum_size are the minimum, mean, and maximum (typical) size in bytes of objects expected to be allocated in the pool. Objects smaller than minimum size may be allocated, but the pool is not guaranteed to manage them space-efficiently. Objects larger than maximum_size may be allocated, but the pool is not guaranteed to manage them space-efficiently.Furthermore, partial freeing is not supported for objects larger than maximum size; doing so will result in the storage of the object never being reused. Mean_size need not be an accurate mean,although the pool will manage mean_size objects more efficiently.

+ +

Reserve Depth

+ +

reserve_depth is the expected hysteresis of the object population. When pool objects are freed, the pool will retain sufficient storage to allocate reserve_depth objects of mean_size for near term allocations (rather than immediately making that storage available to other pools).

+ +

If a pool has a stable object population, one which only grows over the lifetime of the pool, or one which grows steadily and then shrinks steadily, use a reserve_depth of 0.

+ +

It is always safe to use a reserve depth of 0, but if the object population typically fluctuates in a range (e.g., the client program may repeatedly create and destroy a subset of objects in a loop), it is more efficient for the pool to retain enough storage to satisfy that fluctuation. For example, if a pool has an object population that typically fluctuates between 8,000and 10,000, use a reserve_depth of 2,000.

+ +

The reserve will not normally be available to other pools for allocation, even when it is not used by the pool. If this is undesirable, a reserve depth of 0 may be used for a pool whose object population does vary, at a slight cost in efficiency. The reserve does not guarantee any particular amount of allocation.

+ +

Fragmentation Limit

+ +

fragmentation_limit is a percentage in (0, 100] that can be used to set an upper limit on the space overhead of MVT in case object deathtimes and allocations do not correlate well.

+ +

If the free space managed by the pool as a ratio of all the space managed by the pool exceeds the specified percentage, the pool will fall back to a first fit allocation policy,exploiting space more efficiently at a cost in time efficiency.

+ +

A fragmentation_limit of 0 would cause the pool to operate as a first-fit pool, at a significant cost in time-efficiency, therefore is not permitted.

+ +

A fragmentation_limit of 100 will cause the pool to use temporal fit (unless resources are exhausted). If the objects allocated in the pool have similar lifetime expectancies, this mode will have the best time- and space-efficiency. If the objects have widely varying lifetime expectancies,this mode will be time-efficient, but may be space-inefficient. An intermediate setting can be used to limit the space-inefficiency of temporal fit due to varying object life expectancies.

+ +

+ + Allocation + +

+ +

The MVT pool class only supports allocation through allocation points. See mps_ap_create.

+ +

+ + Deallocation + +

+ +

The MVT pool class supports explicit freeing. See mps_pool_free.

+ + +

Internal Notes

+ +

Need a life-expectancy parameter! How else will different instances choose their Loci?

+ +

Need an alignment parameter. Perhaps this is embedded in a format parameter (when all pools have at least a null format).

+ +

It is conceivable that a client would want to mix manual and automatic pools with the manual pool being able to be a root for the automatic. To do so, MVT would need to support formatted objects and scanning. This may be added someday.

+ +

Eventually the MM product will include profiling tools that will help determine object characteristics that correlate with object lifetime and suggest how to configure the appropriate number of MVT pool instances and what characteristics to dispatch on when choosing which instance to allocate from.

+ +

[From mail.ptw.1998-08-19.02-33(0) ]

+ +

Remember Wilson's statement that the goal of a memory manager is to exploit the regularities in allocation patterns? My intent in the interface parameters is to accept measurable regularities in object populations, then the implementation can exploit them.

+ +

Perhaps the pool should accept some description of the mean and deviation of the object sizes, object population, and object lifetimes. Is that what you are getting at? [Reserve_depth is in some sense a deviation.]

+ + +.. c:type:: mps_class_t + + +

Summary

+ +

mps_class_t is the type of pool classes.

+ + +

Associated Protocols

+ +

Pool.

+ + +

Description

+ +

mps_class_t is the abstract type of pool classes. It is opaque. A pool class may be obtained by calling the class function for the appropriate class, such as mps_class_amc for the AMC class. A pool class is used when creating a pool with mps_pool_create or mps_pool_create_v.

+ + +

Example

+ + +

See Also

+ +

+ +mps_pool_create, + +mps_pool_create_v

+ + +

Notes

+ +

mps_class_s is an incomplete structure type used only to define mps_class_t.

+ + +.. c:function:: mps_res_t mps_finalize(mps_arena_t arena, mps_addr_t *object_ref) + + +

Summary

+ +

Registers an object for finalization.

+ + +

Associated Protocols

+ +

Finalization, message.

+ + +

Arguments

+ +

+ arena + -- the arena in which the object lives +

+ +

+ object_ref + -- a pointer to a reference to the object to be finalized +

+ + +

Returned Values

+ +

A result code.

+ + +

Description

+ +

This function registers the specified object for finalization. This object must be an object allocated from a pool in the specified arena. Violations of this constraint may not be checked by the MPS, and may be unsafe (cause the MPS to crash in undefined ways).

+ +

An object becomes finalizable if it is registered for finalization and the collector observes that it would otherwise be reclaimable. Once an object is finalizable the MPS may choose to finalize it (by posting a finalization message, see below) at any future time. Note that the subsequent creation of strong references to the object (from, say, weak references) may cause finalization to occur when an object is not otherwise reclaimable.

+ +

When an object is finalizable, it may be finalized up to N times, where N is the number of times it has been registered for finalization. When an object is finalized, it is also deregistered for finalization (so that it will not be finalized again from the same registration).

+ +

Finalization is performed by passing a finalization message to the client, containing an exact reference to the object. See the message protocol, mps_message_type_finalization, and mps_message_finalization_ref for details.

+ +

If an object is registered for finalization multiple times, then there may be multiple finalization messages on the queue at the same time. On the other hand it may be necessary to discard previous finalization messages for an object before all such messages are posted on the message queue. In other words a finalization message may prevent other finalizations of the same object from occurring until the message is deleted; or, it may not. We don't provide any guarantees either way. Clients performing multiple registrations must cope with both behaviors. In any case we expect it to be unusual for clients to register the same object multiple times.

+ +

Note that there is no guarantee that finalization will be prompt.

+ +

Weak references do not prevent objects from being finalized. At the point that an object is finalized, weak references will still validly refer to the object. The fact that an object is registered for finalization prevents weak references to that object from being deleted.

+ +

Note that there will be no attempt to finalize objects in the context of mps_arena_destroy or mps_pool_destroy. mps_pool_destroy should therefore not be invoked on pools containing objects registered for finalization.

+ +

Not all pool classes support finalization of objects. In general only pools that manage objects whose liveness is determined by garbage collection will support finalization of objects. For more information, see the Pool Class Catalog.

+ + +

Example

+ +

[missing]

+ + +

Error Handling

+ +

[missing]

+ + +

See Also

+ +

+ +mps_message_type_finalization, + +mps_rank_weak, + +mps_arena_destroy, + +mps_pool_destroy

+ + +

Notes

+ +

This function receives a pointer to a reference. This is to avoid placing the restriction on the client that the C call stack be a root.

+ + +.. c:type:: mps_fmt_A_s + + +

Summary

+ +

mps_fmt_A_s is a structure used to create object formats of variant A.

+ + +

Associated Protocols

+ +

Format.

+ + +

Type

+ +
+typedef struct mps_fmt_A_s {
+  mps_align_t     align;
+  mps_fmt_scan_t  scan;
+  mps_fmt_skip_t  skip;
+  mps_fmt_copy_t  copy;
+  mps_fmt_fwd_t   fwd;
+  mps_fmt_isfwd_t isfwd;
+  mps_fmt_pad_t   pad;
+} mps_fmt_A_s;
+
+ + +

Resources

+ +

+ mps.h +

+ + +

Description

+ +

Objects of this type are intended to be used in the creation of object formats. Object formats describe the layout of client objects.

+ +

mps_fmt_A_s is a structure that represents the particular collection of methods and values that describes an object format of variant A.

+ +

Broadly speaking, the object formats of this variant are suitable for use in copying or moving memory managers.

+ +

mps_fmt_A_s has the following methods: scan, skip, copy, fwd, isfwd, pad, and the following value:align.

+ +

align is an integer value defines the alignment of objects allocated with this format. It should be large enough to satisfy the alignment requirements of any field in the objects,and it cannot be larger than the arena alignment. For details of the methods, consult the reference pages for the type of each method.

+ + +

Example

+ +
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt my_format;
+  mps_res_t res;
+  mps_fmt_A_s my_format_A = { my_alignment, &my_scan, &my_skip, &my_copy, &my_fwd,
+                              &my_isfwd, &my_pad };
+
+  res = mps_fmt_create_A(&my_format, arena, &my_format_A);
+  assert(res != MPS_RES_OK);
+
+  return my_format;
+}
+
+ + +

See Also

+ +

+ +mps_fmt_create_A, + +mps_fmt_scan_t, + +mps_fmt_skip_t + +mps_fmt_copy_t, + +mps_fmt_fwd_t, + +mps_isfwd_t, + +mps_pad_t, + +mps_align_t, + +mps_fmt_B_s

+ + +.. c:type:: mps_fmt_A_t + + +

Summary

+ +

mps_fmt_A_t is the type pointer to mps_fmt_A_s.

+ + +

Associated Protocols

+ +

Format.

+ + +

Type

+ +
+typedef struct mps_fmt_A_s {
+  mps_align_t     align;
+  mps_fmt_scan_t  scan;
+  mps_fmt_skip_t  skip;
+  mps_fmt_copy_t  copy;
+  mps_fmt_fwd_t   fwd;
+  mps_fmt_isfwd_t isfwd;
+  mps_fmt_pad_t   pad;
+} mps_fmt_A_s;
+
+typedef struct mps_fmt_A_s *mps_fmt_A_t;
+
+ + +

Description

+ +

mps_fmt_A_t is the type pointer to mps_fmt_A_s. A value of this type represents a collection of methods and values that can be used to create a format object of type mps_fmt_t. This type represents a particular collection of methods and values; other collections are represented by other types.

+ +

Objects of type mps_fmt_A_t are intended to be used in the creation of object formats.Object formats describe the layout of client objects. The function mps_fmt_create_A takes an mps_fmt_A_t as one of its arguments and creates an object of type mps_fmt_t (an object format).

+ +

See the documentation of mps_fmt_A_s for further details.

+ + +

Example

+ + +

See Also

+ +

+ +mps_fmt_A_s, + +mps_fmt_t, + +mps_fmt_create_A

+ + +.. c:type:: mps_fmt_B_s + + +

Summary

+ +

mps_fmt_B_s is a transparent structure used to create object formats of variantB.

+ + +

Associated Protocols

+ +

Format.

+ + +

Type

+ +
+typedef struct mps_fmt_B_s {
+  mps_align_t     align;
+  mps_fmt_scan_t  scan;
+  mps_fmt_skip_t  skip;
+  mps_fmt_copy_t  copy;
+  mps_fmt_fwd_t   fwd;
+  mps_fmt_isfwd_t isfwd;
+  mps_fmt_pad_t   pad;
+  mps_fmt_class_t mps_class;
+} mps_fmt_B_s;
+
+ + +

Description

+ +

Objects of this type are intended to be used in the creation of object formats. Object formats describe the layout of client objects. mps_fmt_B_s is a structure that represents the particular collection of methods and values that describes an object format of variant B.

+ +

mps_fmt_B_s is the same as mps_fmt_A_s except for the addition of the mps_class method. Broadly speaking, the object formats of variety B are suitable for use in copying or moving memory managers (just like variety A); the addition of the class method allows more information to be passed to various support tools (such as graphical browsers).

+ +

mps_fmt_B_s has the following methods: scan, skip, copy, fwd, isfwd, pad, mps_class, and the following value: align.

+ +

align is an integer value defines the alignment of objects allocated with this format. It should be large enough to satisfy the alignment requirements of any field in the objects, and it cannot be larger than the arena alignment. For details of the methods, consult the reference pages for the type of each method.

+ + +

Example

+ +
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt_B_s my_format_B = { my_alignment, &my_scan, &my_skip, &my_copy,
+                              &my_fwd, &my_isfwd, &my_pad, &my_class };
+  mps_fmt my_format;
+  mps_res_t res;
+
+  res = mps_fmt_create_B(&my_format, arena, &my_format_B);
+  assert(res != MPS_RES_OK);
+
+  return my_format;
+}
+
+ + +

See Also

+ +

+ +mps_fmt_create_B, + +mps_fmt_scan_t, + +mps_fmt_skip_t, + +mps_fmt_copy_t, + +mps_fmt_fwd_t, + +mps_isfwd_t, + +mps_pad_t, + +mps_align_t, + +mps_class_t, + +mps_fmt_A_s

+ + +

Notes

+ +

The mps_class field used to be called "class", but that was problematic for C++, so we changed it.

+ + +.. c:type:: mps_fmt_B_t + + +

Summary

+ +

mps_fmt_B_t is a type passed to mps_fmt_create_B. It represents the collection of methods and values used to create a mps_fmt_t. You are expected to declare and create structures of this type if you require an object of type mps_fmt_B_t.

+ + +

Associated Protocols

+ +

Format

+ + +

Structure

+ +
+typedef struct mps_fmt_B_s {
+  mps_align_t     align;
+  mps_fmt_scan_t  scan;
+  mps_fmt_skip_t  skip;
+  mps_fmt_copy_t  copy;
+  mps_fmt_fwd_t   fwd;
+  mps_fmt_isfwd_t isfwd;
+  mps_fmt_pad_t   pad;
+  mps_fmt_class_t class;
+} mps_fmt_B_s;
+
+ + +

Type

+ +

typedef struct mps_fmt_B_s *mps_fmt_B_t;

+ + +

Description

+ +

mps_fmt_B_t is the equivalent to mps_fmt_A_t that should be passed tomps_fmt_create_B. It is suitable for format variety A collectors that need to use tools that useclass information.

+ +

See the documentation for the symbol mps_fmt_B_s for further details.

+ + +

Example

+ + +

See Also

+ +

+ +mps_fmt_B_s, + +mps_fmt_t, + +mps_fmt_create_B, + +mps_fmt_A_t

+ + +

Notes

+ +

None.

+ + +.. c:type:: mps_fmt_auto_header_s + + +

Summary

+ +

mps_fmt_auto_header_s is a structure used to create object formats of variant auto_header.

+ + +

Associated Protocols

+ +

Format.

+ + +

Type

+ +
+
+typedef struct mps_fmt_auto_header_s {
+  mps_align_t     align;
+  mps_fmt_scan_t  scan;
+  mps_fmt_skip_t  skip;
+  mps_fmt_fwd_t   fwd;
+  mps_fmt_isfwd_t isfwd;
+  mps_fmt_pad_t   pad;
+  size_t          mps_headerSize;
+} mps_fmt_auto_header_s;
+
+
+ + +

Resources

+ +

+ mps.h +

+ + +

Description

+ +

Objects of this type are intended to be used in the creation of object formats. Object formats describe the layout of client objects. mps_fmt_auto_header_s isa structure that represents the particular collection of methods and values that describes an object format of variant auto_header.

+ +

Broadly speaking, the object formats of this variant are suitable for use in automatic memory management for objects with headers (hence the name). More precisely, this variant is intended for formats where the client's pointers point some distance into the memory block containing the object. This typically happens when the objects have a common header used for memory management or class system purposes, but this situation also arises when the low bits of a pointer are used for a tag. The MPS does not care what the reason is, only about the offset of the pointer in relation to the memory block.

+ +

mps_fmt_auto_header_shas the following methods: scan, skip, fwd, isfwd, pad, and the following values: align and mps_headerSize.

+ +

align is an integer value defines the alignment of objects allocated with this format. It should be large enough to satisfy the alignment requirements of any field in the objects, and it cannot be larger than the arena alignment.

+ +

mps_headerSize is the size of the header, i.e., the offset of a client pointer from the base the memory block. For details of the methods, consult the reference pages for the type of each method.

+ + +

Example

+ +
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt format;
+  mps_res_t res;
+  mps_fmt_auto_header_s format_desc = { my_alignment, &my_scan, &my_skip, &my_fwd,
+                                        &my_isfwd, &my_pad, HEADER_SIZE };
+
+  res = mps_fmt_create_auto_header(&format, arena, &format_desc);
+  assert(res != MPS_RES_OK);
+
+  return format;
+}
+
+ + +

See Also

+ +

+ +mps_fmt_create_auto_header, + +mps_fmt_scan_t, + +mps_fmt_skip_t, + +mps_fmt_fwd_t, + +mps_isfwd_t, + +mps_pad_t, + +mps_align_t, + +mps_fmt_A_s

+ + +

Notes

+ +

For technical reasons, client objects must be longer than the header, i.e., objects consisting of only a header are not supported. However, if the header size is larger than or equal to alignment, the pad method must still be able to create padding objects down to alignment size.

+ +

At the moment, this format only works with pool classes AMC and AMCZ.

+ + +.. c:type:: mps_fmt_class_t + + +

Summary

+ +

mps_fmt_class_t is a function pointer type for the class method of a format.

+ + +

Associated Protocols

+ +

Format. Telemetry.

+ + +

Type

+ +

typedef mps_addr_t (*mps_fmt_class_t)(mps_addr_t addr);

+ + +

Arguments

+ +

addr the address of the object whose class is of interest

+ + +

Returned Values

+ +

Returns an address that the client associates with the class or type of the object.

+ + +

Description

+ +

mps_fmt_class_t is t he type of a format's class method. A class method returns an address that is related to the class of the object, for passing on to various support tools (such as graphical browsers).

+ +

A class method is provided by the client as part of a format (see Format Protocol).

+ +

The exact meaning of the return value is up to the client, but it would typically bear some relation to class or type in the client program. The client may have objects that represent classes or types. These may be associated with strings via mps_telemetry_intern and mps_telemetry_label.

+ + +

Example

+ +
+mps_addr_t my_class_method(mps_addr_t object) {
+  my_object_generic_t generic_object = object;
+  return (mps_addr_t)(generic_object.class);
+}
+
+ + +

Error Handling

+ +

A class method is not allowed to fail, but may return NULL.

+ + +

See Also

+ +

+ +mps_fmt_t, + +mps_fmt_create_B

+ + +

Notes

+ +

It is recommended that NULL be returned for padding objects and forwarded objects.

+ + +.. c:type:: mps_fmt_copy_t + + +

Summary

+ +

mps_fmt_copy_t is a function pointer type for the copy method of a format. [Obsolete. RHSK 2006-06-06]

+ + +

Associated Protocols

+ +

Format.

+ + +

Type

+ +

typedef void (*mps_fmt_copy_t)(mps_addr_t old, mps_addr_t new);

+ + +

Arguments

+ +

old -- the address of the object

+ +

new -- the address to which the object should be copied

+ + +

Description

+ +

[Note: mps_fmt_copy_t is obsolete: the MPS does not call this format method. The MPS simply copies all the bytes to the new location (using the length reported by the skip format method). RHSK 2006-06-06]

+ +

mps_fmt_copy_t is a function pointer type for the copy method of a format. A copy method copies an object to a new location. It may be called by the MPS as part of copying garbage collection, for example.

+ +

A copy method is required in some formats (in particular formats A and B (see mps_fmt_A_t and mps_fmt_B_t)). A copy method takes the address of an object and another address, and copies the object to the new address. The new and the old locations are guaranteed not to overlap.

+ + +

Example

+ +
+void my_copy_method(mps_addr_t old, mps_addr_t new)
+{
+  size_t length = (char*)my_skip_method(old) - (char *)old;
+  memcpy(new, old, length);
+}
+
+ + +

Error Handling

+ +

A copy method is not allowed to fail.

+ + +

See Also

+ +

+ +mps_fmt_t, + +mps_fmt_create_A, + +mps_fmt_A_t, + +mps_fmt_B_t, + +mps_fmt_create_B

+ + +

Notes

+ +

Most pools will just ignore Copy methods, and do the copy themselves.

+ + +

function mps_fmt_create_A

+ + +

Summary

+ +

Function for create a format of variety A.

+ + +

Associated Protocols

+ +

Format.

+ +

+ + +

Syntax

+ +

mps_res_t mps_fmt_create_A(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_A_s *fmt_A);

+ + +

Arguments

+ +

+ fmt_o + - the address of a variable to hold the new format +

+ +

+ arena + - the arena in which to create the format +

+ +

+ fmt_A + - format description of variety A +

+ + +

Returned Values

+ +

Result status. If the return value is MPS_RES_OK, the new format is in *fmt_o.

+ + +

Description

+ +

This function creates a format from a user format specification of variety A.

+ + +

Example

+ +
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt_A_s my_format_A = { my_alignment, &my_scan, &my_skip, &my_copy,&my_fwd,
+    &my_isfwd, &my_pad };
+  mps_fmt my_format;
+  mps_res_t res;
+
+  res = mps_fmt_create_A(&my_format, arena, &my_format_A);
+  if(res != MPS_RES_OK) {
+    fprintf(stderr, "Couldn't create format.\n");
+    exit(1);
+  }
+
+  return my_format;
+}
+
+ + +

Error Handling

+ +

The MPS may exhaust some resource in the course of mps_fmt_create_A and will return an appropriate error code in such circumstances.

+ + +

See Also

+ +

+ +mps_fmt_A_s, + +mps_fmt_t, + +mps_fmt_create_B

+ + +

function mps_fmt_create_B

+ + +

Summary

+ +

Function for create a format of variety B.

+ + +

Associated Protocols

+ +

Format.

+ +

+ + +

Syntax

+ +

mps_res_t mps_fmt_create_B(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_B_s *fmt_B);

+ + +

Arguments

+ +

arena - the arena in which to create the format

+ +

fmt_B - format description of variety B

+ + +

Returned Values

+ +

Result status. If the return value is MPS_RES_OK, the new format is in*fmt_o.

+ +

+ + +

Description

+ +

This function creates a format from a user format specification of variety B. It is very similar to mps_fmt_create_A.

+ + +

Example

+ +
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt_B_s my_format_B = { my_alignment, &my_scan, &my_skip, &my_copy,
+                              &my_fwd, &my_isfwd, &my_pad, &my_class };
+  mps_fmt my_format;
+  mps_res_t res;
+
+  res = mps_fmt_create_B(&my_format, arena, &my_format_B);
+  assert(res != MPS_RES_OK);
+
+  return my_format;
+}
+
+ + +

Error Handling

+ +

The MPS may exhaust some resource in the course of mps_fmt_create_B and will return an appropriate error code in such circumstances.

+ + +

See Also

+ +

+ +mps_fmt_B_s, + +mps_fmt_t, + +mps_fmt_create_A

+ + +.. c:function:: mps_res_t mps_fmt_create_auto_header(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_auto_header_s *fmt_st); + + +

Summary

+ +

Function for create a format of variety auto_header.

+ + +

Associated Protocols

+ +

Format.

+ + +

Arguments

+ +

+ fmt_o + - the address of a variable to hold the new format +

+ +

+ arena + - the arena in which to create the format +

+ +

+ fmt_st + - format description of variety auto_header +

+ + +

Returned Values

+ +

Result status. If the return value is MPS_RES_OK, the new format is in *fmt_o.

+ + +

Description

+ +

This function creates a format from a user format specification of variety auto_header.

+ + +

Example

+ +
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt_auto_header_s format_desc = { my_alignment, &my_scan, &my_skip, &my_fwd,
+    &my_isfwd, &my_pad, HEADER_SIZE };
+  mps_fmt format;
+  mps_res_t res;
+
+  res = mps_fmt_create_auto_header(&format, arena, &format_desc);
+  assert(res != MPS_RES_OK);
+
+  return format;
+}
+
+ + +

Error Handling

+ +

The MPS may exhaust some resource in the course of mps_fmt_create_auto_headerand will return an appropriate error code in such circumstances.

+ + +

See Also

+ +

+ +mps_fmt_auto_header_s, + +mps_fmt_t, + +mps_fmt_create_A

+ + +.. c:type:: mps_fmt_fwd_t + + +

Summary

+ +

The type of a format's forward method.

+ + +

Associated Protocols

+ +

Format.

+ + +

Type

+ +

typedef void (*mps_fmt_fwd_t)(mps_addr_t old, mps_addr_t new);

+ + +

Arguments

+ +

old

+ +

the address of an object

+ +

new

+ +

the address where the object has been moved

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

mps_fmt_fwd_t is the type of a format's forward method. A forward method is used to store relocation information in a heap. It may be called by the MPS as part of copying garbage collection.

+ +

A forward method is provided by the client as part of a format (see Format Protocol ). TheMPS calls a forward method when it has relocated an object. The forward method when called must replace the object at 'old' with a forwarding marker that points to the address 'new'. The forwarding marker must meet the following requirements:

+ +
    + +

  • it must be possible for the MPS to call other format methods with the address of a forwarding marker as the argument.

    • + +

  • he forwarding marker must not be bigger than the original object.

    • + +

  • t must be possible to distinguish the forwarding marker from ordinary objects using the isfwd method (see mps_fmt_isfwd_t), and the isfwd method must return the address'new'.

    • + +
+ + +

Example

+ +
+/* define the function */
+
+void example_fwd(mps_addr_t old, mps_addr_t new)
+{
+  /* ... */
+}
+
+/* also define example_scan, example_skip, etc */
+/* store pointer to function in the format variant struct */
+struct mps_fmt_B_s example_fmt_B = {
+  4, /* align */
+  example_scan,
+  example_skip,
+  example_copy,
+  example_fwd,
+  example_isfwd,
+  example_pad,
+  example_class
+};
+
+/* The (address of the) example_fmt_B object can now be passed to */
+/* mps_fmt_create_B to create a format. */
+
+ + +

See Also

+ +

+ +mps_fmt_A_s, + +mps_fmt_B_s, + +mps_fmt_auto_header_s, + +mps_fmt_isfwd_t

+ + +

Notes

+ +

This method is never invoked by the GC on an object in a non-moving pool.

+ + +.. c:type:: mps_fmt_isfwd_t + + +

Summary

+ +

The type of a format's isfwd ("is forwarded") method.

+ + +

Associated Protocols

+ +

Format.

+ + +

Type

+ +

typedef mps_addr_t (*mps_fmt_isfwd_t)(mps_addr_t addr);

+ + +

Arguments

+ +

addr

+ +

the address of a candidate object

+ + +

Returned Values

+ +

+ Either a null pointer to indicate the object at + addr + has not been relocated, orthe new location of the object if there is a forwarding marker at + addr + indicating thatthe object has been relocated. +

+ + +

Description

+ +

The type of a format's isfwd ("is forwarded") method. An isfwd method is used to test whether an object has been relocated using the format's forward method.

+ +

An isfwd method is provided by the client as part of a format (see protocol.mps.format(0) ).The MPS calls the isfwd method to determine whether an object in the heap has been relocated or not.Objects in the heap are relocated using the format's forward method (see mps_fmt_fwd_t). When the isfwd method is called the parameter addr will be the address of either an object or a forwarding marker created with the forward method. If it is an object (so it has not been relocated)the method should return a null pointer; otherwise it is a forward marker indicating the address of the relocated object, the address of the relocated object should be returned (this should be the same as the 'new' parameter that was passed to the forward method that created the forwarding marker).

+ + +

Example

+ +

<example of how to use the symbol>

+ + +

See Also

+ +

+ +mps_fmt_A_s, + +mps_fmt_B_s, + +mps_fmt_auto_header_s, + +mps_fmt_fwd_t

+ + +

Notes

+ +

This method is never invoked by the GC on an object in a non-moving pool.

+ + +.. c:type:: mps_fmt_pad_t + + +

Summary

+ +

The type of a format's pad method.

+ + +

Associated Protocols

+ +

Format.

+ + +

Type

+ +

typedef void (*mps_fmt_pad_t)(mps_addr_t addr, size_t size);

+ + +

Arguments

+ +

addr

+ +

The address at which to create a padding object.

+ +

size

+ +

The size (in bytes) of the padding object to be created.

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

The type of a format's pad method. A pad method is used to create padding objects.

+ +

A pad method is provided by the client as part of a format (see Format Protocol ). The MPS calls a pad method when it wants to create a padding object. Typically the MPS creates padding objects to fill in otherwise unused gaps in memory; they allow the MPS to pack objects in fixed-size units (such as OS pages). The pad method should create a padding object of the specified size at the specified address. The size can be any aligned (to the format alignment) size. A padding object should be acceptable to other methods in the format (scan, skip, isfwd, etc.).

+ + +

Example

+ +

<example of how to use the symbol>

+ + +

See Also

+ +

+ +mps_fmt_A_s, + +mps_fmt_B_s

+ + +.. c:type:: mps_fmt_scan_t + + +

Summary

+ +

Type of the scan method of a format.

+ + +

Associated Protocols

+ +

Format, Scanning.

+ + +

Syntax

+ +

typedef mps_res_t (*mps_fmt_scan_t)(mps_ss_t scan_state, mps_addr_t base, mps_addr_t limit)

+ + +

Arguments

+ +

+ scan_state + a scan state +

+ +

+ base + a client pointer to the first object in the block to be scanned +

+ +

+ limit + a client pointer to the object just beyond the end of the block +

+ + +

Returned Values

+ +

A result code.

+ + +

Description

+ +

This is the type of scanning functions provided by the client in some format variants and mps_root_create_fmt. When the MPS needs to scan objects in an area of memory that this scanning function has been registered for, it will be called with a scan state and the limits of the block of objects to scan. It must then indicate references within the objects by usingmps_fix or one of the alternatives.

+ +

The base and limit arguments are client pointers, as usual. Note that there might not be any object at the location indicated by limit.

+ + +

Example

+ +
+/* Scanner for a simple Scheme-like language with just two interesting types */
+
+mps_res_t scan_objs(mps_ss_t ss, mps_addr_t base, mps_addr_t limit)
+{
+  mps_res_t res;
+  mps_addr_t obj;
+
+  MPS_SCAN_BEGIN(ss)
+  for(obj = base; obj < limit;) { /* obj maps over the objects to scan */
+    switch(((Object*)obj)->type) {
+    case ArrayType:
+      {
+        size_t i;
+        Array *array = (Array *)obj;
+
+        for(i = 0; i < array->length; ++i) { /* fix each element */
+          res = MPS_FIX12(ss, &array->contents[i]);
+          if(res != MPS_RES_OK) return res;
+        }
+
+        obj = AddrAdd(obj, ArraySize(array)); /* move to next object */
+        break;
+      }
+
+    case StackFrameType:
+      {
+        StackFrame *frame = (StackFrame *)obj;
+        for(i = frame->size; i > 0; --i) { /* fix each local var */
+          res = MPS_FIX12(ss, &frame->locals[i]);
+          if(res != MPS_RES_OK) return res;
+        }
+
+        res = MPS_FIX12(ss, &frame->next);
+        if(res != MPS_RES_OK) return res;
+        obj = AddrAdd(obj, StackFrameSize(frame));
+        break;
+      }
+
+    default: /* other types don't contain references */
+      obj = AddrAdd(obj, DefaultSize(obj));
+      break;
+
+    }
+  }
+  MPS_SCAN_END(ss);
+
+  return res;
+}
+
+ + +

Error Handling

+ +

If a fixing operation returns a value other than MPS_RES_OK, the scanning function must return that value, and may return without scanning further references. Generally, itis better if it returns as soon as possible. If the scanning is completed successfully, the function should return MPS_RES_OK.

+ + +

See Also

+ +

+ +mps_fmt_A_s, + +mps_fmt_B_s, + +mps_fmt_auto_header_s, + +mps_root_create_fmt, + +mps_fix, + +MPS_FIX12, + +MPS_FIX1, + +MPS_FIX2, + +MPS_FIX_CALL, + +MPS_SCAN_BEGIN, + +MPS_SCAN_END

+ + +.. c:type:: mps_fmt_skip_t + + +

Summary

+ +

mps_fmt_skip_t is a function pointer type for the skip method of a format.

+ + +

Associated Protocols

+ +

Format.

+ + +

Type

+ +

typedef mps_addr_t (*mps_fmt_skip_t)(mps_addr_t obj);

+ + +

Arguments

+ +

+ obj + the client pointer to the object to be skipped +

+ + +

Returned Values

+ +

The skip method should return the address of the next object.

+ + +

Description

+ +

mps_fmt_skip_t is a function pointer type for the skip method of a format.

+ +

These methods are provided by the client as part of a format and invoked by the MPS (seeFormat Protocol). The skip method takes the client pointer to the object. The method should return the client pointer to the next object, whether there is one or not. With no headers, this is the address just past the end of this object; with headers, it's the address just past where the header of next object would be. It is always the case that the difference between the argument and the return value is the size of the block containing the object.

+ + +

Example

+ +
+mps_addr_t my_skip_method(mps_addr_t object)
+{
+  char *p = (char *)object;
+  my_object_t my_object = (my_object_t)object;
+  return((mps_addr_t)(p + my_object->length));
+}
+
+ + +

Error Handling

+ +

A skip method is not allowed to fail.

+ + +

See Also

+ +

+ +mps_fmt_A_s, + +mps_fmt_B_s, + +mps_fmt_auto_header_s

+ + +.. c:type:: mps_fmt_t + + +

Summary

+ +

mps_fmt_t is the type of object formats.

+ + +

Associated Protocols

+ +

Format.

+ + +

Type

+ +

typedef struct mps_fmt_s *mps_fmt_t;

+ +

mps_fmt_s is an incomplete structure type used only to declare the opaque type mps_fmt_t.

+ + +

Description

+ +

mps_fmt_t is the opaque type of object formats. An object format is a way for the MPS and client programs to communicate regarding the layout of client objects. For more information, seeFormat Protocol.

+ + +

Example

+ +
+#include "mps.h"
+#include "mpscamc.h"
+#include <stdlib.h>
+
+struct mps_fmt_A_s fmt_A_s = {
+  (mps_align_t)4,
+  scan, skip, copy, move, isMoved, pad
+};
+
+void go(mps_space_t space)
+{
+  mps_fmt_t format;
+  mps_res_t res;
+  mps_pool_t pool;
+
+  res = mps_fmt_create_A(&format, space, &mps_fmt_A_s);
+  if(res != MPS_RES_OK)
+    abort();
+
+  res = mps_pool_create(&pool, space, mps_class_amc(), format);
+  if(res != MPS_RES_OK)
+    abort();
+
+  /* do some stuff here */
+
+  mps_pool_destroy(pool);
+  mps_format_destroy(format);
+}
+
+ + +

See Also

+ +

+ +mps_fmt_create_A, + +mps_fmt_create_B, + +mps_fmt_destroy, + +mps_fmt_A_t

+ + +.. c:type:: mps_formatted_objects_stepper_t + + +

Summary

+ +

Type of the client supplied heap walker function.

+ + +

Associated Protocols

+ +

Heap walking.

+ + +

Type

+ +

typedef void (*mps_formatted_objects_stepper_t)(mps_addr_t, mps_fmt_t, mps_pool_t, void *,size_t )

+ + +

Arguments

+ +

mps_formatted_objects_stepper is a type not a function so it doesn't take any arguments; however the function pointed to by an object of this type does. Such functions take the following argument list:

+ +

(mps_addr_t object, mps_fmt_t format, mps_pool_t pool, void *p, size_t s)

+ +

object is a pointer to the (client) object.

+ +

format is the MPS format of the client object.

+ +

pool in the MPS pool in which the client object resides.

+ +

p and s are two closure values which are copies of the corresponding values which the client passed into the heap walking function, mps_arena_formatted_objects_walk.

+ + +

Returned Values

+ +

The function pointed to by an object of type mps_formatted_objects_stepper_t returns no arguments.

+ + +

Description

+ +

This symbol describe the type of pointers passed into the heap walking function mps_arena_formatted_objects_walk. The heap walker arranges to apply this function to all objects on the heap, see mps_arena_formatted_objects_walk for details.

+ + +

Example

+ +

<example of how to use the symbol>

+ + +

Error Handling

+ +

The function pointed to by an object of type mps_formatted_objects_stepper_t have no way to return an error code to the caller.

+ + +

See Also

+ +

+ +mps_arena_formatted_objects_arena_walk

+ + +

Notes

+ + +.. c:function:: void mps_free(mps_pool_t pool, mps_addr_t p, size_t size); + + +

Summary

+ +

Frees a block of memory to a pool.

+ + +

Associated Protocols

+ +

Allocation

+ + +

Arguments

+ +

pool the pool of the object to be freed

+ +

p a pointer to the object to the freed

+ +

size the size of the object to the freed in bytes

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

Frees an object of memory, returning the memory block to the pool it was allocated from.The pool might then decide to make it available to other pools, but the way this happens depends onthe pool class and the current situation.

+ + +

Example

+ + +

See Also

+ +

+ +mps_alloc

+ + +

Notes

+ +

mps_free takes a size argument, because it is most efficient to do so. In practical programs, the type of an object is usually known at the point in the code that calls the deallocation function, and hence the size is trivially available. In such cases. storing the size on the MPS side would cost time and memory, and make it hard to get good virtual memory behaviour (as it is, the deallocation code doesn't have to touch the dead object at all).

+ +

Undoubtedly, one day, we'll get around to writing a pool that stores the size of each object.

+ + +.. c:function:: int mps_lib_memcmp(const void *s1, const void *s2, size_t n); + + +

Summary

+ +

A plinth function similar to C's "memcmp".

+ + +

Associated Protocols

+ +

Plinth

+ + +

Arguments

+ +

s1, s2 pointers to memory blocks to be compared

+ +

n length of the blocks, in bytes

+ + +

Returned Values

+ +

An integer that is greater than, equal to, or less than zero, accordingly as the block pointed to by "s1" is greater than, equal to, or less than the block pointer to by "s2".

+ + +

Resources

+ +

mpslib.h

+ + +

Description

+ +

This function is intended to have the same semantics as the "memcmp" function of the ANSI C standard (section 7.11.4.1).

+ +

Like other plinth features, it is used by the MPS and provided by the client (possibly using the ANSI plinth, mpsliban.c).

+ + +

Example

+ +

None, clients don't use it.

+ + +

Error Handling

+ +

None.

+ + +

See Also

+ +

+ +mps_lib_memset, + +mps_lib_memcpy, +mpsliban.c

+ + +

Notes

+ +

None.

+ + +

function mps_lib_memcpy

+ + +

Summary

+ +

A plinth function similar to C's "memcpy".

+ + +

Associated Protocols

+ +

Plinth

+ + +

Syntax

+ +

void *mps_lib_memcpy(void *dest, const void *source, size_t n);

+ + +

Arguments

+ +

dest destination of copy

+ +

source source of copy

+ +

n length of the blocks, in bytes

+ + +

Returned Values

+ +

Returns the value of the dest argument.

+ + +

Resources

+ +

mpslib.h

+ + +

Description

+ +

This function is intended to have the same semantics as the "memcpy" function of the ANSI C standard (section 7.11.2.1).

+ +

Like other plinth features, it is used by the MPS and provided by the client (possibly using the ANSI plinth, mpsliban.c).

+ + +

Example

+ +

None, clients don't use it.

+ + +

Error Handling

+ +

None.

+ + +

See Also

+ +

+ +mps_lib_memset, + +mps_lib_memcmp, +mpsliban.c

+ + +

Notes

+ +

None.

+ + +

function mps_lib_memset

+ + +

Summary

+ +

A plinth function similar to C's "memset".

+ + +

Associated Protocols

+ +

Plinth

+ + +

Syntax

+ +

void *mps_lib_memset(void *s, int c, size_t n);

+ + +

Arguments

+ +

s destination of copy

+ +

c byte (when converted to an unsigned char) to copy

+ +

n length of the block, in bytes

+ + +

Returned Values

+ +

Returns the value of s.

+ + +

Resources

+ +

mpslib.h

+ + +

Description

+ +

This function is intended to have the same semantics as the "memset" function of the ANSI C standard (section 7.11.6.1).

+ +

Like other plinth features, it is used by the MPS and provided by the client (possibly using the ANSI plinth, mpsliban.c).

+ + +

Example

+ +

None, clients don't use it.

+ + +

Error Handling

+ +

None.

+ + +

See Also

+ +

+ +mps_lib_memcpy, + +mps_lib_memcmp, +mpsliban.c

+ + +

Notes

+ +

None.

+ + +

mps_lib_telemetry_control

+ + +

Summary

+ +

Plinth function to supply a default value for telemetry filters from environment.

+ + +

Associated Protocols

+ +

Telemetry

+ + +

Type

+ +

unsigned long mps_lib_telemetry_control();

+ + +

Arguments

+ +

None.

+ + +

Initial/Default Values

+ +

In the absence of environmental data, a default of zero is recommended.

+ + +

Returned Values

+ +

The default value of the telemetry filter, as derived from the environment. It is recommended that the environment be consulted for a symbol analogous to MPS_TELEMETRY_CONTROL, subject to local restrictions.

+ + +

Resources

+ +

Depends on access to the environment.

+ + +

Description

+ +

See mps_telemetry_control for more information on the significant of the values.

+ +

+ + +

Example

+ +

See the supplied ANSI plinth for an example implementation.

+ + +

See Also

+ +

+ +mps_telemetry_control

+ + +.. c:function:: mps_clock_t mps_message_clock(mps_arena_t arena, mps_message_t message) + + +

Summary

+ +

mps_message_clock returns the time at which the MPS posted the message (only for certain message types).

+ + +

Associated Protocols

+ +

Message.

+ + +

Arguments

+ +

+ arena + -- the arena +

+ +

+ message + -- any message retrieved with mps_message_get and not yet discarded +

+ + +

Returned Values

+ +

For supported message types: the time at which the MPS posted the message. For other message types: zero.

+ + +

Description

+ +

Messages are asynchronous: they are posted by the MPS, wait on a queue, and are later collected by the client. Each message (of supported types) records the time that it was posted, and this is what mps_message_clock returns.

+ +

The time returned is the mps_clock_t value returned by the library function mps_clock at the time the message was posted. You can subtract one clock value from another to get the time interval between the posting of two messages.

+ +

Only the following supported message types record the time of posting:

+ + +

For other message types, the value returned is always zero.

+ + +

Example

+ +
+  mps_message_t message;
+  mps_clock_t posted_at;
+
+  if(mps_message_get(&message, arena, mps_message_type_gc_start())) {
+    posted_at = mps_message_clock(arena, message);
+    printf("Collection started at %ul.\n", (unsigned long)posted_at);
+  }
+
+ + +

Error Handling

+ +

Can't fail.

+ + +

See Also

+ +

+ +mps_message_type

+ + +

Notes

+ +

The example ANSI plinth, mpsliban.c, implements mps_clock by calling ISO C time.h's clock(). The difference between two of these clock values may be converted to seconds by dividing by ISO C time.h's CLOCKS_PER_SEC conversion factor.

+ + +.. c:function:: void mps_message_discard(mps_arena_t arena, mps_message_t message) + + +

Summary

+ +

mps_message_discard is used to indicate that the client is done with the message and the MPS can now reclaim any storage associated with the message.

+ + +

Associated Protocols

+ +

Message.

+ + +

Arguments

+ +

+ arena + -- the arena +

+ +

+ message + -- the message +

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

mps_message_discard is used to indicate that the client has no further use for the specified message in the specified arena. After this call, the message is invalid and should not be passed as argument to any message functions.

+ +

Messages are essentially manually managed. This call allows the MPS to reclaim storage associated with messages. If the client does not discard their messages then the resources used may grow without bound.

+ +

As well as consuming resources, messages may have other visible effects that require them to be tidied by calling this function. In particular finalization messages refer to their finalized object, and will prevent the object from being reclaimed (subject to the usual garbage collection liveness analysis). A finalized object cannot possibly be reclaimed until its corresponding finalization messages have been discarded (all such messages in the case of multiple messages for the same object).

+ + +

Example

+ +

[missing]

+ + +

Error Handling

+ +

Can't fail.

+ + +

See Also

+ +

+ +mps_message_get

+ + +

Notes

+ +

None.

+ + +.. c:function:: void mps_message_finalization_ref(mps_addr_t *object_ref, mps_arena_t arena, mps_message_tmessage) + + +

Summary

+ +

mps_message_finalization_ref returns the "finalization reference" property of the specified message in the specified arena.

+ + +

Associated Protocols

+ +

Message, finalization.

+ + +

Arguments

+ +

object_ref -- a pointer to a reference to the object to which the message pertains

+ +

arena -- the arena that the message is in

+ +

message -- a message of a message type that supports this method

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

This method returns the "finalization reference" property of the specified message in the specified arena. The message must be of a message type that supports this method; currently, the only such type is that of finalization messages, as returned by mps_message_type_finalization.

+ +

The reference returned by this method is a reference to the object that was originally registered for finalization (by a call to mps_finalize).

+ +

Note that the reference returned is subject to the normal constraints, such as might be imposed by a moving collection, if appropriate. For this reason, it is returned indirectly via "object_ref" to enable the client to place it directly into scanned memory, without imposing the restriction that the C stack be a root.

+ +

The message itself is not affected by invoking this method. Until the client calls mps_message_discard to discard the message it will refer to the object and prevent its reclamation.

+ + +

Example

+ + +

Error Handling

+ + +

See Also

+ +

+ +mps_message_*, +mps_message_type_finalization, +mps_finalize

+ + +.. c:function:: size_t mps_message_gc_condemned_size(mps_arena_t arena, mps_message_tmessage) + + +

Summary

+ +

mps_message_gc_condemned_size returns the "condemned size" property of the specified message in the specified arena.

+ + +

Associated Protocols

+ +

Message, GC.

+ + +

Arguments

+ +

arena-- the arena

+ +

+ + message-- a message of a message type that supports this method +

+ + +

Returned Values

+ +

An approximate size for the set of objects condemned in the collection that generated the message.

+ + +

Resources

+ +

+ mps.h +

+ + +

Description

+ +

Currently, the only type of message that supports this property is mps_message_type_gc, such messages are generated whenever a garbage collection completes. This method returns an approximation to the size of the set of objects that were condemned in that collection.

+ + +

Example

+ + +

Error Handling

+ + +

See Also

+ +

+ +mps_message_*

+ + +

function mps_message_gc_live_size

+ + +

Summary

+ +

mps_message_gc_live_size returns the "live size" property of the specified message in the specified arena.

+ + +

Associated Protocols

+ +

Message, GC.

+ + +

Syntax

+ +

size_t mps_message_gc_live_size(mps_arena_t arena, mps_message_t message)

+ + +

Arguments

+ +

arena -- the arena;

+ +

message -- a message of a message type that supports this method.

+ + +

Returned Values

+ +

The total size of the condemned objects that survived the collection that generated the message.

+ + +

Resources

+ +

+ mps.h +

+ + +

Description

+ +

Currently, the only type of message that supports this property is mps_message_type_gc, such messages are generated whenever a garbage collection completes. This method returns the size of the set of objects that were condemned in that collection, but survived.

+ + +

Example

+ + +

Error Handling

+ + +

See Also

+ +

+ +mps_message_*

+ + +

function mps_message_gc_not_condemned_size

+ + +

Summary

+ +

mps_message_gc_not_condemned_size returns the "not condemned size" property of the specified message in the specified arena.

+ + +

Associated Protocols

+ +

Message, GC.

+ + +

Syntax

+ +

size_t mps_message_gc_not_condemned_size(mps_arena_t arena, mps_message_t message)

+ + +

Arguments

+ +

+ arena -- the arena +

+ +

+ message -- a message of a message type that supports this method +

+ + +

Returned Values

+ +

An approximate size for the set of objects that were in collected pools, but were not condemned in the collection that generated the message.

+ + +

Resources

+ +

mps.h

+ + +

Description

+ +

Currently, the only type of message that supports this property is mps_message_type_gc; such messages are generated whenever a garbage collection completes. This method returns an approximation to the size of the set of objects that were in collected pools (so potentially subject to garbage collection), but were not condemned in that collection.

+ + +

Example

+ + +

Error Handling

+ + +

See Also

+ +

+ +mps_message_*

+ + +

function mps_message_gc_start_why

+ + +

Summary

+ +

mps_message_gc_start_why returns the a string that describes why a particular collection started.

+ + +

Associated Protocols

+ +

Message, GC.

+ + +

Syntax

+ +

const char * mps_message_gc_start_why(mps_arena_t arena, mps_message_t message)

+ + +

Arguments

+ +

arena -- the arena

+ +

message -- a message of a message type that supports this method (mps_message_type_gc_start())

+ + +

Returned Values

+ +

A pointer to a string that is a textual explanation of why this collection is starting.

+ + +

Resources

+ +

mps.h

+ + +

Description

+ +

Currently, the only type of message that supports this property is mps_message_type_gc_start; such messages are generated whenever a garbage collection starts. This method returns a string describing why the collection started.

+ +

The contents of the string must not be modified by the client. The string and the pointer are only valid as long as the message has not been discarded (with mps_message_discard).

+ +

Example

+ + +

Error Handling

+ + +

See Also

+ +

+ +mps_message_*

+ + +.. c:function:: mps_bool_t mps_message_get(mps_message_t *message_return, mps_arena_t arena, mps_message_type_tmessage_type) + + +

Summary

+ +

Gets a message of the specified type from a message queue.

+ + +

Associated Protocols

+ +

Message.

+ + +

Arguments

+ +

+ message_return + -- the handle to the message that was removed from the queue +

+ +

+ arena + -- the arena +

+ +

+ message_type + -- the type of message +

+ + +

Returned Values

+ +

Returns true if a message has been removed from the queue, false if not.

+ + +

Description

+ +

+ If there is a message of the specified type on the message queue of the specified arena,then this function removes one such message from the queue, returns a handle to it via themessage_return argument, and returns true. Otherwise it returns false. +

+ + +

Example

+ + +

See Also

+ +

+ +mps_message_*

+ + +

mps_message_poll

+ + +

Summary

+ +

mps_message_poll determines whether there are currently any messages on a message queue.

+ + +

Associated Protocols

+ +

Message.

+ + +

Syntax

+ +

mps_bool_t mps_message_poll(mps_arena_t arena)

+ + +

Arguments

+ +

+ arena + -- the arena whose message queue you are interested in +

+ + +

Returned Values

+ +

A flag to indicate whether there are any messages on the queue.

+ + +

Description

+ +

mps_message_poll is used to determine whether there are currently any messages on the message queue of the specified arena.

+ + +

Example

+ +

[missing]

+ + +

Error Handling

+ +

Can't fail.

+ + +

See Also

+ +

+ +mps_message_get

+ + +

Notes

+ +

If you expect a particular type of message, it is usually more practical to just call mps_message_get.

+ + +.. c:function:: mps_bool_t mps_message_queue_type(mps_message_type_t *message_type_return, mps_arena_t arena) + + +

Summary

+ +

mps_message_queue_type returns the type of the first message on a message queue.

+ + +

Associated Protocols

+ +

Message.

+ + +

Arguments

+ +

message_type_return -- the type of the first message on the queue of the specified arena

+ +

arena -- the arena

+ + +

Returned Values

+ +

"True" if there are any messages on the queue of the specified arena, "false" if not.

+ + +

Description

+ +

If there are any messages on the queue of the specified arena, then this function returns"true", and also returns the type of the first message via "message_type_return". Otherwise it returns "false".

+ + +

Example

+ + +

See Also

+ +

+ +mps_message_*

+ + +.. c:type:: mps_message_t + + +

Summary

+ +

mps_message_t is used as a handle on an individual message.

+ + +

Associated Protocols

+ +

Message.

+ + +

Type

+ +

typedef struct mps_message_s *mps_message_t

+ +

mps_message_s is an incomplete structure type used only to declare the opaque type mps_message_t.

+ + +

Description

+ +

The opaque type mps_message_t is used as a handle on an individual message. Messages are manually managed. They are created at the instigation of the MPS (but see mps_message_type_enable), and are deleted by the client.

+ +

An mps_message_t is a reference into MPS managed memory, and can safely be stored as such in scannable memory.

+ + +

Example

+ + +

Error Handling

+ +

Not applicable.

+ + +

See Also

+ +

+ +mps_message_*

+ + +.. c:function:: mps_message_type_t mps_message_type(mps_arena_t arena, mps_message_t message) + + +

Summary

+ +

mps_message_type returns the type of a message.

+ + +

Associated Protocols

+ +

Message.

+ + +

Arguments

+ +

arena -- the arena containing the message

+ +

message -- a valid message; that is, one previously returned by mps_message_get, and notdiscarded via mps_message_discard

+ + +

Returned Values

+ +

The type of the specified message.

+ + +

Description

+ +

mps_message_type returns the type of a message.

+ + +

Example

+ + +

Error Handling

+ + +

See Also

+ +

+ +mps_message_clock

+ + +

function mps_message_type_disable

+ + +

Summary

+ +

mps_message_type_disable restores the arena to the default state whereby messages of thespecified type are not generated.

+ +

This reverses the effect of an earlier call to "m ps_message_type_enable".

+ + +

Associated Protocols

+ +

Message.

+ + +

Syntax

+ +

void mps_message_type_disable(mps_arena_t arena, mps_message_type_t message_type)

+ + +

Arguments

+ +

arena -- the arena

+ +

message_type -- the message type to be disabled

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

This procedure may be used by the client to specify that messages of the specified type should not created for the specified arena.

+ +

Messages are not generated by default, but the client may enable the generation of messages with mps_message_type_enable.

+ +

Any existing messages of the specified type are flushed from the message queue.

+ + +

Example

+ +

[none]

+ + +

Error Handling

+ +

Never fails.

+ + +

See Also

+ +

+ +mps_message_*

+ + +

Notes

+ +

It is permitted to call this function when the message type is already disabled. Such a call will have no effect.

+ + +.. c:function:: void mps_message_type_enable(mps_arena_t arena, mps_message_type_t message_type) + + +

Summary

+ +

mps_message_type_enable allows messages of the specified type to be created for thespecified arena. Without such enabling, the MPS will, by default, not generate any messages of thattype.

+ + +

Associated Protocols

+ +

Message.

+ + +

Arguments

+ +

arena -- the arena

+ +

message_type -- the message type to be enabled

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

This procedure may be used by the client to specify that messages of the specified type maybe created for the specified arena. Without such enabling, the MPS will by default not generate any messages of that type.

+ +

Note that the enabling of messages of a particular type implies that the client application will handle and discard message of that type, or the message queue may consume unbounded resources.

+ +

The client may disable message generation again by means of an equivalent call to mps_message_type_disable.

+ + +

Example

+ +

[none]

+ + +

Error Handling

+ +

Never fails.

+ + +

See Also

+ +

+ +mps_message_*

+ +

"Message Protocol"

+ + +

Notes

+ +

It is permitted to call this function when the message type is already enabled. Such a call will have no effect.

+ +

+ + +.. c:function:: mps_message_type_t mps_message_type_finalization(void) + + +

Summary

+ +

mps_message_type_finalization returns the type of finalization messages.

+ + +

Associated Protocols

+ +

Message, Finalization.

+ + +

Arguments

+ +

None.

+ + +

Returned Values

+ +

The type of finalization messages.

+ + +

Resources

+ +

Not applicable.

+ + +

Description

+ +

mps_message_type_finalization returns the type of finalization messages. Finalization messages are used by the MPS to implement finalization (see mps_finalize). When the MPS detects that an object is finalizable, it finalizes the object by posting a message of this type (note that there might be delays between the object becoming finalizable, the MPS detecting that, and the message being posted).

+ +

+In addition to the usual methods applicable to messages, finalization +messages support the mps_message_finalization_ref +method which returns a reference to the object that was registered for +finalization.

+ + +

Example

+ +
+{
+  mps_message_type_t type;
+
+  if(mps_message_queue_type(&type, arena)) {
+    if(type == mps_message_type_finalization()) {
+      process_finalization_message_from_queue();
+    } else {
+      unknown_message_type();
+    }
+  }
+}
+
+ +

See Also

+ +

+ +mps_message_*, + +mps_finalize

+ + +

function mps_message_type_gc

+ + +

Summary

+ +

mps_message_type_gc returns the type of garbage collection statistic messages.

+ + +

Associated Protocols

+ +

Message.

+ + +

Syntax

+ +

mps_message_type_t mps_message_type_gc(void)

+ + +

Arguments

+ +

None.

+ + +

Returned Values

+ +

The type of garbage collection statistic messages.

+ + +

Resources

+ +

+ mps.h +

+ + +

Description

+ +

mps_message_type_gc returns the type of garbage collection statistic messages. Garbage collection statistic messages are used by the MPS to give the client information about garbage collections that have occurred. Such information may be useful in analysing the client's memory usage over time.

+ +

The access methods specific to a message of this type are:

+ +
    + +

  • mps_message_gc_live_size -- gives the total size of the condemned objects that survived the collection that generated the message

    • + +

  • mps_message_gc_condemned_size + -- gives an approximate size for the set of objects condemned in the collection that generated the message.

    • + +

  • mps_message_gc_not_condemned_size -- gives an approximate size for the set of objects that were in collected pools, but were not condemned in the collection that generated the message.

    • + +
+ + +

Example

+ +
+{
+  mps_message_t message;
+  if(mps_message_get(&message, arena, mps_message_type_gc())) {
+    size_t live, condemned, not_condemned;
+    live = mps_message_gc_live_size(arena, message);
+    condemned = mps_message_gc_condemned_size(arena, message);
+    not_condemned = mps_message_gc_not_condemned_size(arena,message);
+    mps_message_discard(arena, message);
+    process_collection_stats(live, condemned, not_condemned);
+  }
+}
+
+ + +

Error Handling

+ +

Cannot fail.

+ + +

See Also

+ +

+ +mps_message_*.

+ + +

function mps_message_type_gc_start

+ + +

Summary

+ +

+mps_message_type_gc_start +returns the type of garbage collection start messages.

+ + +

Associated Protocols

+ +

Message.

+ + +

Syntax

+ +

mps_message_type_t mps_message_type_gc_start(void)

+ + +

Arguments

+ +

None.

+ + +

Returned Values

+ +

The type of garbage collection start messages.

+ + +

Resources

+ +

+ mps.h +

+ + +

Description

+ +

+mps_message_type_gc_start +returns the type of garbage collection start messages. +The messages contain information about why the collection started. See +mps_message_gc_start_why. +

+ +

The access methods specific to a message of this type are:

+ +
    + +

  • mps_message_gc_start_why -- + Returns a string that is a description of why the collection started. +

    • + +
+ + +

Example

+ +
+{
+  mps_message_t message;
+  if(mps_message_get(&message, arena, mps_message_type_gc_start())) {
+    printf("Collection started; reason: %s\n",
+      mps_message_gc_start_why(arena, message));
+  }
+}
+
+ + +

Error Handling

+ +

Cannot fail.

+ + +

See Also

+ +

+ +mps_message_*.

+ + +.. c:type:: mps_message_type_t + + +

Summary

+ +

mps_message_type_t is the type of message types.

+ + +

Associated Protocols

+ +

Message.

+ + +

Description

+ +

mps_message_type_t is the type whose values are the various message types. It is opaque.

+ + +

Example

+ + +

See Also

+ +

+ +mps_message_*

+ + +.. c:function:: void mps_pool_check_fenceposts(mps_pool_t pool) + + +

Summary

+ +

Check all the fenceposts in the pool.

+ + +

Associated Protocols

+ +

Debug

+ + +

Arguments

+ +

pool the pool whose fenceposts are to be checked

+ + +

Description

+ +

This function is a debugging feature to check all the fenceposts in the pool. If a corrupted fencepost is found, an assert will fire. It is only useful to call this on a debug pool that had fenceposting turned, it does nothing on other pools.

+ + +

Example

+ +

mps_pool_check_fenceposts(gene_pool);

+ + +

Error Handling

+ +

If a corrupted fencepost is found, an assert will fire. You will probably want to look at the problem with a debugger.

+ + +

See Also

+ +

+ +mps_class_*_debug

+ + +

structure mps_pool_debug_option_s

+ + +

Summary

+ +

This structure is used to pass debug options to mps_pool_create for debug classes.

+ + +

Associated Protocols

+ +

Debug.

+ + +

Type

+ +
+typedef struct mps_pool_debug_option_s {
+  void *fence_template;
+  size_t fence_size;
+} mps_pool_debug_option_s;
+
+ + +

Members

+ +

+ fence_template + the template for fencepost contents +

+ +

+ fence_size + the size of the template in bytes +

+ + +

Description

+ +

Structures of this type are used to pass debug options to mps_pool_create when creating instances of debug classes.

+ +

Fenceposting is enabled by specifying a non-zero fence_size; the size must be a multiple of the [pool/format] alignment. The content of fenceposts is given as a template that is simply copied onto each fencepost (although sometimes the MPS will create fenceposts smaller than the given size, for example, to pad out some bit that was left unused because of alignmentrequirements).

+ + +

Example

+ +
+static mps_pool_debug_option_s debugOptions = { (void *)"postpost", 8 };
+if(mps_pool_create(&pool, arena, mps_class_ams_debug(),
+                   &debugOptions, 8192, 135, 8)
+   != MPS_RES_OK) {
+  printf("Error creating pool!"); exit(2);
+}
+
+ + +

See Also

+ +

+ +mps_pool_check_fenceposts

+ + +

Notes

+ +

Fencepost templates allow the client to specify complicated patterns that mimic illegal datavalues, that would cause an assert to fire if read by mistake, and that would never be written by any operation that writes at the wrong address by mistake.

+ +

Another trick is to make the pattern contain an instruction sequence that would cause theprogram to error or stop if executed by mistake.

+ + +

function mps_rank_ambig

+ + +

Summary

+ +

Function returning the value representing "rank ambig".

+ + +

Associated Protocols

+ +

Allocation, Root, Scanning.

+ + +

Syntax

+ +

mps_rank_ambig()

+ + +

Type

+ +

mps_rank_t mps_rank_ambig(void)

+ + +

Arguments

+ +

None.

+ + +

Returned Values

+ +

Returns a value of type mps_rank_t representing "rank ambig".

+ + +

Description

+ +

Used to get a value for "rank ambig", which is used to denote that certain references (in a root, for example) are ambiguous references.

+ + +

Example

+ + +

See Also

+ +

+ +mps_rank_t, + +mps_rank_exact

+ + +.. c:function:: mps_rank_t mps_rank_exact(void); + + +

Summary

+ +

Used to declare references which the client wishes to be exact references.

+ + +

Associated Protocols

+ +

Allocation, Root, Scanning.

+ + +

Arguments

+ +

No arguments.

+ + +

Returned Values

+ +

Returns a rank (see mps_rank_t) which can be used to declare references to be exact references.

+ + +

Description

+ +

Used to declare references which the client wishes to be exact, non-weak references.

+ + +

Example

+ +

[missing]

+ + +

See Also

+ +

+ +mps_rank_t, + +mps_rank_ambig, + +mps_rank_weak

+ + +.. c:type:: mps_rank_t + + +

Summary

+ +

A type whose values are "reference ranks".

+ + +

Associated Protocols

+ +

Allocation, Root.

+ + +

Type

+ +

typedef unsigned int mps_rank_t;

+ + +

Description

+ +

mps_rank_t is a concrete type. It is an alias (via the C typedef mechanism) for "unsigned int" provided for convenience and clarity. An object of type mps_rank_t can store a value representing one reference rank. Reference ranks are used to conveniently express specific semantics of particular references. See "MPS Scanning Protocol" for descriptions of these semantics, and mps_rank_* for the actual ranks used to declare these semantics.

+ + +

Example

+ +

(Probably won't be used explicitly, most likely to be seen in the prototype declaration for other MPS functions. For example, mps_root_create.)

+ + +

See Also

+ +

+ +mps_rank_*

+ + +.. c:function:: extern mps_rank_t mps_rank_weak(void); + + +

Summary

+ +

Function to return a value used to represent "rank weak".

+ + +

Associated Protocols

+ +

Allocation, Scanning.

+ + +

Arguments

+ +

None.

+ + +

Returned Values

+ +

Returns a value of type mps_rank_t that represent "rank weak".

+ + +

Description

+ +

mps_rank_weak returns a value used to represent "rank weak".

+ +

"Rank weak" is often used to denote that certain references (in a root or in objects allocated in a pool) are weak references.

+ + +

Example

+ +

<example of how to use the symbol>

+ + +

See Also

+ +

+ +mps_rank_t, + +mps_rank_exact

+ + +.. c:type:: mps_reg_scan_t + + +

Summary

+ +

Type of root scanning functions for mps_root_create_reg.

+ + +

Associated Protocols

+ +

Root.

+ + +

Syntax

+ +

typedef mps_res_t (*mps_reg_scan_t)( mps_ss_t scan_state, mps_thr_t thread, void *p, size_t s)

+ + +

Arguments

+ +

scan_state a scan state

+ +

thread the thread

+ +

p a value passed through from root registration

+ +

s a value passed through from root registration

+ + +

Returned Values

+ +

A result code.

+ + +

Description

+ +

This is the type of root scanning functions the client provides to mps_root_create_reg.These functions will be called, whenever the root needs to be scanned, and passed the "p" and "s"values specified in the call to mps_root_create_reg.

+ + +

See Also

+ +

+ +mps_root_create_reg, + +mps_stack_scan_ambig

+ + +

Notes

+ +

Users are not expected to write any scanning functions of this type. The one function supplied with the MPS, mps_stack_scan_ambig, should be enough for most purposes.

+ + +.. c:type:: mps_res_t + + +

Summary

+ +

mps_res_t is the type of result codes returned by operations that may fail.

+ + +

Type

+ +

typedef int mps_res_t;

+ + +

Description

+ +

A result code indicates the success or failure of an operation, along with the reason for failure. Like UNIX error codes, the meaning of the code depends on the call that returned it. Refer to the documentation of the function for the exact meaning. This documentation describes the broad categories with mnemonic names for various sorts of problems.

+ +

MPS_RES_OK: The operation succeeded. Out and in/out parameters will only be updated if OK is returned, otherwise they will be left untouched. MPS_RES_OK is zero.

+ +

MPS_RES_FAIL: Something went wrong that does not fall into any of the other categories. The exact meaning depends on the call. See the documentation of the function.

+ +

MPS_RES_RESOURCE: A needed resource could not be obtained. Which resource, depends on the call. Compare with MPS_RES_MEMORY, which is a special case of this.

+ +

MPS_RES_MEMORY: Needed memory (committed memory, not address space) could not be obtained. (A more detailed explanation).

+ +

MPS_RES_LIMIT: An internal limitation was reached. For example, the maximum number of something was reached. (A more detailed explanation).

+ +

MPS_RES_UNIMPL: The operation, or some vital part of it, is unimplemented. This might be returned by functions that are no longer supported, or by operations that are included for future expansion, but not yet supported.

+ +

MPS_RES_IO: An I/O error occurred. Exactly what depends on the function.

+ +

MPS_RES_COMMIT_LIMIT: The arena's commit limit would have been exceeded as a result of (explicit or implicit) allocation. See protocol.arena.commit.

+ +

MPS_RES_PARAM: A parameter of the operation was invalid. (A more detailed explanation).

+ + +

Any function that might fail will return a result code. Any other results of the function are passed back in "return" parameters. See MPS Interface Conventions for more information.

+ + +

Example

+ +
+mps_addr_t p;
+mps_res_t res;
+
+res = mps_alloc(&p, pool, sizeof(struct spong));
+if(res != MPS_RES_OK) {
+  handle_memory_error(res);
+  abort();
+}
+
+ +

For more examples, s ee doc.mps.ref-man.if-conv.

+ + +

See Also

+ +

+ +MPS_RES_*

+ + +.. c:function:: mps_res_t mps_root_create(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_trm, mps_root_scan_t scan, void *p, size_t s) + + +

Summary

+ +

The function mps_root_create declares a root that consists of all the references indicated by a scanning function.

+ + +

Associated Protocols

+ +

Root.

+ + +

Arguments

+ +

root_o a pointer to a variable to store the new root structure

+ +

arena the arena

+ +

rank the rank of references in the root

+ +

rm the root mode

+ +

scan the scanning function

+ +

p a value to be passed to the scanning function

+ +

s a value to be passed to the scanning function

+ + +

Returned Values

+ +

If the return value is MPS_RES_OK, a new root structure in "*root_o".

+ + +

Description

+ +

The client provides a scanning function, that will be called with a scan state and "p" and"s", whenever the root needs to be scanned. See mps_root_scan_t for details.

+ +

If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be valid whenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're using asynchronous GC, this could be right after the root is registered, so the root has to be valid when it is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

+ + +

Example

+ +
+static mps_root_t mmRoot;
+
+int main(void)
+{
+  mps_res_t res;
+
+  /* ... */
+
+  res = mps_root_create(&mmRoot, arena, MPS_RANK_EXACT, (mps_rm_t)0,
+                        &rootScanner, NULL, 0);
+  /* see doc of mps_root_scan_t for definition of rootScanner */
+  if(res != MPS_RES_OK)
+    exit(1);
+
+  /* ... */
+}
+
+ + +

Error Handling

+ +

mps_root_create returns MPS_RES_MEMORY when it fails to allocate memory for the internal root structure; you need to deallocate or reclaim something to make enough space, or expand the arena.

+ + +

See Also

+ +

+ +mps_root_scan_t, + +mps_rm_t, + +mps_rank_t, + +mps_root_t, + +mps_root_create_fmt, + +mps_root_create_table, + +MPS_RM_CONST

+ + +

Notes

+ +

"p" and "s" are just arbitrary data that scanning function can use. This is needed because Clacks local functions.

+ + +.. c:function:: mps_res_t mps_root_create_fmt(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_fmt_scan_t scan, mps_addr_t base, mps_addr_t limit) + + +

Summary

+ +

The function mps_root_create_fmt declares a root that consists of a block of objects, and provides a scanning function for them.

+ + +

Associated Protocols

+ +

Root.

+ + +

Arguments

+ +

root_o a pointer to a variable to store the new root structure

+ +

arena the arena

+ +

rank the rank of references in the root

+ +

rm the root mode

+ +

scan the scanning function

+ +

base the address of the start of the root

+ +

limit the address just beyond the end of the root

+ + +

Returned Values

+ +

If the return value is MPS_RES_OK, the new root in "*root_o".

+ + +

Description

+ +

The client provides a scanning function, that will be called with a scan state and an area of memory, whenever the root needs to be scanned. See mps_fmt_scan_t for details.

+ +

If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be valid whenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're using asynchronous GC, this could be right after the root is registered, so the root has to be valid when it is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

+ + +

Example

+ +
+static mps_root_t mmRoot;
+SegmentDescriptor DataSegment;
+
+int main(void)
+{
+  mps_res_t res;
+
+  /* ... */
+
+  res = mps_root_create_fmt(&mmRoot, arena, MPS_RANK_EXACT, (mps_rm_t)0,
+    &scan_objs,
+    (mps_addr_t)DataSegment.base,
+    (mps_addr_t) (DataSegment.base + SegmentLength) );
+
+  /* see doc of mps_fmt_scan_t for definition of scan_objs */
+
+  if(res != MPS_RES_OK)
+    exit( EXIT_FAILURE );
+
+  /* ... */
+}
+
+ + +

Error Handling

+ +

mps_root_create_fmt returns MPS_RES_MEMORY when it fails to allocate memory for the internal root structure; you need to deallocate or reclaim something to make enough space, or expand the arena.

+ + +

See Also

+ +

+ +mps_fmt_scan_t, + +mps_rm_t, + +mps_rank_t, + +mps_root_t, + +mps_root_create, + +mps_root_create_table, + +MPS_RM_PROT, + +MPS_RM_CONST

+ + +

Notes

+ +

This is like mps_root_create_table, except you get to supply your own scanning function.This is like mps_root_create, except the scanning function has a slightly different argument list(and the MPS knows where the root is).

+ + +.. c:function:: mps_res_t mps_root_create_reg(mps_root_t * root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_thr_t thread, mps_reg_scan_t scan, void *p, size_t s) + + +

Summary

+ +

mps_root_create_reg registers a thread as a root.

+ + +

Associated Protocols

+ +

Root.

+ + +

Arguments

+ +

root_o a pointer to a variable to store the new root structure

+ +

arena the arena

+ +

rank the rank of references in the root

+ +

rm the root mode

+ +

thread the thread to the registered as a root

+ +

scan the scanning function

+ +

p a value to be passed to the scanning function

+ +

s a value to be passed to the scanning function

+ + +

Returned Values

+ +

If the return value is MPS_RES_OK, a new root structure in "*root_o".

+ + +

Description

+ +

mps_root_create_reg declares the state of a thread as a root. The client provides a scanning function that will be called and passed "p" and "s", whenever the root needs to be scanned. See mps_reg_scan_t for details.

+ +

If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be valid whenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're using asynchronous GC, this could be right after the root is registered, so the root has to be valid when it is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

+ + +

Example

+ +
+typedef struct {
+  mps_root_t mmRoot;
+  mps_thr_t thread;
+  /* ...  */
+} ThreadLocals;
+
+void InitThread(ThreadLocals *thr)
+{
+  /* This is a hack to find the bottom of the stack. */
+  void *stackBottom=&stackBottom;
+
+  mps_thread_reg(&thr->thread, arena);
+  mps_root_create_reg(&thr->mmRoot, arena, MPS_RANK_AMBIG, (mps_rm_t) 0,
+    thr->thread, mps_stack_scan_ambig, stackBottom, 0);
+
+  /* ...  */
+
+}
+
+ + +

Error Handling

+ +

mps_root_create_reg returns MPS_RES_MEMORY when it fails to allocate memory for the internal root structure; you need to deallocate or reclaim something to make enough space, or expand the arena.

+ + +

See Also

+ +

+ +mps_stack_scan_ambig, + +mps_reg_scan_t

+ + +

Notes

+ +

Only one suitable scanning function is supplied with the MPS, namely mps_stack_scan_ambig.

+ + +.. c:function:: mps_res_t mps_root_create_table(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t size) + + +

Summary

+ +

mps_root_create_table create s a root that is a vector of references.

+ + +

Associated Protocols

+ +

Root.

+ + +

Arguments

+ +

root_o a pointer to a variable for storing the new root structure in

+ +

arena the arena

+ +

rank the rank of the references in this root

+ +

rm the root mode

+ +

base a pointer to the vector of references that is being registered

+ +

size the number of references in the vector being registered

+ + +

Returned Values

+ +

If the return value is MPS_RES_OK, the new root in "*root_o".

+ + +

Description

+ +

This function declares a root that is a vector of references.

+ +

If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be valid whenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're using asynchronous GC, this could be right after the root is registered, so the root has to be valid when it is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

+ + +

Example

+ +
+static mps_root_t mmRoot;
+Object *Objects[rootCOUNT];
+
+int main(void)
+{
+  mps_res_t res;
+
+  /* ... */
+
+  res = mps_root_create_table(&mmRoot, arena, MPS_RANK_EXACT, (mps_rm_t)0,
+                              (mps_addr_t) &Objects, rootCOUNT );
+
+  if(res != MPS_RES_OK)
+    exit(1);
+
+  /* ... */
+}
+
+ + +

Error Handling

+ +

mps_root_create_table returns MPS_RES_MEMORY when it fails to allocate memory for the internal root structure; you need to deallocate or reclaim something to make enough space, or expand the arena.

+ + +

See Also

+ +

+ +mps_root_create_table_masked, + +MPS_RM_PROT, + +MPS_RM_CONST

+ + +.. c:function:: mps_res_t mps_root_create_table_masked(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t size, mps_word_t mask); + + +

Summary

+ +

mps_root_create_table_masked creates a root that is a vector of tagged values.

+ + +

Associated Protocols

+ +

Root.

+ + +

Arguments

+ +

root_o a pointer to a variable for storing the new root structure in

+ +

arena the arena

+ +

rank the rank of the references in this root

+ +

rm the root mode

+ +

base a pointer to the vector of references that is being registered

+ +

+ size the number of references in the vector being registered +
+ mask any element that has any of the bits in mask set is ignored +

+ + +

Returned Values

+ +

If the return value is MPS_RES_OK, the new root in "*root_o".

+ + +

Description

+ +

mps_root_create_table_masked creates a root that is a table of tagged values. The mask parameter indicates which bits of a pointer are tag bits. References are assumed to have a tag of zero, values with other tags are ignored.

+ +

If the rank of the root is not MPS_RANK_AMBIG, the contents of the root have to be valid whenever a GC happens, i.e., they have to be references to actual objects or "NULL". If you're using asynchronous GC, this could be right after the root is registered, so the root has to be valid when it is registered. It's OK for a root to have entries which point to memory not managed by the MPS --they will simply be ignored.

+ + +

Example

+ +
+#define tagMASK 0x0003
+
+static mps_root_t mmRoot;
+Object *Objects[rootCOUNT];
+
+int main(void)
+{
+  mps_res_t res;
+
+  /* ... */
+
+  res = mps_root_create_table_masked(&mmRoot, arena, MPS_RANK_EXACT, (mps_rm_t)0,
+                                     (mps_addr_t)&Objects, rootCOUNT,
+                                     (mps_word_t)tagMASK);
+  if(res != MPS_RES_OK)
+    exit(1);
+
+  /* ... */
+}
+
+ + +

Error Handling

+ +

mps_root_create_table_masked returns MPS_RES_MEMORY when it fails to allocate memory for the internal root structure; you need to deallocate or reclaim something to make enough space,or expand the arena.

+ + +

See Also

+ +

+ +mps_root_create_table, + +MPS_RM_PROT, + +MPS_RM_CONST

+ + +.. c:type:: mps_root_scan_t + + +

Summary

+ +

Type of root scanning functions for mps_root_create.

+ + +

Associated Protocols

+ +

Root.

+ + +

Syntax

+ +

typedef mps_res_t (*mps_root_scan_t)(mps_ss_t scan_state, void * p, size_t s)

+ + +

Arguments

+ +

scan_state a scan state

+ +

p an argument passed through from mps_root_create

+ +

s an argument passed through from mps_root_create

+ + +

Returned Values

+ +

A result code.

+ + +

Description

+ +

This is the type of root scanning functions the client provides tomps_root_create. The MPS will call these functions whenever the root needs to be scanned, with a scan state (of type mps_ss_t ), and the p ands values specified in the call to mps_root_create. Apart from the argument list, the scanning function works like the format scan methods: it needs to indicate all references using mps_fix or MPS_FIX*.

+ + +

Example

+ +
+static StackFrame *stackBottom;
+
+/* root scanner for an imaginary interpreter for a stack-oriented language */
+static mps_res_t rootScanner(mps_ss_t ss, void * p, size_t s)
+{
+  StackFrame *frame;
+  size_t i;
+  mps_res_t res;
+
+  UNUSED(p);
+  UNUSED(s);
+
+  for(frame = stackBottom; frame != NULL; frame = frame->next)
+    for(i = frame->size; i > 0; --i) {
+      res = mps_fix(ss, &frame->locals[i]);
+      if(res != MPS_RES_OK) return res;
+    }
+
+  return res;
+}
+
+ + +

Error Handling

+ +

If a fixing operation returns a value other than MPS_RES_OK, the scanning function must return that value, and may return without scanning further references. Generally, it is better if it returns as soon as possible. If the scanning is completed successfully, the function should return MPS_RES_OK.

+ + +

See Also

+ +

+ +mps_root_create, + +mps_ss_t, + +mps_fix, + +MPS_SCAN_BEGIN, + +MPS_SCAN_END, + +MPS_FIX12, + +MPS_FIX1, + +MPS_FIX2, + +MPS_FIX_CALL, + +mps_fmt_scan_t

+ + +.. c:type:: mps_roots_stepper_t + + +

Summary

+ +

Type of the client-supplied root walker component.

+ + +

Associated Protocols

+ +

None.

+ + +

Type

+ +

+ typedef void (*mps_roots_stepper_t)( mps_addr_t *, mps_root_t, void *, size_t ) +

+ + +

Arguments

+ +

The function pointed to by an object of type mps_roots_stepper_t takes the followingargument list:

+ +

(mps_addr_t *ref, mps_root_t root, void *p, size_t s)

+ +

ref is the address of a root which references an object in the arena. It's a pointer to a root which points to "something" in the client heap. That "something" will be an object if the root is an exact root. But it might be an interior pointer to an object if the root is an ambiguous root.

+ +

root is the MPS root object which contains ref.

+ +

p and s are two closure values which are copies of the corresponding values which the client passed into mps_arena_roots_walk.

+ + +

Returned Values

+ +

he function pointed to by an object of type mps_roots_stepper_t returns no values.

+ + +

Description

+ +

A pointer to a function is passed into the function mps_arena_roots_walk; the pointer has this type. The root walker arranges to apply this function to all objects which are directly referenced from the roots.

+ + +

Example

+ +

<example of how to use the symbol>

+ + +

Error Handling

+ + +

T

+ +

he function pointed to by an object of type mps_roots_stepper_t has no way of signalling an error to the caller.

+ + +

See Also

+ +

+ +mps_arena_roots_arena_walk

+ + +

Notes

+ + +.. c:type:: mps_sac_class_s + + +

Summary

+ +

A structure describing a size class to be passed as an argument to mps_sac_create.

+ + +

Associated Protocols

+ +

Allocation cache

+ + +

Type

+ +
+typedef struct mps_sac_class_s {
+  size_t mps_block_size;
+  size_t mps_cached_count;
+  unsigned mps_frequency;
+} mps_sac_class_s;
+
+ + +

Description

+ +

mps_sac_class_s is the element type of the array passed tomps_sac_create to describe the size classes. Each element of this array describes one class by specifying block_size, the maximum size (in bytes) in this class; cached_count, the number of objects of this class to cache; and frequency, a number that describes the frequency of requests (allocation and deallocation combined ) in this class relative to all the other classes. The classes should be given in the order of ascending size.

+ +

block_size s have to be aligned to the pool alignment. All sizes must be different, and the smallest size must be large enough to hold a void *.

+ +

+ cached_count + is advice to the MPS on how many blocks to cache, not an absolute limit. The cache policy tries to accommodate fluctuations in the population and minimize the cost of responding to client requests; the purpose of this parameter is to limit how much memory the client is willing to set aside for this purpose. However, a + cached_count + of zero prevents any caching of blocks falling into that class. +

+ +

The MPS automatically provides an "overlarge" class for arbitrarily large objects above the largest class described. Allocations falling into the overlarge class are not cached.

+ + +

Example

+ +
+  mps_sac_t sac;
+  mps_sac_class_s classes[3] = { {8, 38, 1}, {136, 19, 3}, {512, 4, 1} };
+
+  res = mps_sac_create(&sac, pool, 3, classes);
+  if (res != MPS_RES_OK) {
+    printf("Failed to create the allocation cache!");
+    exit(1);
+  }
+
+ + +

See Also

+ +

+ +mps_sac_create

+ + +

Notes

+ +

Any blocks whose size falls between two classes are allocated from the larger class.

+ + +.. c:function:: mps_res_t mps_sac_create(mps_sac_t *sac_o, mps_pool_t pool, size_t classes_count, mps_sac_class_s *classes); + + +

Summary

+ +

This function creates a segregated allocation cache.

+ + +

Associated Protocols

+ +

Allocation cache

+ + +

Arguments

+ +

sac_o a pointer to a variable to hold the cache created

+ +

pool the pool the cache is attached to

+ +

classes_count the number of the size classes

+ +

classes pointer to the first element of an array describing the size classes

+ + +

Returned Values

+ +

If the return value is MPS_RES_OK, a new cache in *sac_o.

+ + +

Description

+ +

This function creates an allocation cache whose free-list is segregated into the given size classes. The cache can get more memory from the given pool, or return memory to it.

+ +

Segregated allocation caches can be associated with any pool that supports mps_alloc and mps_free.

+ +

The size classes are described by an array of element type mps_sac_class_s (q.v.). This array is used to initialize the cache, and is not needed aftermps_sac_create returns. There might be a limit on how many classes can be described,but it will be no less than MPS_SAC_CLASS_LIMIT. You must specify at least one class.The MPS automatically provides an "overlarge" class for arbitrarily large objects above the largest class described. Allocations falling into the overlarge class are not cached.

+ + +

Example

+ +
+  mps_sac_t sac;
+  mps_sac_class_s classes[3] = { {8, 38, 1}, {136, 19, 3}, {512, 4, 1} };
+
+  res = mps_sac_create(&sac, pool, 3, classes);
+  if (res != MPS_RES_OK) {
+    printf("Failed to create the allocation cache!");
+    exit(1);
+  }
+
+ + +

Error Handling

+ +

mps_sac_create returns MPS_RES_MEMORY orMPS_RES_COMMIT_LIMIT when it fails to allocate memory for the internal cache structure;see the documentation for those return codes for recovery options. It returnsMPS_RES_LIMIT if you ask for too many size classes; combine some small adjacent classes. It returns MPS_RES_PARAM if the pool doesn't support segregated allocation caches.

+ + +

See Also

+ +

+ +mps_sac_class_s, + +MPS_SAC_CLASS_LIMIT, + +mps_sac_destroy, + +MPS_RES_MEMORY, + +MPS_RES_COMMIT_LIMIT, + +MPS_RES_LIMIT, + +MPS_RES_PARAM, + +mps_sac_t

+ + +

Notes

+ +

Too many classes will slow down allocation; too few classes waste more space in internal fragmentation. It is assumed that overlarge allocations are rare; otherwise, you would add another class for them, or even create separate allocation caches or pools for them.

+ +

Some pools will work more efficiently with caches than others. In the future, the MPS might offer pools specially optimized for particular types of cache.

+ +

Segregated allocation caches work poorly with debug pool classes at the moment: the checking only happens when blocks are moved between the cache and the pool. This will be fixed, but the speed of allocation with a debug class will always be similar to mps_alloc, rather than cached speed.

+ + +

Type

+ +

size_t

+ + +

Associated Protocols

+ +

Allocation cache

+ + +

Description

+ +

MPS_SAC_CLASS_LIMIT specifies a lower limit on the maximum number of classes that can be described in a call to mps_sac_create, i.e., the MPS guarantees to accept at least this many classes. More might be accepted -- in fact, there might not be any limit in the implementation on the maximum number of classes, but if you specify more than this, you should be prepared to handle the error.

+ +

MPS_SAC_CLASS_LIMIT is a macro suitable for use in a constant expression, both in a #if directive and wherever else constant expressions may be used.

+ + + +

See Also

+ +

+ +mps_sac_create

+ + +

Notes

+ +

If you ask for too many size classes, mps_sac_create returns MPS_RES_LIMIT; you can recover by combining some small adjacent classes.

+ + +.. c:function:: void mps_sac_destroy(mps_sac_t); + + +

Summary

+ +

This function destroys a segregated allocation cache.

+ + +

Associated Protocols

+ +

Allocation cache

+ + +

Arguments

+ +

sac the segregated allocation cache

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

This function destroys a segregated allocation cache. All memory held in it is returned to the associated pool.

+ + +

Example

+ +
+  res = mps_sac_create(&sac, pool, 3, classes);
+  if (res != MPS_RES_OK) {
+    printf("Failed to create the allocation cache!");
+    exit(1);
+  }
+
+  /* Use sac. */
+
+  mps_sac_destroy(sac);
+  mps_pool_destroy(pool);
+
+ + +

See Also

+ +

+ +mps_sac_create, + +mps_sac_t

+ + +

Notes

+ +

Destroying the cache might well cause the pool to return some memory to the arena, but that's up to the pool's usual policy.

+ +

Destroying the cache has no effect on objects allocated through it.

+ + +.. c:function:: void mps_sac_flush(mps_sac_t sac); + + +

Summary

+ +

This function flushes the segregated allocation cache given.

+ + +

Associated Protocols

+ +

Allocation cache

+ + +

Arguments

+ +

sac the segregated allocation cache

+ + +

Returned Values

+ +

None.

+ + +

Description

+ +

This function flushes the segregated allocation cache given, returning all memory held in it to the associated pool.

+ +

The client is responsible for synchronizing the access to the cache, but the MPS will properly synchronize with any other threads that might be accessing the same pool.

+ + +

Example

+ +
+  mps_sac_t sac_small, sac_large;
+
+  res = mps_sac_create(&sac_small, pool, 3, small_classes);
+  if (res != MPS_RES_OK) {
+    printf("Failed to create the small allocation cache!");
+    exit(1);
+  }
+
+  res = mps_sac_create(&sac_large, pool, 3, large_classes);
+  if (res != MPS_RES_OK) {
+    printf("Failed to create the large allocation cache!");
+    exit(1);
+  }
+
+  /* Use sac_small. */
+
+  mps_sac_flush(sac_small);
+
+  /* Use sac_large. */
+
+  mps_sac_flush(sac_large);
+
+  /* Use sac_small. */
+
+ + +

See Also

+ +

+ +mps_sac_t

+ + +

Notes

+ +

This is something that you'd typically do when you know you won't be using the cache for awhile, but want to hold on to the cache itself. Destroying a cache has the effect of flushing it,naturally.

+ +

Flushing the cache might well cause the pool to return some memory to the arena, but that's up to the pool's usual policy.

+ +

Note that the MPS might also decide to take memory from the cache without the client requesting a flush.

+ + +.. c:type:: mps_sac_t + + +

Summary

+ +

Type of segregated allocation caches.

+ + +

Associated Protocols

+ +

Allocation cache

+ + +

Type

+ +

typedef struct mps_sac_s *mps_sac_t;

+ + +

Description

+ +

A value of this type represents an allocation cache with segregated free lists. It is an opaque type.

+ + +

Example

+ +
+  mps_sac_t sac;
+  mps_sac_class_s classes[3] = { {8, 38, 1}, {136, 19, 3}, {512, 4, 1} };
+
+  res = mps_sac_create(&sac, pool, 3, classes);
+  if (res != MPS_RES_OK) {
+    printf("Failed to create the allocation cache!");
+    exit(1);
+  }
+
+ + +

See Also

+ +

+ +mps_sac_create, + +mps_sac_destroy, + +MPS_SAC_ALLOC, + +mps_sac_alloc, + +MPS_SAC_FREE, + +mps_sac_free, + +mps_sac_flush

+ + +

Notes

+ +

None.

+ + +.. c:function:: mps_res_t mps_stack_scan_ambig(mps_ss_t scan_state, mps_thr_t thread, void *stack_bottom, size_t ignore) + + +

Summary

+ +

A scanning function for ambiguous scanning of thread states.

+ + +

Associated Protocols

+ +

Root.

+ + +

Arguments

+ +

scan_state a scan state

+ +

thread the thread

+ +

stack_bottom a pointer to the bottom of the stack

+ +

ignore ignored

+ + +

Returned Values

+ +

A result code.

+ + +

Description

+ +

This is a root scanning function of type mps_reg_scan_t. It will scan all integer registers and everything on the stack of the thread given, and can therefore only be used with roots of rank MPS_RANK_AMBIG. It will only scan things at the given stack bottom pointer or higher on the stack (that is, more recently added). References are assumed to be represented as machine words, and are required to be 4-byte-aligned; unaligned values are ignored.

+ +

Clients don't call this function, it is used as an argument of mps_root_create_reg.

+ + +

Example

+ +
+typedef struct {
+  mps_root_t mmRoot;
+  mps_thr_t thread;
+  /* ... */
+} ThreadLocals;
+
+void InitThread(ThreadLocals *thr)
+{
+  /* This is a hack to find the bottom of the stack. */
+  void *stackBottom=&stackBottom;
+
+  mps_thread_reg(&thr->thread, arena);
+  mps_root_create_reg(&thr->mmRoot, arena, MPS_RANK_AMBIG, (mps_rm_t)0,
+    thr->thread, mps_stack_scan_ambig, stackBottom, 0)
+
+  /* ... */
+}
+
+ + +

See Also

+ +

+ +mps_reg_scan_t, + +mps_root_create_reg

+ + +

Notes

+ +

The MPS provides this function because it's hard to write (it's OS- and architecture-dependent and possibly compiler-dependent).

+ + +.. c:function:: mps_word_t mps_telemetry_control(mps_word_t reset_mask, mps_word_t flip_mask); + + +

Summary

+ +

This function is used to read and change the filters on the telemetry stream.

+ + +

Associated Protocols

+ +

Telemetry.

+ + +

Arguments

+ +

reset_mask is a bit mask indicating the bits that should be reset, regardless of previous value.

+ +

flip_mask is a bit mask indicating the bits whose value should be flipped after the resetting.

+ + +

Returned Values

+ +

The function returns the previous value of the telemetry filter control.

+ + +

Description

+ +

This function is used to read and change the filters on the telemetry stream. It is generally for use by developers.

+ +

The parameters reset_mask and flip_mask allow specifying any binary operation on the filter control. To use this function for typical operations, the parameters should be set as follows:

+ +

Operation reset_mask flip_mask

+ +

set(M) M M

+ +

reset(M) M 0

+ +

flip(M) 0 M

+ +

read() 0 0

+ +

The significance of the bits is liable to change, but the current values (number the least significant bit as zero) are:

+ +

0 -- per space or arena

+ +

1 -- per pool

+ +

2 -- per trace or scan

+ +

3 -- per page (segment)

+ +

4 -- per reference or fix

+ +

5 -- per allocation or object

+ +

6 -- user events (e.g., mps_telemetry_intern)

+ + +

Example

+ + +

See Also

+ +

+ +mps_lib_telemetry_control

+ + +.. c:function:: void mps_telemetry_flush(void); + + +

Summary

+ +

This function is used to flush the internal event buffers.

+ + +

Associated Protocols

+ +

Telemetry.

+ + +

Description

+ +

This function is used to flush the internal event buffers into the event stream. This function also calls mps_lib_io_flush on the event stream itself. This ensures that even the latest events are now properly recorded, should the application terminate (uncontrollably as a result of a bug, for example) or some interactive tool require access to the event data. You could even try calling this from a debugger after a problem.

+ + +

Example

+ +

mps_telemetry_flush();

+ + +

See Also

+ +

+ +mps_lib_io_flush

+ + +.. c:function:: mps_word_t mps_telemetry_intern(char *) + + +

Summary

+ +

This function registers a string with the MPS, and receives a unique identifier in return.This identifier is suitable for use with mps_telemetry_label.

+ + +

Associated Protocols

+ +

Telemetry

+ + +

Arguments

+ +

The function receives a name as a nul-terminated string in the usual C way. The string's length should not exceed 256 characters, including nul terminating character. In appropriate varieties this restriction is checked and will cause the MPS to issue an ASSERT. So don't do it.

+ + +

Returned Values

+ +

The function returns a unique identifier that may be used to represent the string in future.

+ + +

Description

+ +

The intention of this function is to provide an immediate identifier that can be used to concisely represent a string for the purposes of mps_telemetry_label. Note that the appropriate settings must be made to the telemetry filter (via mps_telemetry_control) before this function is invoked; the associate event is of the user kind.

+ + +

Error Handling

+ +

The string's length should not exceed 256 characters, including nul terminating character.This will cause the MPS to issue an ASSERT in appropriate varieties.

+ + +

See Also

+ +

+ +mps_telemetry_label

+ +

+ +mps_telemetry_control

+ + +.. c:function:: void mps_telemetry_label(mps_addr_t, mps_word_t); + + +

Summary

+ +

This function associates an identifier returned from mps_telemetry_intern, and hence a string, with an address, in the telemetry stream.

+ + +

Associated Protocols

+ +

telemetry

+ + +

Arguments

+ +

The function receives an address and an identifier. The identifier should be one returned by mps_telemetry_intern in the same session.

+ + +

Description

+ +

This function is intended to associate the address with an identifier in the telemetry stream. Note that the user kind must be set in the telemetry filter.

+ + +

Example

+ +

Typical uses include:

+ +

- Label pools with a human-meaningful name;

+ +

- Label allocated objects with their type or class.

+ + +

See Also

+ +

+ +mps_telemetry_intern, + +mps_telemetry_control, + +mps_thr_t

+ + +.. c:type:: mps_thr_t + + + +

Summary

+ +

mps_thr_t is the type of thread records registered with the MPS.

+ + +

Associated Protocols

+ +

Threads.

+ + +

Type

+ +

typedef mps_thr_s *mps_thr_t;

+ + +

Description

+ +

An object of the opaque type mps_thr_t is a thread registration. In a multi-threaded environment where incremental garbage collection is used, threads must be registered with the MPS so that the MPS can examine their state.

+ +

An object of type mps_thr_t is obtained using the thread registration function mps_thread_reg.

+ + +

Example

+ +
+  mps_thr_t this_thread;
+  mps_res_t res;
+
+  res = mps_thread_reg(&this_thread, space);
+  if(res != MPS_RES_OK) return res;
+
+ + +

See Also

+ +

+ +mps_reg_t, + +mps_thread_reg, + +mps_thread_dereg, + +mps_reg_scan_t, + +mps_root_create_reg, + +mps_stack_scan_ambig

+ + +

4. Undocumented Symbols

+ +

The following MPS symbols are used or defined in MPS header files, and intended for client use, but are not yet documented in this reference manual.

+ +

[This section is very out-of-date. RB 2012-08-15]

+ +
+mps_arena_t
+mps_pool_t
+mps_chain_t
+mps_root_t
+mps_ap_t
+mps_ld_t
+mps_ss_t
+mps_alloc_pattern_t
+mps_frame_t
+mps_word_t
+mps_shift_t
+mps_rm_t
+MPS_RES_OK
+MPS_RES_FAIL
+MPS_RES_UNIMPL
+MPS_RES_IO
+MPS_RES_COMMIT_LIMIT
+mps_ap_s
+mps_sac_freelist_block_s
+mps_sac_s
+mps_ld_s
+mps_ss_s
+mps_fmt_fixed_s
+MPS_BEGIN
+MPS_END
+mps_arena_step
+mps_arena_start_collect
+mps_arena_destroy
+mps_arena_reserved
+mps_arena_extend
+mps_arena_retract
+mps_fmt_create_fixed
+mps_fmt_destroy
+mps_addr_pool
+mps_addr_fmt
+mps_pool_create
+mps_pool_create_v
+mps_pool_destroy
+mps_gen_param_s
+mps_chain_create
+mps_chain_destroy
+mps_alloc_v
+mps_ap_create
+mps_ap_create_v
+mps_ap_destroy
+mps_reserve
+mps_commit
+mps_ap_fill
+mps_ap_fill_with_reservoir_permit
+mps_ap_trip
+MPS_SAC_ALLOC
+MPS_SAC_FREE
+mps_reservoir_limit_set
+mps_reservoir_limit
+mps_reservoir_available
+mps_reserve_with_reservoir_permit
+MPS_RESERVE_BLOCK
+MPS_RESERVE_WITH_RESERVOIRf_PERMIT_BLOCK
+mps_root_destroy
+mps_tramp_t
+mps_tramp
+mps_thread_reg
+mps_thread_dereg
+mps_ld_reset
+mps_ld_add
+mps_ld_merge
+mps_ld_isstale
+mps_collections
+mps_definalize
+mps_alert_collection_set
+mps_pool_check_free_space
+mps_lib_get_EOF
+mps_lib_stream_s
+mps_lib_get_stderr
+mps_lib_get_stdout
+mps_lib_fputc
+mps_lib_fputs
+mps_lib_assert_fail
+mps_clock_t
+mps_clock
+mps_clocks_per_sec
+mps_class_amcz
+mps_class_ams
+mps_class_ams_debug
+mps_class_awl
+mps_class_lo
+mps_mv_free_size
+mps_mv_size
+mps_class_mv
+mps_class_mv_debug
+mps_mvt_free_size
+mps_mvt_size
+mps_mvff_free_size
+mps_mvff_size
+mps_class_mvff_debug
+mps_SEH_filter
+mps_SEH_handler
+mps_io_t
+mps_io_create
+mps_io_destroy
+mps_io_write
+mps_io_flush
+MPS_PF_STRING
+MPS_PF_ALIGN
+MPS_ARCH_I3
+MPS_ARCH_I4
+MPS_ARCH_PP
+MPS_ARCH_S8
+MPS_ARCH_S9
+MPS_BUILD_GC
+MPS_BUILD_MV
+MPS_BUILD_SC
+MPS_OS_FR
+MPS_OS_LI
+MPS_OS_SO
+MPS_OS_W3
+MPS_OS_XC
+MPS_PF_FRI3GC
+MPS_PF_LII3GC
+MPS_PF_LIPPGC
+MPS_PF_SOS8GC
+MPS_PF_SOS9SC
+MPS_PF_W3I3MV
+MPS_PF_XCPPGC
+
+ +

A. References

+ + +

B. Document History

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
2002-05-27RB Created from individual MPS reference pages, originally written and mainted in Lotus Notes by members of the Memory Management Group of Global Graphics (formerly Harlequin). I found many errors caused by the various conversions that this text has been through. There are probably many more.
2002-06-17RB Removed Global Graphics specific entries for confidential sources not included in open source release.
2002-06-18NB Added contents table to section 3.
2002-06-20NBQuite a bit of proof-reading, to insert missing spaces. Also reformatted for easier editing, including the "See Also" sections.
2002-06-21NBRemoved obsolete symbols.
2003-01-01DRJ[various edits in 2003]
2006-06-06RHSKMarked copy format method as obsolete.
2007-06-19DRJmps_finalize and finalization messages: correct, clarify, and expand descriptions
2008-10-24RHSKmps_arena_has_addr entry: fix wrong title; remove from undocumented symbols list. (Also: fix html tag error; add missing document history entries).
2008-11-25RHSKmps_message_clock: add entry.
2010-03-02RHSKmps_addr_pool, mps_addr_fmt, mps_alert_collection_set: as yet Undocumented.
+ + +

C. Copyright and License

+ +
+ +
+ +

$Id: //info.ravenbrook.com/project/mps/branch/2012-10-09/user-guide/manual/reference/index.html#1 $

+ +

+Ravenbrook / +Projects / +Memory Pool System / +Master Product Sources / +Product Manuals +

+ +
+ + + + + diff --git a/mps/manual/source/topic/allocation.rst b/mps/manual/source/topic/allocation.rst new file mode 100644 index 00000000000..d39ec7233f8 --- /dev/null +++ b/mps/manual/source/topic/allocation.rst @@ -0,0 +1,47 @@ +.. _topic-allocation: + +Allocation +========== + + +This example seems to be wrong (no function "mps_pool_alloc" in the public interface). + + +
+{
+  mps_addr_t new_block;
+  mps_res_t res;
+  thingy *tp;
+
+  res = mps_pool_alloc(&new_block, pool, sizeof(thingy));
+  if(res != MPS_RES_OK) return res;
+  tp = new_block;
+
+  /* ... */
+}
+
+ + + Some :term:`pools ` and :term:`allocation protocols + ` accept an alignment as an option. This + ensures that objects in the pool or objects allocated observe a + stricter alignment than that of the object format. + + + + +

Example

+ +
+  mps_res_t res;
+  mps_addr_t p;
+
+  res = mps_alloc(&p, pool, size);
+  if(res != MPS_RES_OK) {
+    /* p hasn't been touched in this case. */
+    handle error;
+  }
+
+  /* p now contains the result, which is the address of the new block */
+  /* in this case. */
+
diff --git a/mps/manual/source/topic/cache.rst b/mps/manual/source/topic/cache.rst new file mode 100644 index 00000000000..0164a9d91a9 --- /dev/null +++ b/mps/manual/source/topic/cache.rst @@ -0,0 +1,109 @@ +.. _topic-cache: + +Allocation caches +================= + + + +
+  void *p;
+  Foo *foo;
+
+  res = mps_sac_alloc(&p, sac, FooSIZE, is_in_panic);
+  if (res != MPS_RES_OK) {
+    printf("Failed to alloc foo!\n");
+    exit(1);
+  }
+  foo = p;
+
+  /* use foo */
+
+  mps_sac_free(sac, p, FooSIZE);
+
+ + +What does this mean? (from mps_sac_alloc): + + The client is responsible for synchronising the access to the + cache, but if the cache decides to access the pool, the MPS will + properly synchronize with any other threads that might be + accessing the same pool. + + +
+  void *p;
+  Foo *foo;
+  mps_res_t res;
+
+  MPS_SAC_ALLOC_FAST(res, p, sac, FooSIZE, is_in_panic);
+  if (res != MPS_RES_OK) {
+    printf("Failed to alloc foo!\n");
+    exit(1);
+  }
+  foo = p;
+
+  /* use foo */
+
+  MPS_SAC_FREE_FAST(sac, p, FooSIZE);
+
+ + + +

Example

+ +
+  mps_sac_t sac;
+  mps_sac_class_s classes[3] = { {8, 38, 1}, {136, 19, 3}, {512, 4, 1} };
+
+#if (MPS_SAC_CLASS_LIMIT < 3)
+#  error "Too many classes!"
+#endif
+
+  res = mps_sac_create(&sac, pool, 3, classes);
+  if (res != MPS_RES_OK) {
+    printf("Failed to create the allocation cache!");
+    exit(1);
+  }
+
+ + + + +

Example

+ +
+  void *p;
+  Foo *foo;
+
+  res = mps_sac_alloc(&p, sac, FooSIZE, is_in_panic);
+  if (res != MPS_RES_OK) {
+    printf("Failed to alloc foo!\n");
+    exit(1);
+  }
+  foo = p;
+
+  /* use foo */
+
+  mps_sac_free(sac, p, FooSIZE);
+
+ + + +

Example

+ +
+  void *p;
+  Foo *foo;
+  mps_res_t res;
+
+  MPS_SAC_ALLOC_FAST(res, p, sac, FooSIZE, is_in_panic);
+  if (res != MPS_RES_OK) {
+    printf("Failed to alloc foo!\n");
+    exit(1);
+  }
+  foo = p;
+
+  /* use foo */
+
+  MPS_SAC_FREE_FAST(sac, p, FooSIZE);
+
diff --git a/mps/manual/source/topic/error.rst b/mps/manual/source/topic/error.rst new file mode 100644 index 00000000000..acd8dd0b5c1 --- /dev/null +++ b/mps/manual/source/topic/error.rst @@ -0,0 +1,35 @@ +.. _topic-error: + +Error handing +============= + + + + +

Example

+ +
+  switch(mps_alloc(&(mps_addr_t)object, pool, size)) {
+  case MPS_RES_LIMIT:
+    bomb("The MPS has reached an internal limit");
+    break;
+
+    /* ... */
+
+  }
+
+ + + +

Example

+ +
+  switch( res = mps_pool_create_v(&pool, arena, class, params) ) {
+  case MPS_RES_PARAM:
+    bomb("Can't make a pool with those specifications");
+    break;
+
+    /* ... */
+
+   }
+
diff --git a/mps/manual/source/topic/frame.rst b/mps/manual/source/topic/frame.rst new file mode 100644 index 00000000000..449ad9166db --- /dev/null +++ b/mps/manual/source/topic/frame.rst @@ -0,0 +1,5 @@ +.. _topic-frame: + +Allocation frames +================= + diff --git a/mps/manual/source/topic/index.rst b/mps/manual/source/topic/index.rst new file mode 100644 index 00000000000..0f498a993e4 --- /dev/null +++ b/mps/manual/source/topic/index.rst @@ -0,0 +1,15 @@ +Topic reference +=============== + +.. toctree:: + :maxdepth: 2 + + allocation + error + scanning + moving + root + cache + platform + pattern + frame diff --git a/mps/manual/source/topic/moving.rst b/mps/manual/source/topic/moving.rst new file mode 100644 index 00000000000..d9fdcb03817 --- /dev/null +++ b/mps/manual/source/topic/moving.rst @@ -0,0 +1,4 @@ +.. _topic-moving: + +Moving pools +============ diff --git a/mps/manual/source/topic/pattern.rst b/mps/manual/source/topic/pattern.rst new file mode 100644 index 00000000000..6c332994793 --- /dev/null +++ b/mps/manual/source/topic/pattern.rst @@ -0,0 +1,110 @@ +.. _topic-pattern: + +Allocation patterns +=================== + + + +
+{
+  mps_ap_alloc_pattern_begin(ap, mps_alloc_pattern_ramp());
+  do_lots_of_work();
+  mps_ap_alloc_pattern_end(ap, mps_alloc_pattern_ramp());
+}
+
+ + + +

Example

+ +
+{
+  mps_ap_alloc_pattern_begin(ap, mps_alloc_pattern_ramp_collect_all());
+  do_lots_of_work();
+  mps_ap_alloc_pattern_end(ap, mps_alloc_pattern_ramp_collect_all());
+  wait_for_collection_statistics_while_doing_other_allocation();
+}
+
+ + + + +

Example

+ +
+{
+  res = mps_ap_alloc_pattern_begin(ap, mps_alloc_pattern_ramp());
+  assert(res == mps_res_ok);
+
+  do_some_work(); /* Leaves stuff lying around */
+
+  res = mps_ap_alloc_pattern_begin(ap, mps_alloc_pattern_ramp());
+  assert(res == mps_res_ok);
+
+  do_some_more_work(); /* Tidies up after itself */
+
+  res = mps_ap_alloc_pattern_end(ap, mps_alloc_pattern_ramp());
+  assert(res == mps_res_ok);
+
+  tidy_up_first_work();
+
+  res = mps_ap_alloc_pattern_end(ap, mps_alloc_pattern_ramp());
+  assert(res == mps_res_ok);
+}
+
+ + + +
+{
+  res = mps_ap_alloc_pattern_begin(ap, mps_alloc_pattern_ramp());
+  assert(res == mps_res_ok);
+
+  do_some_work(); /* Leaves stuff lying around */
+
+  res = mps_ap_alloc_pattern_begin(ap, mps_alloc_pattern_ramp());
+  assert(res == mps_res_ok);
+
+  do_some_more_work(); /* Tidies up after itself */
+
+  res = mps_ap_alloc_pattern_end(ap, mps_alloc_pattern_ramp());
+  assert(res == mps_res_ok);
+
+  tidy_up_first_work();
+
+  res = mps_ap_alloc_pattern_end(ap, mps_alloc_pattern_ramp());
+  assert(res == mps_res_ok);
+}
+
+ + +

Example

+ +
+{
+  res = mps_ap_alloc_pattern_begin(ap, mps_alloc_pattern_ramp());
+  assert(res == mps_res_ok);
+
+  do_some_work(); /* Leaves stuff lying around */
+
+  res = mps_ap_alloc_pattern_begin(ap, mps_alloc_pattern_ramp());
+  assert(res == mps_res_ok);
+
+  res = do_some_more_work(); /* Tidies up after itself */
+  if(res != mps_res_ok) {
+    res = mps_ap_alloc_pattern_reset(ap);
+    assert(res == mps_res_ok);
+    return;
+  }
+
+  res = mps_ap_alloc_pattern_end(ap, mps_alloc_pattern_ramp());
+  assert(res == mps_res_ok);
+
+  tidy_up_first_work();
+
+  res = mps_ap_alloc_pattern_end(ap, mps_alloc_pattern_ramp());
+  assert(res == mps_res_ok);
+}
+
+ + diff --git a/mps/manual/source/topic/platform.rst b/mps/manual/source/topic/platform.rst new file mode 100644 index 00000000000..94739b79de2 --- /dev/null +++ b/mps/manual/source/topic/platform.rst @@ -0,0 +1,5 @@ +.. _topic-platform: + +Supporting MPS on a new platform +================================ + diff --git a/mps/manual/source/topic/root.rst b/mps/manual/source/topic/root.rst new file mode 100644 index 00000000000..efe45abc8af --- /dev/null +++ b/mps/manual/source/topic/root.rst @@ -0,0 +1,26 @@ +.. _topic-root: + +Roots +===== + + + +

MPS_RM_CONST is a preprocessor macro defining a constant that can be OR'ed with other MPS_RM_* constants, and passed as the root mode argument to certain root creation functions (mps_root_create, mps_root_create_fmt, mps_root_create_table, mps_root_create_table_masked, mps_root_create_reg ).

+ + +from MPS_RM_PROT: + +

No page may contain parts of two or more roots with MPS_RM_PROT [how does one prevent +that?]. You mustn't specify MPS_RM_PROT if the client program or +anything other than (this instance of) the MPS is going to protect or +unprotect the relevant pages.

+ +

Internal Notes

+ +

Future meaning: The MPS may place a hardware read and/or write barrier on any pages which any part of the root covers. Format methods and scanning functions (except for the one for this root) may not read or write data in this root. You may specify MPS_RM_PROT on a root allocated from the MPS, as long as it's not from a GCd pool. - drj 1997-12-18

+ +

This feature is far too technical for most of our clients: we should think about producing some guidelines on how to use it. - pekka 1998-01-27

+ +

There may be problems if the client wants the OS to access the root. Lots of OSes can't cope with writing to protected pages. So we'll need to document that caveat too. drj 1998-05-20

diff --git a/mps/manual/source/topic/scanning.rst b/mps/manual/source/topic/scanning.rst new file mode 100644 index 00000000000..4296aa8dfe8 --- /dev/null +++ b/mps/manual/source/topic/scanning.rst @@ -0,0 +1,129 @@ +.. _topic-scanning: + +Scanning +======== + + + +

Returned Values

+ +

Returns a result code, see ERROR HANDLING.

+ +

If the reference rank of the object being scanned is not MPS_RANK_AMBIG then the reference pointed to by ref_io may be modified by mps_fix.

+ + +

Description

+ +

This function is the part of the scanning protocol used to indicate references. Scanning functions apply it, or MPS_FIX12, or MPS_FIX1 and MPS_FIX2 to the references in the object being scanned.

+ +

It may only be called from within a scanning function. If it is called within a MPS_SCAN_BEGIN block, MPS_FIX_CALL must be used (yes, really).

+ +

This function does not perform any particular operation. The MPS may call scanning functions for a number of reasons, and mps_fix may take different actions depending on those reasons.

+ + +

Example

+ +
+mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length)
+{
+  size_t i;
+
+  mps_res_t res;
+  mps_addr_t *array = (mps_addr_t *)object;
+  for(i = 0; i < length; ++i) {
+    res = mps_fix(ss, &array[i]);
+    if(res != MPS_RES_OK) return res;
+  }
+
+  return res;
+}
+
+ + +

Error Handling

+ +

The function returns MPS_RES_OK if it was successful, in which case the scanning function should continue to scan the rest of the object, applying mps_fix to the remaining references. If mps_fix returns a value other than MPS_RES_OK, the scanning function must return that value, and may return without scanning further references. Generally, it is better if it returns as soon as possible.

+ + + + + +

Example

+ +
+mps_res_t scan_array(mps_ss_t ss, Array object, size_t length)
+{
+  size_t i;
+
+  mps_res_t res;
+  mps_addr_t *array = (mps_addr_t *)object;
+  MPS_SCAN_BEGIN(ss)
+  for(i = 0; i < length; ++i) {
+    mps_addr_t ref = array[i];
+    if(MPS_FIX1(ss, ref)) {
+      /* if(((Object*)ref)->type == ScannableType) { */
+      /* You can do something here, but in the end, you must call MPS_FIX2. */
+      res = MPS_FIX2(ss, &array[i]);
+      if(res != MPS_RES_OK)
+        return res;
+      /* } */
+    }
+  }
+  MPS_SCAN_END(ss);
+
+  return res;
+}
+
+ + + + +

Example

+ +
+mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length) {
+  size_t i;
+
+  mps_res_t res;
+  mps_addr_t *array = (mps_addr_t *)object;
+  MPS_SCAN_BEGIN(ss)
+  for(i = 0; i < length; ++i) {
+    res = MPS_FIX(ss, &array[i]);
+    if(res != MPS_RES_OK)
+      return res;
+  }
+  MPS_SCAN_END(ss);
+
+  return res;
+}
+
+ + +

Error Handling

+ +

The macro returns MPS_RES_OK if it was successful, in which case the scanning function should continue to scan the rest of the object, fixing the remaining references. If MPS_FIX12 returns a value other than MPS_RES_OK, the scanning function must return that value, and may return without scanning further references. Generally, it is better if it returns as soon as possible.

+ + + + +

Example

+ +
+mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length)
+{
+  size_t i;
+  mps_res_t res;
+  mps_addr_t *array = (mps_addr_t *)object;
+
+  MPS_SCAN_BEGIN(ss)
+  for(i = 0; i < length; ++i) {
+    res = MPS_FIX12(ss, &array[i]);
+    if(res != MPS_RES_OK)
+      return res;
+  }
+  MPS_SCAN_END(ss);
+
+  return res;
+}
+
+