Pool reference for mfs.

Copied from Perforce
 Change: 180310
 ServerID: perforce.ravenbrook.com

mps/manual/source/pool/mfs.rst

@@ -0,0 +1,95 @@
+.. index::
+   single: MFS
+   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`.
+
+The implementation is very simple: unlike 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; properties
+
+MSF 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; interface
+
+MFS interface
+-------------
+
+::
+
+   #include "mpscmfs.h"
+
+.. c:function:: mps_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` takes two
+    extra arguments::
+
+        mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena, 
+                                  mps_class_t mps_class_mfs(),
+                                  mps_size_t unit_size,
+                                  mps_size_t extend_size)
+
+    ``unit_size`` 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`.
+
+    ``extend_size`` is the :term:`size` of segment that the pool will
+    request from the :term:`arena`. It must be at least as big as
+    ``unit_size``. If this is not a multiple of ``unit_size``, there
+    will be wasted space in each segment.