GObject.Object.add_toggle_ref

### Method

# GObject Objectadd_toggle_ref

since: 2.8

#### Declaration [src]

    void
    g_object_add_toggle_ref (
      GObject* object,
      GToggleNotify notify,
      gpointer data
    )

#### Description [src]

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.

#### Parameters

`notify`

  Type: `GToggleNotify`

  A function to call when this reference is the last reference to the object, or is no longer the last reference.

`data`

  Type: `gpointer`

  Data to pass to `notify`.

  The argument can be `NULL`.
  The data is owned by the caller of the method.