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
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
.. highlight:: none


.. index::
   pair: pool classes; design

.. _design-pool:


Pool classes
============

.. mps:prefix:: design.mps.pool


Introduction
-------------

:mps:tag:`intro` This document describes the interface and protocols between
the MPM and the pool classes.


Classes and structures
----------------------

:mps:tag:`class` Each pool belongs to a *pool class*.

:mps:tag:`class.name` Each pool class has a short, pithy, cryptic name for
the pool class. It should start with ``"A"`` (for "automatic") if
memory is managed by the garbage collector, and ``"M"`` (for "manual")
if memory is managed by alloc/free. For example, "AMC", "MVFF".

:mps:tag:`class.protocol` Pool classes use the *protocol* mechanisms (see
design.mps.protocol_) to implement class initialization and
inheritance.

.. _design.mps.protocol: protocol.html

:mps:tag:`class.structure` Each pool class has an associated *class
structure*, which is a C object of type :c:type:`PoolClass`. This is
initialized and accessed via the :c:func:`CLASS()` macro, for example
``CLASS(MRGPool)`` initializes and accesses the class structure for
the MRG pool class.

:mps:tag:`struct.outer` The *outer structure* of a pool belonging to the ABC
pool class is a C object of type :c:type:`ABCPoolStruct`, which is a typedef
for ``struct PoolABCStruct``.

:mps:tag:`stuct.outer.sig` See `design.mps.sig.field.end.outer`_.

.. _design.mps.sig.field.end.outer: sig.txt.html#design.mps.sig.field.end.outer

:mps:tag:`struct.generic` The *generic structure* of a pool is a C object of
type :c:type:`PoolStruct` (found embedded in the outer structure), which is
a typedef for ``struct PoolStruct``.


Fields
------

:mps:tag:`field` These fields are provided by pool classes as part of the
:c:type:`PoolClass` object (see :mps:ref:`.class.structure`). They form part of the
interface which allows the MPM to treat pools in a uniform manner.

:mps:tag:`field.name` The ``name`` field must be the pool class name
(:mps:ref:`.class.name`).

:mps:tag:`field.size` The ``size`` field is the size of the pool instance
structure. For the ``PoolABC`` class this can reasonably be expected
to be ``sizeof(PoolABCStruct)``.

:mps:tag:`field.attr` The ``attr`` field must be a bitset of pool class
attributes. See design.mps.type.attr_.

.. _design.mps.type.attr: type.html#design.mps.type.attr

:mps:tag:`field.alignShift` The ``alignShift`` field is the ``SizeLog2`` of
the pool's alignment. It is computed and initialised when a pool is
created. Mark-and-sweep pool classes use it to compute the number of
grains in a segment, which is the number of bits need in the segment's
mark and alloc bit tables.

:mps:tag:`field.format` The ``format`` field is used to refer to the object
format. The object format is passed to the pool during pool creation.


Methods
-------

:mps:tag:`method` These methods are provided by pool classes as part of the
:c:type:`PoolClass` object (see :mps:ref:`.class.structure`). They form part of the
interface which allows the MPM to treat pools in a uniform manner.

:mps:tag:`method.unused` If a pool class is not required to provide a
certain method, the class should assign the appropriate ``PoolNo``
method (which asserts) for that method to ensure that erroneous calls
are detected. It is not acceptable to use :c:macro:`NULL`.

:mps:tag:`method.trivial` If a pool class if required to provide a certain
method, but the class provides no special behaviour in this case, it
should assign the appropriate ``PoolTriv`` method, which does nothing.

:mps:tag:`method.inst` Pool classes may implement the generic instance
methods (see design.mps.protocol.inst.method_). In particular:

.. _design.mps.protocol.inst.method: inst.html#design.mps.protocol.inst.method

- :mps:tag:`method.inst.finish` The ``finish`` method
  (design.mps.protocol.inst.method.finish_) must finish the outer
  structure and then call its superclass method via the
  :c:func:`NextMethod()` macro (thus calling :c:func:`PoolAbsFinish()` which
  finishes the generic structure).

  .. _design.mps.protocol.inst.method.finish: inst.html#design.mps.protocol.inst.method.finish

- :mps:tag:`method.inst.describe` The ``describe`` method
  (design.mps.protocol.inst.method.describe_) should print a
  description of the pool. Each line should begin with two spaces.
  Classes are not required to provide this method.

  .. _design.mps.protocol.inst.method.describe: inst.html#design.mps.protocol.inst.method.describe

.. c:type:: void (*PoolVarargsMethod)(ArgStruct args[], va_list varargs)

:mps:tag:`method.varargs` The ``varargs`` field decodes the variable
arguments to the deprecated function :c:func:`mps_pool_create()` and
converts them to a list of keyword arguments (see
design.mps.keyword-arguments_).

.. _design.mps.keyword-arguments: keyword-arguments.html

.. c:type:: Res (*PoolInitMethod)(Pool pool, Arena arena, PoolClass klass, ArgList args)

:mps:tag:`method.init` The ``init`` method must call its superclass method
via the :c:func:`NextMethod()` macro (thus calling :c:func:`PoolAbsInit()` which
initializes the generic structure), and then initialize the outer
structure. It is called via the generic function :c:func:`PoolInit()`.

.. c:type:: Res (*PoolAllocMethod)(Addr *pReturn, Pool pool, Size size)

:mps:tag:`method.alloc` The ``alloc`` method manually allocates a block of
at least ``size`` bytes. It should update ``*pReturn`` with a pointer
to a fresh (that is, not overlapping with any other live object)
object of the required size. Failure to allocate must be indicated by
returning an appropriate error code, and in such a case, ``*pReturn``
must not be updated. Pool classes are not required to provide this
method. It is called via the generic function :c:func:`PoolAlloc()`.

:mps:tag:`method.alloc.size.align` A pool class may allow an unaligned
``size`` (rounding it up to the pool's alignment).

.. c:type:: void (*PoolFreeMethod)(Pool pool, Addr old, Size size)

:mps:tag:`method.free` The ``free`` method manually frees a block. The
parameters are required to correspond to a previous allocation request
(possibly via a buffer, not necessarily via :c:func:`PoolAlloc()`). It is an
assertion by the client that the indicated object is no longer
required and the resources associated with it can be recycled. Pool
classes are not required to provide this method. It is called via the
generic function :c:func:`PoolFree()`.

:mps:tag:`method.free.size.align` A pool class may allow an unaligned
``size`` (rounding it up to the pool's alignment).

.. c:type:: BufferClass (*PoolBufferClassMethod)(void)

:mps:tag:`method.bufferClass` The ``bufferClass`` method returns the class
of buffers used by the pool. Pool classes are not required to provide
this method. It is called via the generic function
:c:func:`PoolDefaultBufferClass()`.

.. c:type:: Res (*PoolBufferFillMethod)(Addr *baseReturn, Addr *limitReturn, Pool pool, Buffer buffer, Size size)

:mps:tag:`method.bufferFill` The ``bufferFill`` method should allocate a
region of least ``size`` bytes of memory for attaching to ``buffer``.
The buffer is in the "reset" state (see design.mps.buffer.reset_). If
successful, it must update ``*baseReturn`` and ``*limitReturn`` to the
base and limit of the allocated region and return ``ResOK``. Otherwise
it must leave ``*baseReturn`` and ``*limitReturn`` unchanged and
return a non-OK result code. Pool classes are not required to provide
this method. This method is called by :c:func:`BufferFill()`.

.. _design.mps.buffer.reset: buffer.html#design.mps.buffer.reset

.. c:type:: void (*PoolBufferEmptyMethod)(Pool pool, Buffer buffer)

:mps:tag:`method.bufferEmpty` The ``bufferEmpty`` method indicates that the
client program has finished with the unused part of the buffer (the
part between init and limit). The buffer is in the "ready" state (see
design.mps.buffer.ready_). This method must be provided if and only if
``bufferFill`` is provided. This method is called by the generic
function :c:func:`BufferDetach()`.

.. _design.mps.buffer.ready: buffer.html#design.mps.buffer.ready

.. c:type:: Size (*PoolSizeMethod)(Pool pool)

:mps:tag:`method.totalSize` The ``totalSize`` method must return the total
memory allocated from the arena and managed by the pool. This method
is called by the generic function :c:func:`PoolTotalSize()`.

:mps:tag:`method.freeSize` The ``freeSize`` method must return the free
memory allocated from the arena and managed by the pool, but not in
use by the client program. This method is called by the generic
function :c:func:`PoolFreeSize()`.