[gst-devel] Why do we call gst_object_unref() ?

[Wes Miller]

I'm going to give you a slightly different view of this answer.  This
explanation is slightly less correct, but once i figured it out, the whole
unref stuff made more sense.  This is a simple approach and there are
probably dozens of special cases I am skipping over.

First, let's say you have a program running in a local (your) thread.  You
want to do some Gstreamer stuff, so you create the pipeline, elements, etc.
by calling gst_init() and various "create" routines.  

Here's the stricky part; whatever you create will not be in your local
thread,  It will be in some other thread (probably) spawned by the
gst-Init() call.  Think of this as saying your code remains "over here" and
the pipeline, bus, loop, etc, are created "over there".  

The "create" functions return pointers that tell you not where your
creations are located, but where they are described.  They point at
structures (located in "over there's heap) that holds the details about the
pipeline or whatever you created.  These structures have a refcount var in
them that is set to 1 meaning somebody (you) are using those structures and
the stuff they describe.

Useful Note:  When a pipeline is created, it creates a bus.  The bus is an
object "over there" but you have no idea where!   A GstBus structure is also
created to describe the bus itself and to hold the refcount for the bus.  It
is set to one showing the pipeline holds a ref to the bus.     Hold that
thought and see the example below.

When you want to access something "over there" you must use the pointer you
got from the create function or get a new pointer by asking "over there" to
create a pointer/structure for you. 

When you are done with something, some object, "over there', you must
dereference it.  We do this with the g_object_unerf() function, which
reduces the refcount by 1.  It is possible for something to have many
references.  When the reference count goes to zero, the structure and the
object it describes are garbage collected. 

Example:

In your local code you create a GstBus* pointer.  When you call bus =
gst_pipeline_get_bus(), the pointer to the structure describing the bus is
returned..  Note that, in this case, the structure doesn't have to be
created.  It already exists.  It will be the same one created when the
pipeline created the bus.  It will hold a refcount of 2, one for you and one
for the pipeline.  

Now, do whatever you need to with the bus over there, say, assign it a
callback routine for the on_pad_added signal. 

Notice what you are really doing.  You are NOT directly touching the bus. 
Gst_bus_add_watch() uses the information in the "bus" structure and does its
magic indirectly.  You set the callback pointer into the bus object itself,
not its descriptive structure.

finally, you need to unref the bus.  You no longer need to know anything
about the bus.  It knows what you wanted it to know.  So, use
g_object_unref() to remove one ref from the structure.  The refcount will
decrease by one and will now equal one, the ref held by the pipeline.

Had the refcount gone to zero, the bus and structure would have been garbage
collected and gone out of scope.  The ref held by the pipeline keeps them
"alive".  At the end of your program. deref-ing the pipeline will cause it
to deref the bus automatically.

This can be messy and confusing.  Be sure to read the description of every
g_ and gst_ call you make to see if it tells you to unref something.

Hope this helps,

Wes

-- 
View this message in context: http://gstreamer-devel.966125.n4.nabble.com/Why-do-we-call-gst-object-unref-tp3170699p3172399.html
Sent from the GStreamer-devel mailing list archive at Nabble.com.