sink

Takes over the initial ownership of a closure.

Each closure is initially created in a "floating" state, which means that the initial reference count is not owned by any caller.

This function checks to see if the object is still floating, and if so, unsets the floating state and decreases the reference count. If the closure is not floating, sink does nothing.

The reason for the existence of the floating state is to prevent cumbersome code sequences like:

closure = g_cclosure_new (cb_func, cb_data);
g_source_set_closure (source, closure);
g_closure_unref (closure); // GObject doesn't really need this

Because source_set_closure (and similar functions) take ownership of the initial reference count, if it is unowned, we instead can write:

g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));

Generally, this function is used together with @ref. An example of storing a closure for later notification looks like:

static GClosure *notify_closure = NULL;
void
foo_notify_set_closure (GClosure *closure)
{
	if (notify_closure)
		g_closure_unref (notify_closure);
	notify_closure = closure;
	if (notify_closure)
		{
			g_closure_ref (notify_closure);
			g_closure_sink (notify_closure);
		}
}

Because sink may decrement the reference count of a closure (if it hasn't been called on this yet) just like unref, @ref should be called prior to this function.

Parameters:

this	Closure to decrement the initial reference count on, if it's still being held