GObjectObjectadd_toggle_ref

Increases the reference count of the object by one and sets a callback to be called when all other references to the object are dropped, or when this is already the last reference to the object and another reference is established.

This functionality is intended for binding object to a proxy object managed by another memory manager. This is done with two paired references: the strong reference added by g_object_add_toggle_ref() and a reverse reference to the proxy object which is either a strong reference or weak reference.

The setup is that when there are no other references to object, only a weak reference is held in the reverse direction from object to the proxy object, but when there are other references held to object, a strong reference is held. The notify callback is called when the reference from object to the proxy object should be “toggled” from strong to weak (is_last_ref true) or weak to strong (is_last_ref false).

Since a (normal) reference must be held to the object before calling g_object_add_toggle_ref(), the initial state of the reverse link is always strong.

Multiple toggle references may be added to the same gobject, however if there are multiple toggle references to an object, none of them will ever be notified until all but one are removed. For this reason, you should only ever use a toggle reference if there is important state in the proxy object.

Note that if you unref the object on another thread, then notify might still be invoked after g_object_remove_toggle_ref(), and the object argument might be a dangling pointer. If the object is destroyed on other threads, you must take care of that yourself.

A g_object_add_toggle_ref() must be released with g_object_remove_toggle_ref().

Available since: 2.8

This method is not directly available to language bindings.