takeRef

If @object is floating, sink it. Otherwise, do nothing.

In other words, this function will convert a floating reference (if present) into a full reference.

Typically you want to use g_object_ref_sink() in order to automatically do the correct thing with respect to floating or non-floating references, but there is one specific scenario where this function is helpful.

The situation where this function is helpful is when creating an API that allows the user to provide a callback function that returns a GObject. We certainly want to allow the user the flexibility to return a non-floating reference from this callback (for the case where the object that is being returned already exists).

At the same time, the API style of some popular GObject-based libraries (such as Gtk) make it likely that for newly-created GObject instances, the user can be saved some typing if they are allowed to return a floating reference.

Using this function on the return value of the user's callback allows the user to do whichever is more convenient for them. The caller will always receives exactly one full reference to the value: either the one that was returned in the first place, or a floating reference that has been converted to a full reference.

This function has an odd interaction when combined with g_object_ref_sink() running at the same time in another thread on the same #GObject instance. If g_object_ref_sink() runs first then the result will be that the floating reference is converted to a hard reference. If g_object_take_ref() runs first then the result will be that the floating reference is converted to a hard reference and an additional reference on top of that one is added. It is best to avoid this situation.