mirror of
git://git.sv.gnu.org/emacs.git
synced 2026-03-26 08:41:47 -07:00
179 lines
6.5 KiB
ReStructuredText
179 lines
6.5 KiB
ReStructuredText
.. mode: -*- rst -*-
|
|
|
|
Finalization
|
|
============
|
|
|
|
:Tag: design.mps.finalize
|
|
:Author: David Jones
|
|
:Date: 1997-02-14
|
|
:Status: incomplete design
|
|
:Revision: $Id$
|
|
:Copyright: See `Copyright and License`_.
|
|
:Index terms: pair: finalization; design
|
|
|
|
|
|
Overview
|
|
--------
|
|
|
|
_`.overview`: Finalization is implemented internally using the
|
|
Guardian pool class (design.mps.poolmrg_). Objects can be registered
|
|
for finalization using ``mps_finalize()``. Notification of
|
|
finalization is given to the client via the messaging interface. The
|
|
Guardian pool class implements a ``Message`` subclass which implements
|
|
the finalization messages.
|
|
|
|
.. _design.mps.poolmrg: poolmrg
|
|
|
|
|
|
Requirements
|
|
------------
|
|
|
|
_`.req`: Historically only Dylan had requirements for finalization,
|
|
see req.dylan.fun.final. Now (2003-02-19) Configura have requirements
|
|
for finalization. Happily they are very similar.
|
|
|
|
|
|
Architecture
|
|
------------
|
|
|
|
External interface
|
|
..................
|
|
|
|
_`.if.register`: ``mps_finalize()`` increases the number of times that
|
|
an object has been registered for finalization by one. The object must
|
|
have been allocated from the arena (space). Any finalization messages
|
|
that are created for this object will appear on the arena's message
|
|
queue. The MPS will attempt to finalize the object that number of
|
|
times.
|
|
|
|
_`.if.deregister`: ``mps_definalize()`` reduces the number of times that
|
|
the object located at ``obj`` has been registered for finalization by
|
|
one. It is an error to definalize an object that has not been
|
|
registered for finalization.
|
|
|
|
_`.if.deregister.not`: At the moment (1997-08-20) ``mps_definalize()``
|
|
is not implemented.
|
|
|
|
_`.if.get-ref`: ``mps_message_finalization_ref()`` returns the reference
|
|
to the finalized object stored in the finalization message.
|
|
|
|
|
|
Implementation
|
|
--------------
|
|
|
|
_`.int.over`: Registering an object for finalization corresponds to
|
|
allocating a reference of rank FINAL to that object. This reference is
|
|
allocated in a guardian object in a pool of ``PoolClassMRG`` (see
|
|
design.mps.poolmrg_).
|
|
|
|
.. _design.mps.poolmrg: poolmrg
|
|
|
|
_`.int.arena.struct`: The MRG pool used for managing final references
|
|
is kept in the Arena (Space), referred to as the "final pool".
|
|
|
|
_`.int.arena.lazy`: The pool is lazily created. It will not be created
|
|
until the first object is registered for finalization.
|
|
|
|
_`.int.arena.flag`: There is a flag in the Arena that indicates
|
|
whether the final pool has been created yet or not.
|
|
|
|
``Res ArenaFinalize(Arena arena, Ref addr)``
|
|
|
|
_`.int.finalize.create`: Creates the final pool if it has not been
|
|
created yet.
|
|
|
|
_`.int.finalize.alloc`: Allocates a guardian in the final pool.
|
|
|
|
_`.int.finalize.write`: Writes a reference to the object into the
|
|
guardian object.
|
|
|
|
_`.int.finalize.all`: That's all.
|
|
|
|
_`.int.finalize.error`: If either the creation of the pool or the
|
|
allocation of the object fails then the error will be reported back to
|
|
the caller.
|
|
|
|
_`.int.finalize.error.no-unwind`: This function does not need to do
|
|
any unwinding in the error cases because the creation of the pool is
|
|
not something that needs to be undone.
|
|
|
|
_`.int.arena-destroy.empty`: ``ArenaDestroy()`` empties the message
|
|
queue by calling ``MessageEmpty()``.
|
|
|
|
_`.int.arena-destroy.final-pool`: If the final pool has been created
|
|
then ``ArenaDestroy()`` destroys the final pool.
|
|
|
|
_`.access`: ``mps_message_finalization_ref()`` needs to access the
|
|
finalization message to retrieve the reference and then write it to
|
|
where the client asks. This must be done carefully, in order to avoid
|
|
breaking the invariants or creating a hidden root.
|
|
|
|
_`.access.invariants`: We protect the invariants by using special
|
|
routines ``ArenaRead()`` and ``ArenaPoke()`` to read and write the
|
|
reference. This works as long as there's no write-barrier collection.
|
|
|
|
.. note::
|
|
|
|
Instead of ``ArenaPoke()``, we could put in an ``ArenaWrite()``
|
|
that would be identical to ``ArenaPoke()``, except that it would
|
|
``AVER()`` the invariant (or it can just ``AVER()`` that there are
|
|
no busy traces unflipped). When we get write-barrier collection,
|
|
we could change it to do the real thing, but in the absence of a
|
|
write-barrier, it's functionally identical to ``ArenaPoke()``.
|
|
Pekka P. Pirinen, 1997-12-09.
|
|
|
|
|
|
Document History
|
|
----------------
|
|
|
|
- 1997-02-14 David Jones. Incomplete design.
|
|
|
|
- 2002-06-07 RB_ Converted from MMInfo database design document.
|
|
|
|
- 2013-04-13 GDR_ Converted to reStructuredText.
|
|
|
|
.. _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.
|
|
<http://www.ravenbrook.com/>. 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.**
|