src/gc-finalized.h

   1 /*
   2  * Inkscape::GC::Finalized - mixin for GC-managed objects with non-trivial
   3  *                           destructors
   4  *
   5  * Copyright 2004 MenTaLguY <mental@rydia.net>
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation; either version 2
  10  * of the License, or (at your option) any later version.
  11  *
  12  * See the file COPYING for details.
  13  *
  14  */
  15
  16 #ifndef SEEN_INKSCAPE_GC_FINALIZED_H
  17 #define SEEN_INKSCAPE_GC_FINALIZED_H
  18
  19 #include <new>
  20 #include "gc-core.h"
  21
  22 namespace Inkscape {
  23
  24 namespace GC {
  25
  26 /* @brief a mix-in ensuring that a object's destructor will get called before
  27  *        the garbage collector destroys it
  28  *
  29  * Normally, the garbage collector does not call destructors before destroying
  30  * an object.  On construction, this "mix-in" will register a finalizer
  31  * function to call destructors before derived objects are destroyed.
  32  *
  33  * This works pretty well, with the following caveats:
  34  *
  35  *   1. The garbage collector uses strictly topologically-ordered
  36  *      finalization; if objects with finalizers reference each other
  37  *      directly or indirectly, the collector will refuse to finalize (and
  38  *      therefor free) them.  You'll see a warning on the console if this
  39  *      happens.
  40  *
  41  *      The best way to limit this effect is to only make "leaf" objects
  42  *      (i.e. those that don't point to other finalizaable objects)
  43  *      finalizable, or if the object also derives from GC::Managed<>,
  44  *      use GC::Managed<>::clearOnceInaccessible to register those links
  45  *      to be cleared once the object is made inacecssible (and before it's
  46  *      finalized).
  47  *
  48  *      In a tree structure that has parent links and finalized nodes,
  49  *      you will almost always want to do this with the parent links
  50  *      if you can't avoid having them.
  51  *
  52  *      @see Inkscape::GC::Managed<>::clearOnceInaccessible
  53  *      @see Inkscape::GC::Managed<>::cancelClearOnceInacessible
  54  *
  55  *   2. Because there is no guarantee when the collector will destroy
  56  *      objects, there is no guarantee when the destructor will get called.
  57  *
  58  *      It may not get called until the very end of the program, or never.
  59  *
  60  *   3. If allocated in arrays, only the first object in the array will
  61  *      have its destructor called, unless you make other arrangements by
  62  *      registering your own finalizer instead.
  63  *
  64  *   4. Similarly, making multiple GC::Finalized-derived objects members
  65  *      of a non-finalized but garbage-collected object generally won't
  66  *      work unless you take care of registering finalizers yourself.
  67  *
  68  * [n.b., by "member", I mean an actual by-value-member of a type that
  69  *  derives from GC::Finalized, not simply a member that's a pointer or a
  70  *  reference to such a type]
  71  *
  72  */
  73 class Finalized {
  74 public:
  75     Finalized() {
  76         void *base=Core::base(this);
  77         if (base) { // only if we are managed by the collector
  78             CleanupFunc old_cleanup;
  79             void *old_data;
  80
  81             // the finalization callback needs to know the value of 'this'
  82             // to call the destructor, but registering a real pointer to
  83             // ourselves would pin us forever and prevent us from being
  84             // finalized; instead we use an offset-from-base-address
  85
  86             Core::register_finalizer_ignore_self(base, _invoke_dtor,
  87                                                        _offset(base, this),
  88                                                        &old_cleanup, &old_data);
  89
  90             if (old_cleanup) {
  91                 // If there was already a finalizer registered for our
  92                 // base address, there are two main possibilities:
  93                 //
  94                 // 1. one of our members is also a GC::Finalized and had
  95                 //    already registered a finalizer -- keep ours, since
  96                 //    it will call that member's destructor, too
  97                 //
  98                 // 2. someone else registered a finalizer and we will have
  99                 //    to trust that they will call the destructor -- put
 100                 //    the existing finalizer back
 101                 //
 102                 // It's also possible that a member's constructor was called
 103                 // after ours (e.g. via placement new).  Don't do that.
 104
 105                 if ( old_cleanup != _invoke_dtor ) {
 106                     Core::register_finalizer_ignore_self(base,
 107                                                          old_cleanup, old_data,
 108                                                          NULL, NULL);
 109                 }
 110             }
 111         }
 112     }
 113
 114     virtual ~Finalized() {
 115         // make sure the destructor won't get invoked twice
 116         Core::register_finalizer_ignore_self(Core::base(this),
 117                                              NULL, NULL, NULL, NULL);
 118     }
 119
 120 private:
 121     /// invoke the destructor for an object given a base and offset pair
 122     static void _invoke_dtor(void *base, void *offset) {
 123         _unoffset(base, offset)->~Finalized();
 124     }
 125
 126     /// turn 'this' pointer into an offset-from-base-address (stored as void *)
 127     static void *_offset(void *base, Finalized *self) {
 128         return reinterpret_cast<void *>(
 129             reinterpret_cast<char *>(self) - reinterpret_cast<char *>(base)
 130         );
 131     }
 132     /// reconstitute 'this' given an offset-from-base-address in a void *
 133     static Finalized *_unoffset(void *base, void *offset) {
 134         return reinterpret_cast<Finalized *>(
 135             reinterpret_cast<char *>(base) +
 136             reinterpret_cast<std::ptrdiff_t>(offset)
 137         );
 138     }
 139 };
 140
 141 }
 142
 143 }
 144
 145 #endif
 146 /*
 147   Local Variables:
 148   mode:c++
 149   c-file-style:"stroustrup"
 150   c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
 151   indent-tabs-mode:nil
 152   fill-column:99
 153   End:
 154 */
 155 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :