Manual sink architecture

[diamondburned]

Problem

Currently, gotk4 commonly suffers from the following problem which would cause
massive memory leaks due to limitations of the Go garbage collector:

w := gtk.NewWidget()
w.ConnectSignal(func() {
	w.Use() // memory leak!
})

This is because all closures must be stored in a global registry to be
referenced back later, which would cause w to also be globally referenced,
meaning its finalizer is never called, causing a memory leak.

Current State

The current workaround involves creating a weak reference to w and using that
in the closure:

w := gtk.NewWidget()
wref := glib.NewWeakRef(w)
w.ConnectSignal(func() {
	w := wref.Get()
	w.Use() // we're good, actually!
})

This works for at least GTK widgets, because signals should not own a strong
reference to the object unless it is being called. Signals are strictly only
relevant when the object itself is still alive.

However, this workaround has a limitation: it doesn't work if w is stored in a
struct and that struct itself is referenced, as it commonly is. Consider the
following example:

type MyWidget struct {
	gtk.Widget
	data string
}

func NewMyWidget() *MyWidget {
	m := &MyWidget{}

	m.Widget = gtk.NewWidget()

	wref := glib.NewWeakRef(m.Widget)
	m.Widget.ConnectSignal(func() {
		w := wref.Get()
		w.Use(m.data) // memory leak!
	})
}

This may work if m is also created as a weak reference in Go's allocator
system, possibly by using a third-party library that handles weak references
like xeus2001/go-weak:

type MyWidget struct {
	gtk.Widget
	data string
}

func NewMyWidget() *MyWidget {
	m := &MyWidget{}

	m.Widget = gtk.NewWidget()

	mref := weak.NewRef(m)
	m.Widget.ConnectSignal(func() {
		m := mref.Get()
		m.Widget.Use(m.data) // we're good, actually!
	})
}

Proposed Solution

The proposed solution is to do what GTK itself does: use a floating reference by
default when new objects are constructed. This means that, unless the object is
immediately referenced by something else, it will be destroyed in the next
iteration of the main loop.

What this means is that the following code will not cause a memory leak:

w := gtk.NewWidget()
w.ConnectSignal(func() {
	w.Use() // we're good, actually!
})

This is because, assuming w is not referenced by anything else, it will be
destroyed in the next iteration of the main loop, and the closure will be
destroyed with it.

This code will cause w to sink:

w := gtk.NewWidget()
parent.Add(w)

This is because w is now referenced by parent, and will not be destroyed
until parent is destroyed.

However, this also means that if w is stored for longer than the lifetime of
parent, it will be destroyed in the next iteration of the main loop, causing
the program to crash:

w := gtk.NewWidget()
parent1.Add(w)
parent1.Destroy()
parent2.Add(w) // crash!

In this case, the user must manually sink w to prevent it from being
destroyed:

w := gtk.NewWidget().Sink()
parent1.Add(w)
parent1.Destroy()
parent2.Add(w) // we're good, actually!

However, by manually sinking w, the user must also manually destroy it:

w := gtk.NewWidget().Sink()
parent1.Add(w)
parent1.Destroy()
parent2.Add(w)
w.Destroy() // we're good, actually!

This doesn't actually destroy w immediately, it simply removes the sunken
reference so that Go's garbage collector can destroy it when it is no longer
referenced.

When sunken, references to w within closures will cause the same memory leak
as before:

w := gtk.NewWidget().Sink()
w.ConnectSignal(func() {
	w.Use() // memory leak!
})

However, note that the user should rarely need to sink objects. The only
time this should be necessary is when the user is storing an object for longer
than the lifetime of the object that references it. Doing so is already very
complicated, and the user should be aware of the consequences of doing so.

Implementation

TBD.