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
.. index::
   single: MFS pool class
   single: pool class; MFS

.. _pool-mfs:

MFS (Manual Fixed Small)
========================

**MFS** is an :term:`manually managed <manual memory management>`
:term:`pool class` for small objects of fixed size.

Unlike other manual pool classes, it is not subject to :term:`internal
fragmentation`: if the population remains bounded, the memory usage
remains bounded too. On the other hand, unlike :ref:`pool-mvt` and
:ref:`pool-mvff` it does not return unused memory to the arena for
reuse by other pools.

The implementation is very simple: unlike most other :term:`pool
classes` which store their control structures separately from the
allocated blocks, MFS maintains a stack of free blocks using a pointer
in the free block. :c:func:`mps_alloc` pops this stack and
:c:func:`mps_free` pushes it.


.. index::
   single: MFS pool class; properties

MFS 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` (but using one would
  be pointless, since all blocks are the same size).

* 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 are fixed in size.

* The :term:`alignment` of blocks is not configurable: it is the
  :term:`natural alignment` of the platform (see
  :c:macro:`MPS_PF_ALIGN`).

* 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: MFS pool class; interface

MFS interface
-------------

::

   #include "mpscmfs.h"

.. c:function:: mps_pool_class_t mps_class_mfs(void)

    Return the :term:`pool class` for an MFS (Manual Fixed Small)
    :term:`pool`.

    When creating an MFS pool, :c:func:`mps_pool_create_k` requires
    one :term:`keyword argument`:

    * :c:macro:`MPS_KEY_MFS_UNIT_SIZE` (type :c:type:`size_t`) is the
      :term:`size` of blocks that will be allocated from this pool, in
      :term:`bytes (1)`. It must be at least one :term:`word`.

    In addition, :c:func:`mps_pool_create_k` accepts one optional
    keyword argument:

    * :c:macro:`MPS_KEY_EXTEND_BY` (type :c:type:`size_t`,
      default 65536) is the :term:`size` of extent that the pool will
      request from the :term:`arena`. For efficiency, this should be
      much larger than :c:macro:`MPS_KEY_MFS_UNIT_SIZE`, so that many
      blocks fit into each extent.

    For example::

        MPS_ARGS_BEGIN(args) {
            MPS_ARGS_ADD(args, MPS_KEY_MFS_UNIT_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);