diff options
Diffstat (limited to 'boehm-gc/include/weakpointer.h')
| -rw-r--r-- | boehm-gc/include/weakpointer.h | 221 |
1 files changed, 0 insertions, 221 deletions
diff --git a/boehm-gc/include/weakpointer.h b/boehm-gc/include/weakpointer.h deleted file mode 100644 index 84906b00a68..00000000000 --- a/boehm-gc/include/weakpointer.h +++ /dev/null @@ -1,221 +0,0 @@ -#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_ */ - - |