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 an 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 finalizable objects)
  43  *      finalizable, and otherwise use GC::soft_ptr<> instead of a regular
  44  *      pointer for "backreferences" (e.g. parent pointers in a tree
  45  *      structure), so that those references can be cleared to break any
  46  *      finalization cycles.
  47  *
  48  *      @see Inkscape::GC::soft_ptr<>
  49  *
  50  *   2. Because there is no guarantee when the collector will destroy
  51  *      objects, it is impossible to tell in advance when the destructor
  52  *      will get called. It may not get called until the very end
  53  *      of the program, or ever.
  54  *
  55  *   3. If allocated in arrays, only the first object in the array will
  56  *      have its destructor called, unless you make other arrangements by
  57  *      registering your own finalizer instead.
  58  *
  59  *   4. Similarly, putting a finalized object as a member in another
  60  *      garbage collected but non-finalized object will cause the member
  61  *      object's destructor not to be called when the parent object is
  62  *      collected, unless you register the finalizer yourself (by "member"
  63  *      we mean an actual by-value member, not a reference or a pointer).
  64  */
  65 class Finalized {
  66 public:
  67     Finalized() {
  68         void *base=Core::base(this);
  69         if (base) { // only if we are managed by the collector
  70             CleanupFunc old_cleanup;
  71             void *old_data;
  72
  73             // the finalization callback needs to know the value of 'this'
  74             // to call the destructor, but registering a real pointer to
  75             // ourselves would pin us forever and prevent us from being
  76             // finalized; instead we use an offset-from-base-address
  77
  78             Core::register_finalizer_ignore_self(base, _invoke_dtor,
  79                                                        _offset(base, this),
  80                                                        &old_cleanup, &old_data);
  81
  82             if (old_cleanup) {
  83                 // If there was already a finalizer registered for our
  84                 // base address, there are two main possibilities:
  85                 //
  86                 // 1. one of our members is also a GC::Finalized and had
  87                 //    already registered a finalizer -- keep ours, since
  88                 //    it will call that member's destructor, too
  89                 //
  90                 // 2. someone else registered a finalizer and we will have
  91                 //    to trust that they will call the destructor -- put
  92                 //    the existing finalizer back
  93                 //
  94                 // It's also possible that a member's constructor was called
  95                 // after ours (e.g. via placement new).  Don't do that.
  96
  97                 if ( old_cleanup != _invoke_dtor ) {
  98                     Core::register_finalizer_ignore_self(base,
  99                                                          old_cleanup, old_data,
 100                                                          NULL, NULL);
 101                 }
 102             }
 103         }
 104     }
 105
 106     virtual ~Finalized() {
 107         // make sure the destructor won't get invoked twice
 108         Core::register_finalizer_ignore_self(Core::base(this),
 109                                              NULL, NULL, NULL, NULL);
 110     }
 111
 112 private:
 113     /// invoke the destructor for an object given a base and offset pair
 114     static void _invoke_dtor(void *base, void *offset);
 115
 116     /// turn 'this' pointer into an offset-from-base-address (stored as void *)
 117     static void *_offset(void *base, Finalized *self) {
 118         return reinterpret_cast<void *>(
 119             reinterpret_cast<char *>(self) - reinterpret_cast<char *>(base)
 120         );
 121     }
 122     /// reconstitute 'this' given an offset-from-base-address in a void *
 123     static Finalized *_unoffset(void *base, void *offset) {
 124         return reinterpret_cast<Finalized *>(
 125             reinterpret_cast<char *>(base) +
 126             reinterpret_cast<std::ptrdiff_t>(offset)
 127         );
 128     }
 129 };
 130
 131 }
 132
 133 }
 134
 135 #endif
 136 /*
 137   Local Variables:
 138   mode:c++
 139   c-file-style:"stroustrup"
 140   c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
 141   indent-tabs-mode:nil
 142   fill-column:99
 143   End:
 144 */
 145 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:fileencoding=utf-8:textwidth=99 :