.. mode: -*- rst -*-

Pool class interface
====================

:Tag: design.mps.class-interface
:Author: Richard Brooksby
:Date: 1997-08-19
:Status: incomplete design
:Revision: $Id: //info.ravenbrook.com/project/mps/version/1.116/design/class-interface.txt#1 $
:Copyright: See `Copyright and License`_.
:Index terms:    pair: class interface; design


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

_`.intro`: This document describes the interface and protocols between
the MPM and the pool class implementations.

.. note::

    This document should be merged into design.mps.pool_. Pekka P.
    Pirinen, 1999-07-20.

    .. _design.mps.pool: pool


Fields
------

_`.field`: These fields are provided by pool classes as part of the
``PoolClass`` object (see impl.h.mpmst.class). They form part of the
interface which allows the MPM to treat pools in a uniform manner.

_`.field.name`: The ``name`` field should be a short, pithy, cryptic
name for the pool class. It should typically start with ``"A"`` if
memory is managed by the garbage collector, and ``"M"`` if memory is
managed by alloc/free. Examples are "AMC", "MV".

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

.. _design.mps.type.attr: type

_`.field.size`: The ``size`` field is the size of the pool instance
structure. For the ``PoolFoo`` class this can reasonably be expected
to be ``sizeof(PoolFooStruct)``.

_`.field.offset`: The ``offset`` field is the offset into the pool
instance structure of the generic ``PoolStruct``. Typically this field
is called ``poolStruct``, so something like ``offsetof(PoolFooStruct,
poolStruct)`` is typical. If possible, arrange for this to be zero.


Methods
-------

_`.method`: These methods are provided by pool classes as part of the
``PoolClass`` object (see impl.h.mpmst.class). They form part of the
interface which allows the MPM to treat pools in a uniform manner.

_`.method.unused`: If a pool class is not required to provide a
certain method, the class should assign the appropriate ``PoolNo``
method for that method to ensure that erroneous calls are detected. It
is not acceptable to use ``NULL``.

