Closure.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, gobject.closure.Closure.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 gobject.global.sourceSetClosure (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 gobject.closure.Closure.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 gobject.closure.Closure.sink may decrement the reference count of a closure (if it hasn't been called on closure yet) just like gobject.closure.Closure.unref, gobject.closure.Closure.ref_ should be called prior to this function.