add_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 this to a proxy object managed by another memory manager. This is done with two paired references: the strong reference added by 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 this, only a weak reference is held in the reverse direction from this to the proxy object, but when there are other references held to this, a strong reference is held. The notify callback is called when the reference from this 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 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 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 add_toggle_ref must be released with remove_toggle_ref.

Parameters:

this	a Object
notify	a function to call when this reference is the last reference to the object, or is no longer the last reference.
data	data to pass to notify