Leaky Documents

Making slow but steady progress on the documentation and auditing for the 2.10 API. Hopefully I'll finish up the Printing API next week. I've been refining some of the tools we use to add boilerplate-ish documentation for things like default signal handler virtual methods, and some of the semi-internal API the binding has to expose for binding purposes.

Since writing documentation doesn't make me feel sexy, I've been mixing in some bugfixing and new development along the way. Today I spent some time hacking toggle ref support into GLib.Object. Toggle refs are a new ref type added in glib-2.8. They are a special ref type which provides notification when transitioning from sole-ownership to shared-ownership of an object.

It's important to account for this with managed subclasses because we have to hold a strong reference to the managed object as long as native-owned refs exist. If Gtk# is the sole owner of a native object, we can allow the managed reference handling to drive garbage collection. However, when any native code takes a native ref on a managed subclass, we need to artificially maintain a managed ref to the object until the native code releases its ref.

Since we maintain a GObject* keyed hashtable of outstanding GLib.Object instances, we can use the toggle ref notification to switch between weak and strong references in the hash. While we have shared ownership, the hash will contain a normal object ref, avoiding garbage collection. When we transition to sole ownership, we'll hold a WeakReference to the object in the hash.

My first pass at toggle ref implementation seems to work well for plain GLib.Object subclasses. Now I just have to make it work within the context of GtkObject destruction and so on. I won't be committing anything until I've done a considerable amount of testing, since ref management changes have historically been a source of pain.