mirror of
git://git.sv.gnu.org/emacs.git
synced 2026-02-24 13:57:36 +00:00
Remove design.mps.class-interface, merged into design.mps.pool.
Copied from Perforce Change: 192643 ServerID: perforce.ravenbrook.com
This commit is contained in:
Gareth Rees
parent
0f4564a71b
commit
1274e4aaf6
1 changed files with 0 additions and 304 deletions
|
|
@ -1,304 +0,0 @@
|
|||
.. mode: -*- rst -*-
|
||||
|
||||
Pool class interface
|
||||
====================
|
||||
|
||||
:Tag: design.mps.class-interface
|
||||
:Author: Richard Brooksby
|
||||
:Date: 1997-08-19
|
||||
:Status: incomplete design
|
||||
:Revision: $Id$
|
||||
: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.**
|
||||
Loading…
Reference in a new issue