summaryrefslogtreecommitdiffstats
path: root/src/gc-finalized.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/gc-finalized.h')
-rw-r--r--src/gc-finalized.h144
1 files changed, 144 insertions, 0 deletions
diff --git a/src/gc-finalized.h b/src/gc-finalized.h
new file mode 100644
index 0000000..6bd702c
--- /dev/null
+++ b/src/gc-finalized.h
@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+/** @file
+ * Inkscape::GC::Finalized - mixin for GC-managed objects with non-trivial
+ * destructors
+ *//*
+ * Authors:
+ * see git history
+ * MenTaLguY <mental@rydia.net>
+ *
+ * Copyright (C) 2004-2018 Authors
+ * Released under GNU GPL v2+, read the file 'COPYING' for more information.
+ */
+
+#ifndef SEEN_INKSCAPE_GC_FINALIZED_H
+#define SEEN_INKSCAPE_GC_FINALIZED_H
+
+#include <new>
+#include <cstddef>
+#include "inkgc/gc-core.h"
+
+namespace Inkscape {
+
+namespace GC {
+
+/* @brief A mix-in ensuring that an object's destructor will get called before
+ * the garbage collector destroys it
+ *
+ * Normally, the garbage collector does not call destructors before destroying
+ * an object. On construction, this "mix-in" will register a finalizer
+ * function to call destructors before derived objects are destroyed.
+ *
+ * This works pretty well, with the following caveats:
+ *
+ * 1. The garbage collector uses strictly topologically-ordered
+ * finalization; if objects with finalizers reference each other
+ * directly or indirectly, the collector will refuse to finalize (and
+ * therefore free) them. You'll see a warning on the console if this
+ * happens.
+ *
+ * The best way to limit this effect is to only make "leaf" objects
+ * (i.e. those that don't point to other finalizable objects)
+ * finalizable, and otherwise use GC::soft_ptr<> instead of a regular
+ * pointer for "backreferences" (e.g. parent pointers in a tree
+ * structure), so that those references can be cleared to break any
+ * finalization cycles.
+ *
+ * @see Inkscape::GC::soft_ptr<>
+ *
+ * 2. Because there is no guarantee when the collector will destroy
+ * objects, it is impossible to tell in advance when the destructor
+ * will get called. It may not get called until the very end
+ * of the program, or ever.
+ *
+ * 3. If allocated in arrays, only the first object in the array will
+ * have its destructor called, unless you make other arrangements by
+ * registering your own finalizer instead.
+ *
+ * 4. Similarly, putting a finalized object as a member in another
+ * garbage collected but non-finalized object will cause the member
+ * object's destructor not to be called when the parent object is
+ * collected, unless you register the finalizer yourself (by "member"
+ * we mean an actual by-value member, not a reference or a pointer).
+ */
+class Finalized {
+public:
+ Finalized() {
+ void *base=Core::base(this);
+ if (base) { // only if we are managed by the collector
+ CleanupFunc old_cleanup;
+ void *old_data;
+
+ // the finalization callback needs to know the value of 'this'
+ // to call the destructor, but registering a real pointer to
+ // ourselves would pin us forever and prevent us from being
+ // finalized; instead we use an offset-from-base-address
+
+ Core::register_finalizer_ignore_self(base, _invoke_dtor,
+ _offset(base, this),
+ &old_cleanup, &old_data);
+
+ if (old_cleanup) {
+ // If there was already a finalizer registered for our
+ // base address, there are two main possibilities:
+ //
+ // 1. one of our members is also a GC::Finalized and had
+ // already registered a finalizer -- keep ours, since
+ // it will call that member's destructor, too
+ //
+ // 2. someone else registered a finalizer and we will have
+ // to trust that they will call the destructor -- put
+ // the existing finalizer back
+ //
+ // It's also possible that a member's constructor was called
+ // after ours (e.g. via placement new). Don't do that.
+
+ if ( old_cleanup != _invoke_dtor ) {
+ Core::register_finalizer_ignore_self(base,
+ old_cleanup, old_data,
+ nullptr, nullptr);
+ }
+ }
+ }
+ }
+
+ virtual ~Finalized() {
+ // make sure the destructor won't get invoked twice
+ Core::register_finalizer_ignore_self(Core::base(this),
+ nullptr, nullptr, nullptr, nullptr);
+ }
+
+private:
+ /// invoke the destructor for an object given a base and offset pair
+ static void _invoke_dtor(void *base, void *offset);
+
+ /// turn 'this' pointer into an offset-from-base-address (stored as void *)
+ static void *_offset(void *base, Finalized *self) {
+ return reinterpret_cast<void *>(
+ reinterpret_cast<char *>(self) - reinterpret_cast<char *>(base)
+ );
+ }
+ /// reconstitute 'this' given an offset-from-base-address in a void *
+ static Finalized *_unoffset(void *base, void *offset) {
+ return reinterpret_cast<Finalized *>(
+ reinterpret_cast<char *>(base) +
+ reinterpret_cast<std::ptrdiff_t>(offset)
+ );
+ }
+};
+
+}
+
+}
+
+#endif
+/*
+ Local Variables:
+ mode:c++
+ c-file-style:"stroustrup"
+ c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
+ indent-tabs-mode:nil
+ fill-column:99
+ End:
+*/
+// vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:fileencoding=utf-8:textwidth=99 :