Re: gobject ref and unref ?

[David Nečas <yeti physics muni cz>]

Please don't cross-post.

On Tue, Nov 10, 2009 at 11:14:24PM +0530, Siddu wrote:
> How does one get to know if an API is adding a reference of its own to
> an object

References represent ownership.  Hence a reference is added if you
provide an object to be taken and used later.  Most methods that have
other object arguments beside `self' or `this' are of this kind.

    gtk_container_add(container, child);

Read:
container takes child (child becomes used/owned by container) so, it
adds a reference.

    gtk_container_child_get(container, child, ...);

Read:
something happens with container and child but their mutual ownership
remains unchanged so, when the function returns the number of references
remain unchanged (even though it can change during the call).

The difference should be pretty clear if you undestand the purpose of
the method you use.

There are a few somehwat counterintuitive methods such as
gtk_tree_model_get() but they always mention the ownership rules in the
documentation.

>     gtk_tree_view_set_model() is adding a reference count of its own
> to the store.

According to the above rules.

>     /* Set treeview's model */
>     gtk_tree_view_set_model( GTK_TREE_VIEW( treeview ),
>                              GTK_TREE_MODEL( store ) );
>     g_object_unref( G_OBJECT( store ) );

You do the unref only if you want to get rid of your own model 
reference, i.e. you are fine with hte model going poof the instant the
tree view decides it no longer needs the model.

To confuse things, widgets and other GtkObjects can exist in a state
not owned by anything (just initially after creation).  See the
documentation of GInitiallyUnowned for details.

Yeti