From 1274e4aaf6c015d4bbf8a16859b6573b86b4ea06 Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Wed, 19 Oct 2016 15:35:22 +0100 Subject: [PATCH] Remove design.mps.class-interface, merged into design.mps.pool. Copied from Perforce Change: 192643 ServerID: perforce.ravenbrook.com --- mps/design/class-interface.txt | 304 --------------------------------- 1 file changed, 304 deletions(-) delete mode 100644 mps/design/class-interface.txt diff --git a/mps/design/class-interface.txt b/mps/design/class-interface.txt deleted file mode 100644 index 00925e51019..00000000000 --- a/mps/design/class-interface.txt +++ /dev/null @@ -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`` 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 . -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.**