_`.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.

_`.method.init`: The ``init`` field is the pool class's init method.
This method is called via the generic function ``PoolInit()``, which
is in turn called by ``PoolCreate()``. The generic function allocates
the pool's structure (using the ``size`` and ``offset`` fields),
initializes the ``PoolStruct`` (generic part), then calls the ``init``
method to do any class-specific initialization. Typically this means
initializing the fields in the pool instance structure. If ``init``
returns a non-OK result code the instance structure will be
deallocated and the code returned to the caller of ``PoolInit()`` or
``PoolCreate()``. Note that the ``PoolStruct`` isn't made fully valid
until ``PoolInit()`` returns, so the ``init`` method must not call
``PoolCheck()``.

_`.method.finish`: The ``finish`` field is the pool class's finish
method. This method is called via the generic function
``PoolFinish()``, which is in turn called by ``PoolDestroy()``. It is
expected to finalise the pool instance structure, release any
resources allocated to the pool, and release the memory associated
with the pool instance structure. Note that the pool is valid when it
is passed to ``finish``. The ``PoolStruct`` (generic part) is finished
when the pool class's ``finish`` method returns.

_`.method.alloc`: The ``alloc`` field is the pool class's allocation
method. This method is called via the generic function
``PoolAlloc()``. It is expected to return a pointer to a fresh (that
is, not overlapping with any other live object) object of the required
size. Failure to allocate should be indicated by returning an
appropriate error code, and in such a case, ``*pReturn`` should not be
updated. Pool classes are not required to provide this method.

_`.method.free`: The ``free`` method is the pool class's free method.
This is intended primarily for manual style pools. This method is
called via the generic function ``PoolFree()``. The parameters are
required to correspond to a previous allocation request (possibly via
a buffer). 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.

_`.method.bufferInit`: The ``bufferInit`` method is the pool class's
buffer initialization method. It is called by the generic function
``BufferCreate()``, which allocates the buffer descriptor and
initializes the generic fields. The pool may optionally adjust these
fields or fill in extra values. If ``bufferInit`` returns a result
code other than ``ResOK``, the buffer structure is deallocated and the
result code is returned to the caller of ``BufferCreate()``. Note that
the ``BufferStruct`` isn't fully valid until ``BufferCreate()``
returns. Pool classes are not required to provide this method.

_`.method.bufferFinish`: The ``bufferFinish`` method is the pool
class's buffer finishing method. It is called by the the generic
function ``BufferDestroy()``. The pool is expected to detach the
buffer from any memory and prepare the buffer for destruction. The
pool is expected to release the resources associated with the buffer
structure, and any unreserved memory in the buffer may be recycled. It
is illegal for a buffer to be destroyed when there are pending
allocations on it (that is, an allocation has been reserved, but not
committed) and this is checked in the generic function. This method
must be provided if and only if ``bufferInit`` is provided.

_`.method.access`: The ``access`` method is used to handle client
access. This method is called via the generic functions
``ArenaAccess()`` and ``PoolAccess()``. It indicates that the client
has attempted to access the specified region, but has been denied and
the request trapped due to a protection state. The pool should perform
any work necessary to remove the protection whilst still preserving
appropriate invariants (typically this will be scanning work). Pool
classes are not required to provide this method, and not doing so
indicates they never protect any memory managed by the pool.

_`.method.whiten`: The ``whiten`` method is used to condemn a segment
belonging to a pool. This method is called via the generic function
``PoolWhiten()``. The pool is expected to condemn a subset (but
typically all) of the objects in the segment and prepare the segment
for participation in a global trace to determine liveness. The pool
should expect fix requests (via the ``fix`` method below) during a
global trace. Pool classes that automatically reclaim dead objects
must provide this method, and must additionally set the ``AttrGC``
attribute.

_`.method.grey`: The ``grey`` method is used to greyen a segment
belonging to a pool. This method is called via the generic function
``PoolGrey()``. The pool should set all of the objects in the segment
(excepting any set that has been condemned in this trace) to be grey,
that is, ready for scanning. The pool should arrange that any
appropriate invariants are preserved, possibly by using the protection
interface (see design.mps.prot_). Pool classes are not required to
provide this method, and not doing so indicates that all instances of
this class will have no fixable or traceable references in them.

.. _design.mps.prot: prot

_`.method.blacken`: The ``blacken`` method is used to blacken a
segment belonging to a pool. This method is called via the generic
function ``PoolBlacken()`` when it is known that the segment cannot
refer to the white set. The pool must blacken all grey objects in the
segment. Pool classes are not required to provide this method, and not
doing so indicates that all instances of this class will have no
fixable or traceable references in them.

_`.method.scan`: The ``scan`` method is used to scan a segment. This
method is called via the generic function ``PoolScan()``. The pool
must scan all the known grey objects on the segment and it may also
accumulate a summary of *all* the objects on the segment. If it
succeeds in accumulating such a summary it must indicate that it has
done so by setting the ``totalReturn`` parameter to ``TRUE``. Pool
classes are not required to provide this method, and not doing so
indicates that all instances of this class will have no fixable or
traceable reference in them.

_`.method.fix`: The ``fix`` method is used to perform fixing. This
method is called via the generic function ``TraceFix()``. It indicates
that the specified reference has been found and the pool should
consider the object to be live. There is provision for adjusting the
value of the reference (to allow for classes that move objects). not
required to provide this method. Pool classes that automatically
reclaim dead objects must provide this method, and must additionally
set the ``AttrGC`` attribute. Pool classes that may move objects must
also set the ``AttrMOVINGGC`` attribute.

_`.method.fixEmergency`: The ``fixEmergency`` method is used to
perform fixing in "emergency" situations. It must complete its work
without allocating memory (perhaps by using some approximation, or by
running more slowly). Pool classes must provide this method if they
provide the ``fix`` method.

_`.method.reclaim`: The ``reclaim`` method is used to reclaim memory
in a segment. This method is called via the generic function
``PoolReclaim()``. It indicates that any remaining white objects in
the segment have now been proved unreachable, hence are dead. The pool
should reclaim the resources associated with the dead objects. Pool
classes are not required to provide this method. If they do, they must
set the ``AttrGC`` attribute.

_`.method.walk`: The ``walk`` method is used by the heap walker. The
``walk`` method should apply the visitor function (along with its
closure parameter and the object format) to all *black* objects in
the segment. Padding objects may or may not be included in the walk at
the classes discretion, in any case in will be the responsibility of
the client to do something sensible with padding objects. Forwarding
objects are never included in the walk. Pool classes need not provide
this method. If they do, they must set the ``AttrFMT`` attribute.

_`.method.describe`: The ``describe`` field is used to print out a
description of a pool. This method is called via the generic function
``PoolDescribe()``. The class should emit an textual description of
the pool's contents onto the specified stream. Each line should begin
with two spaces. Classes are not required to provide this method.


Events
------

_`.replay`: To work with the allocation replayer (see
design.mps.telemetry.replayer_), the pool has to emit an event for each
call to an external interface, containing all the parameters passed by
the user. If a new event type is required to carry this information,
the replayer (impl.c.eventrep) must then be extended to recreate the
call.

.. _design.mps.telemetry.replayer: telemetry#replayer

_`.replay.Init`: In particular, the ``init`` method should emit a
``PoolInit<foo>`` event with all the pool parameters.


Text
-----

_`.alloc.size`: The pool class implementation defines the meaning of
the "size" parameter to the ``alloc`` and ``free`` methods. It may not
actually correspond to a number of bytes of memory.

_`.alloc.size.align`: In particular, the class may allow an unaligned
size to be passed.


Document history
----------------

- 1997-08-19 RB_ Initial draft. David Jones added comments about how
  accurate this document is.

- 2002-06-07 RB_ Converted from MMInfo database design document.

- 2013-03-12 GDR_ Converted to reStructuredText.

- 2014-06-08 GDR_ Bring method descriptions up to date.

.. _RB: http://www.ravenbrook.com/consultants/rb/
.. _GDR: http://www.ravenbrook.com/consultants/gdr/


Copyright and License
---------------------

Copyright © 2013-2014 Ravenbrook Limited <http://www.ravenbrook.com/>.
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:

#. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

#. 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.

#. 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.**