Code

Patch to fix build on Natty by Alex Valavanis
[inkscape.git] / 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  */
16 #ifndef SEEN_INKSCAPE_GC_FINALIZED_H
17 #define SEEN_INKSCAPE_GC_FINALIZED_H
19 #include <new>
20 #include "gc-core.h"
22 namespace Inkscape {
24 namespace GC {
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;
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
78             Core::register_finalizer_ignore_self(base, _invoke_dtor,
79                                                        _offset(base, this),
80                                                        &old_cleanup, &old_data);
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.
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     }
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     }
112 private:
113     /// invoke the destructor for an object given a base and offset pair
114     static void _invoke_dtor(void *base, void *offset);
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 };
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:encoding=utf-8:textwidth=99 :