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 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;
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
86 Core::register_finalizer_ignore_self(base, _invoke_dtor,
87 _offset(base, this),
88 &old_cleanup, &old_data);
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.
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 }
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 }
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 }
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 };
141 }
143 }
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 :