Initial revision
This commit is contained in:
Akinori Ito
221
gc/include/weakpointer.h
Normal file
221
gc/include/weakpointer.h
Normal file
@@ -0,0 +1,221 @@
|
||||
#ifndef _weakpointer_h_
|
||||
#define _weakpointer_h_
|
||||
|
||||
/****************************************************************************
|
||||
|
||||
WeakPointer and CleanUp
|
||||
|
||||
Copyright (c) 1991 by Xerox Corporation. All rights reserved.
|
||||
|
||||
THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
|
||||
OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
|
||||
|
||||
Permission is hereby granted to copy this code for any purpose,
|
||||
provided the above notices are retained on all copies.
|
||||
|
||||
Last modified on Mon Jul 17 18:16:01 PDT 1995 by ellis
|
||||
|
||||
****************************************************************************/
|
||||
|
||||
/****************************************************************************
|
||||
|
||||
WeakPointer
|
||||
|
||||
A weak pointer is a pointer to a heap-allocated object that doesn't
|
||||
prevent the object from being garbage collected. Weak pointers can be
|
||||
used to track which objects haven't yet been reclaimed by the
|
||||
collector. A weak pointer is deactivated when the collector discovers
|
||||
its referent object is unreachable by normal pointers (reachability
|
||||
and deactivation are defined more precisely below). A deactivated weak
|
||||
pointer remains deactivated forever.
|
||||
|
||||
****************************************************************************/
|
||||
|
||||
|
||||
template< class T > class WeakPointer {
|
||||
public:
|
||||
|
||||
WeakPointer( T* t = 0 )
|
||||
/* Constructs a weak pointer for *t. t may be null. It is an error
|
||||
if t is non-null and *t is not a collected object. */
|
||||
{impl = _WeakPointer_New( t );}
|
||||
|
||||
T* Pointer()
|
||||
/* wp.Pointer() returns a pointer to the referent object of wp or
|
||||
null if wp has been deactivated (because its referent object
|
||||
has been discovered unreachable by the collector). */
|
||||
{return (T*) _WeakPointer_Pointer( this->impl );}
|
||||
|
||||
int operator==( WeakPointer< T > wp2 )
|
||||
/* Given weak pointers wp1 and wp2, if wp1 == wp2, then wp1 and
|
||||
wp2 refer to the same object. If wp1 != wp2, then either wp1
|
||||
and wp2 don't refer to the same object, or if they do, one or
|
||||
both of them has been deactivated. (Note: If objects t1 and t2
|
||||
are never made reachable by their clean-up functions, then
|
||||
WeakPointer<T>(t1) == WeakPointer<T>(t2) if and only t1 == t2.) */
|
||||
{return _WeakPointer_Equal( this->impl, wp2.impl );}
|
||||
|
||||
int Hash()
|
||||
/* Returns a hash code suitable for use by multiplicative- and
|
||||
division-based hash tables. If wp1 == wp2, then wp1.Hash() ==
|
||||
wp2.Hash(). */
|
||||
{return _WeakPointer_Hash( this->impl );}
|
||||
|
||||
private:
|
||||
void* impl;
|
||||
};
|
||||
|
||||
/*****************************************************************************
|
||||
|
||||
CleanUp
|
||||
|
||||
A garbage-collected object can have an associated clean-up function
|
||||
that will be invoked some time after the collector discovers the
|
||||
object is unreachable via normal pointers. Clean-up functions can be
|
||||
used to release resources such as open-file handles or window handles
|
||||
when their containing objects become unreachable. If a C++ object has
|
||||
a non-empty explicit destructor (i.e. it contains programmer-written
|
||||
code), the destructor will be automatically registered as the object's
|
||||
initial clean-up function.
|
||||
|
||||
There is no guarantee that the collector will detect every unreachable
|
||||
object (though it will find almost all of them). Clients should not
|
||||
rely on clean-up to cause some action to occur immediately -- clean-up
|
||||
is only a mechanism for improving resource usage.
|
||||
|
||||
Every object with a clean-up function also has a clean-up queue. When
|
||||
the collector finds the object is unreachable, it enqueues it on its
|
||||
queue. The clean-up function is applied when the object is removed
|
||||
from the queue. By default, objects are enqueued on the garbage
|
||||
collector's queue, and the collector removes all objects from its
|
||||
queue after each collection. If a client supplies another queue for
|
||||
objects, it is his responsibility to remove objects (and cause their
|
||||
functions to be called) by polling it periodically.
|
||||
|
||||
Clean-up queues allow clean-up functions accessing global data to
|
||||
synchronize with the main program. Garbage collection can occur at any
|
||||
time, and clean-ups invoked by the collector might access data in an
|
||||
inconsistent state. A client can control this by defining an explicit
|
||||
queue for objects and polling it at safe points.
|
||||
|
||||
The following definitions are used by the specification below:
|
||||
|
||||
Given a pointer t to a collected object, the base object BO(t) is the
|
||||
value returned by new when it created the object. (Because of multiple
|
||||
inheritance, t and BO(t) may not be the same address.)
|
||||
|
||||
A weak pointer wp references an object *t if BO(wp.Pointer()) ==
|
||||
BO(t).
|
||||
|
||||
***************************************************************************/
|
||||
|
||||
template< class T, class Data > class CleanUp {
|
||||
public:
|
||||
|
||||
static void Set( T* t, void c( Data* d, T* t ), Data* d = 0 )
|
||||
/* Sets the clean-up function of object BO(t) to be <c, d>,
|
||||
replacing any previously defined clean-up function for BO(t); c
|
||||
and d can be null, but t cannot. Sets the clean-up queue for
|
||||
BO(t) to be the collector's queue. When t is removed from its
|
||||
clean-up queue, its clean-up will be applied by calling c(d,
|
||||
t). It is an error if *t is not a collected object. */
|
||||
{_CleanUp_Set( t, c, d );}
|
||||
|
||||
static void Call( T* t )
|
||||
/* Sets the new clean-up function for BO(t) to be null and, if the
|
||||
old one is non-null, calls it immediately, even if BO(t) is
|
||||
still reachable. Deactivates any weak pointers to BO(t). */
|
||||
{_CleanUp_Call( t );}
|
||||
|
||||
class Queue {public:
|
||||
Queue()
|
||||
/* Constructs a new queue. */
|
||||
{this->head = _CleanUp_Queue_NewHead();}
|
||||
|
||||
void Set( T* t )
|
||||
/* q.Set(t) sets the clean-up queue of BO(t) to be q. */
|
||||
{_CleanUp_Queue_Set( this->head, t );}
|
||||
|
||||
int Call()
|
||||
/* If q is non-empty, q.Call() removes the first object and
|
||||
calls its clean-up function; does nothing if q is
|
||||
empty. Returns true if there are more objects in the
|
||||
queue. */
|
||||
{return _CleanUp_Queue_Call( this->head );}
|
||||
|
||||
private:
|
||||
void* head;
|
||||
};
|
||||
};
|
||||
|
||||
/**********************************************************************
|
||||
|
||||
Reachability and Clean-up
|
||||
|
||||
An object O is reachable if it can be reached via a non-empty path of
|
||||
normal pointers from the registers, stacks, global variables, or an
|
||||
object with a non-null clean-up function (including O itself),
|
||||
ignoring pointers from an object to itself.
|
||||
|
||||
This definition of reachability ensures that if object B is accessible
|
||||
from object A (and not vice versa) and if both A and B have clean-up
|
||||
functions, then A will always be cleaned up before B. Note that as
|
||||
long as an object with a clean-up function is contained in a cycle of
|
||||
pointers, it will always be reachable and will never be cleaned up or
|
||||
collected.
|
||||
|
||||
When the collector finds an unreachable object with a null clean-up
|
||||
function, it atomically deactivates all weak pointers referencing the
|
||||
object and recycles its storage. If object B is accessible from object
|
||||
A via a path of normal pointers, A will be discovered unreachable no
|
||||
later than B, and a weak pointer to A will be deactivated no later
|
||||
than a weak pointer to B.
|
||||
|
||||
When the collector finds an unreachable object with a non-null
|
||||
clean-up function, the collector atomically deactivates all weak
|
||||
pointers referencing the object, redefines its clean-up function to be
|
||||
null, and enqueues it on its clean-up queue. The object then becomes
|
||||
reachable again and remains reachable at least until its clean-up
|
||||
function executes.
|
||||
|
||||
The clean-up function is assured that its argument is the only
|
||||
accessible pointer to the object. Nothing prevents the function from
|
||||
redefining the object's clean-up function or making the object
|
||||
reachable again (for example, by storing the pointer in a global
|
||||
variable).
|
||||
|
||||
If the clean-up function does not make its object reachable again and
|
||||
does not redefine its clean-up function, then the object will be
|
||||
collected by a subsequent collection (because the object remains
|
||||
unreachable and now has a null clean-up function). If the clean-up
|
||||
function does make its object reachable again and a clean-up function
|
||||
is subsequently redefined for the object, then the new clean-up
|
||||
function will be invoked the next time the collector finds the object
|
||||
unreachable.
|
||||
|
||||
Note that a destructor for a collected object cannot safely redefine a
|
||||
clean-up function for its object, since after the destructor executes,
|
||||
the object has been destroyed into "raw memory". (In most
|
||||
implementations, destroying an object mutates its vtbl.)
|
||||
|
||||
Finally, note that calling delete t on a collected object first
|
||||
deactivates any weak pointers to t and then invokes its clean-up
|
||||
function (destructor).
|
||||
|
||||
**********************************************************************/
|
||||
|
||||
extern "C" {
|
||||
void* _WeakPointer_New( void* t );
|
||||
void* _WeakPointer_Pointer( void* wp );
|
||||
int _WeakPointer_Equal( void* wp1, void* wp2 );
|
||||
int _WeakPointer_Hash( void* wp );
|
||||
void _CleanUp_Set( void* t, void (*c)( void* d, void* t ), void* d );
|
||||
void _CleanUp_Call( void* t );
|
||||
void* _CleanUp_Queue_NewHead ();
|
||||
void _CleanUp_Queue_Set( void* h, void* t );
|
||||
int _CleanUp_Queue_Call( void* h );
|
||||
}
|
||||
|
||||
#endif /* _weakpointer_h_ */
|
||||
|
||||
|
||||
Reference in New Issue
Block a user