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 };
131 }
133 }
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 :