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.
| 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 |