1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
.. index::
   single: MV
   single: pool class; MV

.. _pool-mv:

MV (Manual Variable)
====================

.. deprecated:: starting with version 1.111.

    :ref:`pool-mvff` or :ref:`pool-mvt` should be used instead.

**MV** is a general-purpose :term:`manually managed <manual memory
management>` :term:`pool class` that manages :term:`blocks` of
variable size.


.. index::
   single: MV; properties

MV properties
-------------

* Supports allocation via :c:func:`mps_alloc` and deallocation via
  :c:func:`mps_free`.

* Does not support allocation via :term:`allocation points`.

* Does not support :term:`allocation frames`.

* Supports :term:`segregated allocation caches`.

* There are no garbage collections in this pool.

* Blocks may not contain :term:`references` to blocks in automatically
  managed pools (unless these are registered as :term:`roots`).

* Allocations may be variable in size.

* The :term:`alignment` of blocks is configurable.

* Blocks do not have :term:`dependent objects`.

* Blocks are not automatically :term:`reclaimed`.

* Blocks are not :term:`scanned <scan>`.

* Blocks are not protected by :term:`barriers (1)`.

* Blocks do not :term:`move <moving garbage collector>`.

* Blocks may not be registered for :term:`finalization`.

* Blocks must not belong to an :term:`object format`.


.. index::
   single: MV; interface

MV interface
------------

::

   #include "mpscmv.h"

.. c:function:: mps_class_t mps_class_mv(void)

    Return the :term:`pool class` for an MV (Manual Variable)
    :term:`pool`.

    When creating an MV pool, :c:func:`mps_pool_create_k` may take
    the following :term:`keyword arguments`:

    * :c:macro:`MPS_KEY_ALIGN` (type :c:type:`mps_align_t`, default is
      :c:macro:`MPS_PF_ALIGN`) is the
      :term:`alignment` of addresses for allocation (and freeing) in
      the pool. If an unaligned size is passed to :c:func:`mps_alloc` or
      :c:func:`mps_free`, it will be rounded up to the pool's alignment.

    * :c:macro:`MPS_KEY_EXTEND_BY` (type :c:type:`size_t`,
      default 65536) is the :term:`size` of segment that the pool will
      request from the :term:`arena`.

    * :c:macro:`MPS_KEY_MEAN_SIZE` (type :c:type:`size_t`, default 32)
      is the predicted mean size of blocks that will be allocated from
      the pool. This value must be smaller than, or equal to, the
      value for :c:macro:`MPS_KEY_EXTEND_BY`.

    * :c:macro:`MPS_KEY_MAX_SIZE` (type :c:type:`size_t`,
      default 65536) is the predicted maximum size of blocks that will
      be allocated from the pool. This value must be larger than, or
      equal to, the value for :c:macro:`MPS_KEY_EXTEND_BY`.

    The mean and maximum sizes are *hints* to the MPS: the pool will be
    less efficient if these are wrong, but nothing will break.

    For example::

        MPS_ARGS_BEGIN(args) {
            MPS_ARGS_ADD(args, MPS_KEY_MEAN_SIZE, 32);
            MPS_ARGS_ADD(args, MPS_KEY_MAX_SIZE, 1024);
            MPS_ARGS_ADD(args, MPS_KEY_EXTEND_BY, 1024 * 1024);
            res = mps_pool_create_k(&pool, arena, mps_class_mfs(), args);
        } MPS_ARGS_END(args);

    .. deprecated:: starting with version 1.112.

        When using :c:func:`mps_pool_create`, pass the segment size,
        mean size, and maximum size like this::

            mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena, 
                                      mps_class_t mps_class_mv(),
                                      size_t extend_size,
                                      size_t average_size,
                                      mps_size_t maximum_size)


.. c:function:: mps_class_t mps_class_mv_debug(void)

    A :ref:`debugging <topic-debugging>` version of the MV pool
    class.

    When creating a debugging MV pool, :c:func:`mps_pool_create_k`
    takes the following keyword arguments: :c:macro:`MPS_KEY_ALIGN`,
    :c:macro:`MPS_KEY_EXTEND_SIZE`, :c:macro:`MPS_KEY_MEAN_SIZE`,
    :c:macro:`MPS_KEY_MAX_SIZE` are as described above, and
    :c:macro:`MPS_KEY_POOL_DEBUG_OPTIONS` specifies the debugging
    options. See :c:type:`mps_debug_option_s`.

    .. deprecated:: starting with version 1.112.

        When using :c:func:`mps_pool_create`, pass the arguments like
        this::

            mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena, 
                                      mps_class_t mps_class_mv_debug(),
                                      mps_pool_debug_option_s debug_option,
                                      mps_size_t extend_size,
                                      mps_size_t average_size,
                                      mps_size_t maximum_size)


.. index::
   pair: MV; introspection

MV introspection
----------------

::

   #include "mpscmv.h"

.. c:function:: size_t mps_mv_free_size(mps_pool_t pool)

    Return the total amount of free space in an MV pool.

    ``pool`` is the MV pool.

    Returns the total free space in the pool, in :term:`bytes (1)`.


.. c:function:: size_t mps_mv_size(mps_pool_t pool)

    Return the total size of an MV pool.

    ``pool`` is the MV pool.

    Returns the total size of the pool, in :term:`bytes (1)`. This
    is the sum of allocated space and free space.