home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / sa104os2.zip / SATHR104.ZIP / SATHER / SYSTEM / GC / GC_CPP.H < prev    next >
C/C++ Source or Header  |  1994-12-12  |  9KB  |  268 lines
  1. #ifndef GC_CPP_H
  2. #define GC_CPP_H
  3. /****************************************************************************
  4. Copyright (c) 1994 by Xerox Corporation.  All rights reserved.
  5.  
  6. THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
  7. OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.
  8.  
  9. Permission is hereby granted to use or copy this program for any
  10. purpose, provided the above notices are retained on all copies.
  11. Permission to modify the code and to distribute modified code is
  12. granted, provided the above notices are retained, and a notice that
  13. the code was modified is included with the above copyright notice.
  14. ****************************************************************************
  15.  
  16. C++ Interface to the Boehm Collector
  17.  
  18.     John R. Ellis and Jesse Hull 
  19.     Last modified on Thu Dec  8 12:41:07 PST 1994 by ellis
  20.  
  21. This interface provides access to the Boehm collector.  It provides
  22. basic facilities similar to those described in "Safe, Efficient
  23. Garbage Collection for C++", by John R. Elis and David L. Detlefs
  24. (ftp.parc.xerox.com:/pub/ellis/gc).
  25.  
  26. All heap-allocated objects are either "collectable" or
  27. "uncollectable".  Programs must explicitly delete uncollectable
  28. objects, whereas the garbage collector will automatically delete
  29. collectable objects when it discovers them to be inaccessible.
  30. Collectable objects may freely point at uncollectable objects and vice
  31. versa.
  32.  
  33. Objects allocated with the built-in "::operator new" are uncollectable.
  34.  
  35. Objects derived from class "gc" are collectable.  For example:
  36.  
  37.     class A: gc {...};
  38.     A* a = new A;       // a is collectable. 
  39.  
  40. Collectable instances of non-class types can be allocated using the GC
  41. placement:
  42.  
  43.     typedef int A[ 10 ];
  44.     A* a = new (GC) A;
  45.  
  46. Uncollectable instances of classes derived from "gc" can be allocated
  47. using the NoGC placement:
  48.  
  49.     class A: gc {...};
  50.     A* a = new (NoGC) A;   // a is uncollectable.
  51.  
  52. Both uncollectable and collectable objects can be explicitly deleted
  53. with "delete", which invokes an object's destructors and frees its
  54. storage immediately.
  55.  
  56. A collectable object may have a clean-up function, which will be
  57. invoked when the collector discovers the object to be inaccessible.
  58. An object derived from "gc_cleanup" or containing a member derived
  59. from "gc_cleanup" has a default clean-up function that invokes the
  60. object's destructors.  Explicit clean-up functions may be specified as
  61. an additional placement argument:
  62.  
  63.     A* a = ::new (GC, MyCleanup) A;
  64.  
  65. An object is considered "accessible" by the collector if it can be
  66. reached by a path of pointers from static variables, automatic
  67. variables of active functions, or from some object with clean-up
  68. enabled; pointers from an object to itself are ignored.
  69.  
  70. Thus, if objects A and B both have clean-up functions, and A points at
  71. B, B is considered accessible.  After A's clean-up is invoked and its
  72. storage released, B will then become inaccessible and will have its
  73. clean-up invoked.  If A points at B and B points to A, forming a
  74. cycle, then that's considered a storage leak, and neither will be
  75. collectable.  See the interface gc.h for low-level facilities for
  76. handling such cycles of objects with clean-up.
  77.  
  78. The collector cannot guarrantee that it will find all inaccessible
  79. objects.  In practice, it finds almost all of them.
  80.  
  81.  
  82. Cautions:
  83.  
  84. 1. Be sure the collector has been augmented with "make c++".
  85.  
  86. 2.  If your compiler supports the new "operator new[]" syntax, then
  87. add -DOPERATOR_NEW_ARRAY to the Makefile.
  88.  
  89. If your compiler doesn't support "operator new[]", beware that an
  90. array of type T, where T is derived from "gc", will by default be
  91. allocated as an uncollectable object.  Use the explicit GC placement
  92. to make the array collectable.  For example:
  93.  
  94.     class A: gc {...};
  95.     A* a1 = new A[ 10 ];        // uncollectable
  96.     A* a2 = new (GC) A[ 10 ];   // collectable
  97.  
  98. 3. Arrays of objects derived from "gc_cleanup" do not have default
  99. clean-up functions.  For example:
  100.  
  101.     class A: gc_cleanup {...};
  102.     A* a = new (GC) A[ 10 ];
  103.  
  104. The elements of "a" will not have their destructors invoked when the
  105. collector frees "a".  You must supply an explicit clean-up function
  106. for that to occur.
  107.  
  108. 4. Compiler bugs:
  109.  
  110.     Solaris 2's CC (SC3.0) doesn't implement t->~T() correctly, so the
  111.     destructors of classes derived from gc_cleanup won't be invoked.
  112.     You'll have to explicitly register a clean-up function with
  113.     new-placement syntax.
  114.  
  115.     Evidently cfront 3.0 does not allow destructors to be explicitly
  116.     invoked using the ANSI-conforming syntax t->~T().  If you're using
  117.     cfront 3.0, you'll have to comment out the class gc_cleanup, which
  118.     uses explicit invocation.
  119.  
  120. ****************************************************************************/
  121.  
  122. #include "gc.h"
  123.  
  124. #ifndef THINK_CPLUS
  125. #define _cdecl
  126. #endif
  127.  
  128. enum GCPlacement {GC, NoGC};
  129.  
  130. class gc {public:
  131.     inline void* operator new( size_t size );
  132.     inline void* operator new( size_t size, GCPlacement gcp );
  133.     inline void operator delete( void* obj );
  134.  
  135. #ifdef OPERATOR_NEW_ARRAY
  136.     inline void* operator new[]( size_t size );
  137.     inline void* operator new[]( size_t size, GCPlacement gcp );
  138.     inline void operator delete[]( void* obj );
  139. #endif /* OPERATOR_NEW_ARRAY */
  140.     };    
  141.     /*
  142.     Instances of classes derived from "gc" will be allocated in the 
  143.     collected heap by default, unless an explicit NoGC placement is
  144.     specified. */
  145.  
  146. class gc_cleanup: virtual public gc {public:
  147.     inline gc_cleanup();
  148.     inline virtual ~gc_cleanup();
  149. private:
  150.     inline static void _cdecl cleanup( void* obj, void* clientData );};
  151.     /*
  152.     Instances of classes derived from "gc_cleanup" will be allocated
  153.     in the collected heap by default.  When the collector discovers an
  154.     inaccessible object derived from "gc_cleanup" or containing a
  155.     member derived from "gc_cleanup", its destructors will be
  156.     invoked. */
  157.  
  158. extern "C" {typedef void (*GCCleanUpFunc)( void* obj, void* clientData );}
  159.  
  160. inline void* operator new( 
  161.     size_t size, 
  162.     GCPlacement gcp,
  163.     GCCleanUpFunc cleanup = 0,
  164.     void* clientData = 0 );
  165.     /*
  166.     Allocates a collectable or uncollected object, according to the
  167.     value of "gcp".
  168.  
  169.     For collectable objects, if "cleanup" is non-null, then when the
  170.     allocated object "obj" becomes inaccessible, the collector will
  171.     invoke the function "cleanup( obj, clientData )" but will not
  172.     invoke the object's destructors.  It is an error to explicitly
  173.     delete an object allocated with a non-null "cleanup".
  174.  
  175.     It is an error to specify a non-null "cleanup" with NoGC or for
  176.     classes derived from "gc_cleanup" or containing members derived
  177.     from "gc_cleanup". */
  178.  
  179. #ifdef OPERATOR_NEW_ARRAY
  180.  
  181. inline void* operator new[](
  182.     size_t size, 
  183.     GCPlacement gcp,
  184.     GCCleanUpFunc cleanup = 0,
  185.     void* clientData = 0 );
  186.     /*
  187.     The operator new for arrays, identical to the above. */
  188.  
  189. #endif /* OPERATOR_NEW_ARRAY */
  190.  
  191. /****************************************************************************
  192.  
  193. Inline implementation
  194.  
  195. ****************************************************************************/
  196.  
  197. inline void* gc::operator new( size_t size ) {
  198.     return GC_MALLOC( size );}
  199.     
  200. inline void* gc::operator new( size_t size, GCPlacement gcp ) {
  201.     if (gcp == GC) 
  202.         return GC_MALLOC( size );
  203.     else
  204.         return GC_MALLOC_UNCOLLECTABLE( size );}
  205.  
  206. inline void gc::operator delete( void* obj ) {
  207.     GC_FREE( obj );}
  208.     
  209.  
  210. #ifdef OPERATOR_NEW_ARRAY
  211.  
  212. inline void* gc::operator new[]( size_t size ) {
  213.     return gc::operator new( size );}
  214.     
  215. inline void* gc::operator new[]( size_t size, GCPlacement gcp ) {
  216.     return gc::operator new( size, gcp );}
  217.  
  218. inline void gc::operator delete[]( void* obj ) {
  219.     gc::operator delete( obj );}
  220.     
  221. #endif /* OPERATOR_NEW_ARRAY */
  222.  
  223.  
  224. inline gc_cleanup::~gc_cleanup() {
  225.     GC_REGISTER_FINALIZER_IGNORE_SELF( this, 0, 0, 0, 0 );}
  226.  
  227. inline void gc_cleanup::cleanup( void* obj, void* displ ) {
  228.     ((gc_cleanup*) ((char*) obj + (ptrdiff_t) displ))->~gc_cleanup();}
  229.  
  230. inline gc_cleanup::gc_cleanup() {
  231.     register void *base = GC_base( (void *) this );
  232.     GC_REGISTER_FINALIZER_IGNORE_SELF( 
  233.         base, cleanup, (void*) ((char*) this - (char*) base), 0, 0 );}
  234.  
  235. inline void* operator new( 
  236.     size_t size, 
  237.     GCPlacement gcp,
  238.     GCCleanUpFunc cleanup,
  239.     void* clientData )
  240. {
  241.     void* obj;
  242.  
  243.     if (gcp == GC) {
  244.         obj = GC_MALLOC( size );
  245.         if (cleanup != 0) 
  246.             GC_REGISTER_FINALIZER_IGNORE_SELF( 
  247.                 obj, cleanup, clientData, 0, 0 );}
  248.     else {
  249.         obj = GC_MALLOC_UNCOLLECTABLE( size );};
  250.     return obj;}
  251.         
  252.  
  253. #ifdef OPERATOR_NEW_ARRAY
  254.  
  255. inline void* operator new[]( 
  256.     size_t size, 
  257.     GCPlacement gcp,
  258.     GCCleanUpFunc cleanup,
  259.     void* clientData )
  260. {
  261.     return ::operator new( size, gcp, cleanup, clientData );}
  262.  
  263. #endif /* OPERATOR_NEW_ARRAY */
  264.  
  265.  
  266. #endif /* GC_CPP_H */
  267.  
  268.