1 /* GStreamer

     2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>

     3  *                    2000 Wim Taymans <wtay@chello.be>

     4  *                    2005 Wim Taymans <wim@fluendo.com>

     5  *

     6  * gstobject.c: Fundamental class used for all of GStreamer

     7  *

     8  * This library is free software; you can redistribute it and/or

     9  * modify it under the terms of the GNU Library General Public

    10  * License as published by the Free Software Foundation; either

    11  * version 2 of the License, or (at your option) any later version.

    12  *

    13  * This library is distributed in the hope that it will be useful,

    14  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

    16  * Library General Public License for more details.

    17  *

    18  * You should have received a copy of the GNU Library General Public

    19  * License along with this library; if not, write to the

    20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,

    21  * Boston, MA 02111-1307, USA.

    22  */

    23 

    24 /**

    25  * SECTION:gstobject

    26  * @short_description: Base class for the GStreamer object hierarchy

    27  *

    28  * #GstObject provides a root for the object hierarchy tree filed in by the

    29  * GStreamer library.  It is currently a thin wrapper on top of

    30  * #GObject. It is an abstract class that is not very usable on its own.

    31  *

    32  * #GstObject gives us basic refcounting, parenting functionality and locking.

    33  * Most of the function are just extended for special GStreamer needs and can be

    34  * found under the same name in the base class of #GstObject which is #GObject

    35  * (e.g. g_object_ref() becomes gst_object_ref()).

    36  *

    37  * The most interesting difference between #GstObject and #GObject is the

    38  * "floating" reference count. A #GObject is created with a reference count of

    39  * 1, owned by the creator of the #GObject. (The owner of a reference is the

    40  * code section that has the right to call gst_object_unref() in order to

    41  * remove that reference.) A #GstObject is created with a reference count of 1

    42  * also, but it isn't owned by anyone; Instead, the initial reference count

    43  * of a #GstObject is "floating". The floating reference can be removed by

    44  * anyone at any time, by calling gst_object_sink().  gst_object_sink() does

    45  * nothing if an object is already sunk (has no floating reference).

    46  *

    47  * When you add a #GstElement to its parent container, the parent container will

    48  * do this:

    49  * <informalexample>

    50  * <programlisting>

    51  *   gst_object_ref (GST_OBJECT (child_element));

    52  *   gst_object_sink (GST_OBJECT (child_element));

    53  * </programlisting>

    54  * </informalexample>

    55  * This means that the container now owns a reference to the child element

    56  * (since it called gst_object_ref()), and the child element has no floating

    57  * reference.

    58  *

    59  * The purpose of the floating reference is to keep the child element alive

    60  * until you add it to a parent container, which then manages the lifetime of

    61  * the object itself:

    62  * <informalexample>

    63  * <programlisting>

    64  *    element = gst_element_factory_make (factoryname, name);

    65  *    // element has one floating reference to keep it alive

    66  *    gst_bin_add (GST_BIN (bin), element);

    67  *    // element has one non-floating reference owned by the container

    68  * </programlisting>

    69  * </informalexample>

    70  *

    71  * Another effect of this is, that calling gst_object_unref() on a bin object,

    72  * will also destoy all the #GstElement objects in it. The same is true for

    73  * calling gst_bin_remove().

    74  *

    75  * Special care has to be taken for all methods that gst_object_sink() an object

    76  * since if the caller of those functions had a floating reference to the object,

    77  * the object reference is now invalid.

    78  *

    79  * In contrast to #GObject instances, #GstObject adds a name property. The functions

    80  * gst_object_set_name() and gst_object_get_name() are used to set/get the name

    81  * of the object.

    82  *

    83  * Last reviewed on 2005-11-09 (0.9.4)

    84  */

    85 

    86 

    87 #include "gst_private.h"

    88 

    89 #include "gstobject.h"

    90 #include "gstmarshal.h"

    91 #include "gstinfo.h"

    92 #include "gstutils.h"

    93 

    94 #ifdef __SYMBIAN32__

    95 #include <glib_global.h>

    96 #include <gobject_global.h>

    97 #endif

    98 

    99 #ifndef GST_DISABLE_TRACE

   100 #include "gsttrace.h"

   101 static GstAllocTrace *_gst_object_trace;

   102 #endif

   103 

   104 

   105 #define DEBUG_REFCOUNT

   106 

   107 /* Object signals and args */

   108 enum

   109 {

   110   PARENT_SET,

   111   PARENT_UNSET,

   112 #ifndef GST_DISABLE_LOADSAVE

   113   OBJECT_SAVED,

   114 #endif

   115   DEEP_NOTIFY,

   116   LAST_SIGNAL

   117 };

   118 

   119 enum

   120 {

   121   ARG_0,

   122   ARG_NAME

   123       /* FILL ME */

   124 };

   125 

   126 enum

   127 {

   128   SO_OBJECT_LOADED,

   129   SO_LAST_SIGNAL

   130 };

   131 

   132 /* maps type name quark => count */

   133 static GData *object_name_counts = NULL;

   134 

   135 G_LOCK_DEFINE_STATIC (object_name_mutex);

   136 

   137 typedef struct _GstSignalObject GstSignalObject;

   138 typedef struct _GstSignalObjectClass GstSignalObjectClass;

   139 

   140 static GType gst_signal_object_get_type (void);

   141 static void gst_signal_object_class_init (GstSignalObjectClass * klass);

   142 static void gst_signal_object_init (GstSignalObject * object);

   143 

   144 #ifndef GST_DISABLE_LOADSAVE

   145 static guint gst_signal_object_signals[SO_LAST_SIGNAL] = { 0 };

   146 #endif

   147 

   148 static void gst_object_class_init (GstObjectClass * klass);

   149 static void gst_object_init (GTypeInstance * instance, gpointer g_class);

   150 

   151 static void gst_object_set_property (GObject * object, guint prop_id,

   152     const GValue * value, GParamSpec * pspec);

   153 static void gst_object_get_property (GObject * object, guint prop_id,

   154     GValue * value, GParamSpec * pspec);

   155 static void gst_object_dispatch_properties_changed (GObject * object,

   156     guint n_pspecs, GParamSpec ** pspecs);

   157 

   158 static void gst_object_dispose (GObject * object);

   159 static void gst_object_finalize (GObject * object);

   160 

   161 static gboolean gst_object_set_name_default (GstObject * object);

   162 

   163 #ifndef GST_DISABLE_LOADSAVE

   164 static void gst_object_real_restore_thyself (GstObject * object,

   165     xmlNodePtr self);

   166 #endif

   167 

   168 static GObjectClass *parent_class = NULL;

   169 static guint gst_object_signals[LAST_SIGNAL] = { 0 };

   170 #ifdef __SYMBIAN32__

   171 EXPORT_C

   172 #endif

   173 

   174 

   175 GType

   176 gst_object_get_type (void)

   177 {

   178   static GType gst_object_type = 0;

   179 

   180   if (G_UNLIKELY (gst_object_type == 0)) {

   181     static const GTypeInfo object_info = {

   182       sizeof (GstObjectClass),

   183       NULL,

   184       NULL,

   185       (GClassInitFunc) gst_object_class_init,

   186       NULL,

   187       NULL,

   188       sizeof (GstObject),

   189       0,

   190       gst_object_init,

   191       NULL

   192     };

   193 

   194     gst_object_type =

   195         g_type_register_static (G_TYPE_OBJECT, "GstObject", &object_info,

   196         G_TYPE_FLAG_ABSTRACT);

   197   }

   198   return gst_object_type;

   199 }

   200 

   201 static void

   202 gst_object_class_init (GstObjectClass * klass)

   203 {

   204   GObjectClass *gobject_class;

   205 

   206   gobject_class = G_OBJECT_CLASS (klass);

   207 

   208   parent_class = g_type_class_peek_parent (klass);

   209 

   210 #ifndef GST_DISABLE_TRACE

   211   _gst_object_trace = gst_alloc_trace_register (g_type_name (GST_TYPE_OBJECT));

   212 #endif

   213 

   214   gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_object_set_property);

   215   gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_object_get_property);

   216 

   217   g_object_class_install_property (gobject_class, ARG_NAME,

   218       g_param_spec_string ("name", "Name", "The name of the object",

   219           NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT));

   220 

   221   /**

   222    * GstObject::parent-set:

   223    * @gstobject: a #GstObject

   224    * @parent: the new parent

   225    *

   226    * Emitted when the parent of an object is set.

   227    */

   228   gst_object_signals[PARENT_SET] =

   229       g_signal_new ("parent-set", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,

   230       G_STRUCT_OFFSET (GstObjectClass, parent_set), NULL, NULL,

   231       g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_OBJECT);

   232 

   233   /**

   234    * GstObject::parent-unset:

   235    * @gstobject: a #GstObject

   236    * @parent: the old parent

   237    *

   238    * Emitted when the parent of an object is unset.

   239    */

   240   gst_object_signals[PARENT_UNSET] =

   241       g_signal_new ("parent-unset", G_TYPE_FROM_CLASS (klass),

   242       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstObjectClass, parent_unset), NULL,

   243       NULL, g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_OBJECT);

   244 

   245 #ifndef GST_DISABLE_LOADSAVE

   246   /**

   247    * GstObject::object-saved:

   248    * @gstobject: a #GstObject

   249    * @xml_node: the xmlNodePtr of the parent node

   250    *

   251    * Trigered whenever a new object is saved to XML. You can connect to this

   252    * signal to insert custom XML tags into the core XML.

   253    */

   254   /* FIXME This should be the GType of xmlNodePtr instead of G_TYPE_POINTER

   255    *       (if libxml would use GObject)

   256    */

   257   gst_object_signals[OBJECT_SAVED] =

   258       g_signal_new ("object-saved", G_TYPE_FROM_CLASS (klass),

   259       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstObjectClass, object_saved), NULL,

   260       NULL, g_cclosure_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_POINTER);

   261 

   262   klass->restore_thyself = gst_object_real_restore_thyself;

   263 #endif

   264 

   265   /**

   266    * GstObject::deep-notify:

   267    * @gstobject: a #GstObject

   268    * @prop_object: the object that originated the signal

   269    * @prop: the property that changed

   270    *

   271    * The deep notify signal is used to be notified of property changes. It is

   272    * typically attached to the toplevel bin to receive notifications from all

   273    * the elements contained in that bin.

   274    */

   275   gst_object_signals[DEEP_NOTIFY] =

   276       g_signal_new ("deep-notify", G_TYPE_FROM_CLASS (klass),

   277       G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_DETAILED |

   278       G_SIGNAL_NO_HOOKS, G_STRUCT_OFFSET (GstObjectClass, deep_notify), NULL,

   279       NULL, gst_marshal_VOID__OBJECT_PARAM, G_TYPE_NONE, 2, GST_TYPE_OBJECT,

   280       G_TYPE_PARAM);

   281 

   282   klass->path_string_separator = "/";

   283   klass->lock = g_new0 (GStaticRecMutex, 1);

   284   g_static_rec_mutex_init (klass->lock);

   285 

   286   klass->signal_object = g_object_new (gst_signal_object_get_type (), NULL);

   287 

   288   /* see the comments at gst_object_dispatch_properties_changed */

   289   gobject_class->dispatch_properties_changed

   290       = GST_DEBUG_FUNCPTR (gst_object_dispatch_properties_changed);

   291 

   292   gobject_class->dispose = gst_object_dispose;

   293   gobject_class->finalize = gst_object_finalize;

   294 }

   295 

   296 static void

   297 gst_object_init (GTypeInstance * instance, gpointer g_class)

   298 {

   299   GstObject *object = GST_OBJECT (instance);

   300 

   301   object->lock = g_mutex_new ();

   302   object->parent = NULL;

   303   object->name = NULL;

   304   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p new", object);

   305 

   306 #ifndef GST_DISABLE_TRACE

   307   gst_alloc_trace_new (_gst_object_trace, object);

   308 #endif

   309 

   310   object->flags = 0;

   311   GST_OBJECT_FLAG_SET (object, GST_OBJECT_FLOATING);

   312 }

   313 

   314 /**

   315  * gst_object_ref:

   316  * @object: a #GstObject to reference

   317  *

   318  * Increments the reference count on @object. This function

   319  * does not take the lock on @object because it relies on

   320  * atomic refcounting.

   321  *

   322  * This object returns the input parameter to ease writing

   323  * constructs like :

   324  *  result = gst_object_ref (object->parent);

   325  *

   326  * Returns: A pointer to @object

   327  */

   328 #ifdef __SYMBIAN32__

   329 EXPORT_C

   330 #endif

   331 gpointer

   332 gst_object_ref (gpointer object)

   333 {

   334   g_return_val_if_fail (object != NULL, NULL);

   335 

   336 #ifdef DEBUG_REFCOUNT

   337   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p ref %d->%d",

   338       object,

   339       ((GObject *) object)->ref_count, ((GObject *) object)->ref_count + 1);

   340 #endif

   341   g_object_ref (object);

   342 

   343   return object;

   344 }

   345 

   346 /**

   347  * gst_object_unref:

   348  * @object: a #GstObject to unreference

   349  *

   350  * Decrements the reference count on @object.  If reference count hits

   351  * zero, destroy @object. This function does not take the lock

   352  * on @object as it relies on atomic refcounting.

   353  *

   354  * The unref method should never be called with the LOCK held since

   355  * this might deadlock the dispose function.

   356  */

   357 #ifdef __SYMBIAN32__

   358 EXPORT_C

   359 #endif

   360 

   361 void

   362 gst_object_unref (gpointer object)

   363 {

   364   g_return_if_fail (object != NULL);

   365   g_return_if_fail (((GObject *) object)->ref_count > 0);

   366 

   367 #ifdef DEBUG_REFCOUNT

   368   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p unref %d->%d",

   369       object,

   370       ((GObject *) object)->ref_count, ((GObject *) object)->ref_count - 1);

   371 #endif

   372   g_object_unref (object);

   373 }

   374 

   375 /**

   376  * gst_object_sink:

   377  * @object: a #GstObject to sink

   378  *

   379  * If @object was floating, the #GST_OBJECT_FLOATING flag is removed

   380  * and @object is unreffed. When @object was not floating,

   381  * this function does nothing.

   382  *

   383  * Any newly created object has a refcount of 1 and is floating.

   384  * This function should be used when creating a new object to

   385  * symbolically 'take ownership' of @object. This done by first doing a

   386  * gst_object_ref() to keep a reference to @object and then gst_object_sink()

   387  * to remove and unref any floating references to @object.

   388  * Use gst_object_set_parent() to have this done for you.

   389  *

   390  * MT safe. This function grabs and releases @object lock.

   391  */

   392 #ifdef __SYMBIAN32__

   393 EXPORT_C

   394 #endif

   395 

   396 void

   397 gst_object_sink (gpointer object)

   398 {

   399   g_return_if_fail (GST_IS_OBJECT (object));

   400 

   401   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "sink");

   402 

   403   GST_OBJECT_LOCK (object);

   404   if (G_LIKELY (GST_OBJECT_IS_FLOATING (object))) {

   405     GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "clear floating flag");

   406     GST_OBJECT_FLAG_UNSET (object, GST_OBJECT_FLOATING);

   407     GST_OBJECT_UNLOCK (object);

   408     gst_object_unref (object);

   409   } else {

   410     GST_OBJECT_UNLOCK (object);

   411   }

   412 }

   413 

   414 /**

   415  * gst_object_replace:

   416  * @oldobj: pointer to a place of a #GstObject to replace

   417  * @newobj: a new #GstObject

   418  *

   419  * Unrefs the #GstObject pointed to by @oldobj, refs @newobj and

   420  * puts @newobj in *@oldobj. Be carefull when calling this

   421  * function, it does not take any locks. You might want to lock

   422  * the object owning @oldobj pointer before calling this

   423  * function.

   424  *

   425  * Make sure not to LOCK @oldobj because it might be unreffed

   426  * which could cause a deadlock when it is disposed.

   427  */

   428 #ifdef __SYMBIAN32__

   429 EXPORT_C

   430 #endif

   431 

   432 void

   433 gst_object_replace (GstObject ** oldobj, GstObject * newobj)

   434 {

   435   g_return_if_fail (oldobj != NULL);

   436   g_return_if_fail (*oldobj == NULL || GST_IS_OBJECT (*oldobj));

   437   g_return_if_fail (newobj == NULL || GST_IS_OBJECT (newobj));

   438 

   439 #ifdef DEBUG_REFCOUNT

   440   GST_CAT_LOG (GST_CAT_REFCOUNTING, "replace %s (%d) with %s (%d)",

   441       *oldobj ? GST_STR_NULL (GST_OBJECT_NAME (*oldobj)) : "(NONE)",

   442       *oldobj ? G_OBJECT (*oldobj)->ref_count : 0,

   443       newobj ? GST_STR_NULL (GST_OBJECT_NAME (newobj)) : "(NONE)",

   444       newobj ? G_OBJECT (newobj)->ref_count : 0);

   445 #endif

   446 

   447   if (G_LIKELY (*oldobj != newobj)) {

   448     if (newobj)

   449       gst_object_ref (newobj);

   450     if (*oldobj)

   451       gst_object_unref (*oldobj);

   452 

   453     *oldobj = newobj;

   454   }

   455 }

   456 

   457 /* dispose is called when the object has to release all links

   458  * to other objects */

   459 static void

   460 gst_object_dispose (GObject * object)

   461 {

   462   GstObject *parent;

   463 

   464   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "dispose");

   465 

   466   GST_OBJECT_LOCK (object);

   467   if ((parent = GST_OBJECT_PARENT (object)))

   468     goto have_parent;

   469   GST_OBJECT_PARENT (object) = NULL;

   470   GST_OBJECT_UNLOCK (object);

   471 

   472   parent_class->dispose (object);

   473 

   474   return;

   475 

   476   /* ERRORS */

   477 have_parent:

   478   {

   479     g_critical ("\nTrying to dispose object \"%s\", but it still has a "

   480         "parent \"%s\".\nYou need to let the parent manage the "

   481         "object instead of unreffing the object directly.\n",

   482         GST_OBJECT_NAME (object), GST_OBJECT_NAME (parent));

   483     GST_OBJECT_UNLOCK (object);

   484     /* ref the object again to revive it in this error case */

   485     object = gst_object_ref (object);

   486     return;

   487   }

   488 }

   489 

   490 /* finalize is called when the object has to free its resources */

   491 static void

   492 gst_object_finalize (GObject * object)

   493 {

   494   GstObject *gstobject = GST_OBJECT (object);

   495 

   496   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "finalize");

   497 

   498   g_signal_handlers_destroy (object);

   499 

   500   g_free (gstobject->name);

   501   g_mutex_free (gstobject->lock);

   502 

   503 #ifndef GST_DISABLE_TRACE

   504   gst_alloc_trace_free (_gst_object_trace, object);

   505 #endif

   506 

   507   parent_class->finalize (object);

   508 }

   509 

   510 /* Changing a GObject property of a GstObject will result in "deep_notify"

   511  * signals being emitted by the object itself, as well as in each parent

   512  * object. This is so that an application can connect a listener to the

   513  * top-level bin to catch property-change notifications for all contained

   514  * elements.

   515  *

   516  * This function is not MT safe in glib < 2.8 so we need to lock it with a

   517  * classwide mutex in that case.

   518  *

   519  * MT safe.

   520  */

   521 static void

   522 gst_object_dispatch_properties_changed (GObject * object,

   523     guint n_pspecs, GParamSpec ** pspecs)

   524 {

   525   GstObject *gst_object, *parent, *old_parent;

   526   guint i;

   527   gchar *name, *debug_name;

   528   GstObjectClass *klass;

   529 

   530   /* we fail when this is not a GstObject */

   531   g_return_if_fail (GST_IS_OBJECT (object));

   532 

   533   klass = GST_OBJECT_GET_CLASS (object);

   534 

   535   /* do the standard dispatching */

   536   G_OBJECT_CLASS (parent_class)->dispatch_properties_changed (object, n_pspecs,

   537       pspecs);

   538 

   539   gst_object = GST_OBJECT_CAST (object);

   540   name = gst_object_get_name (gst_object);

   541   debug_name = GST_STR_NULL (name);

   542 

   543   /* now let the parent dispatch those, too */

   544   parent = gst_object_get_parent (gst_object);

   545   while (parent) {

   546     for (i = 0; i < n_pspecs; i++) {

   547       GST_LOG_OBJECT (parent, "deep notification from %s (%s)",

   548           debug_name, pspecs[i]->name);

   549 

   550       g_signal_emit (parent, gst_object_signals[DEEP_NOTIFY],

   551           g_quark_from_string (pspecs[i]->name), GST_OBJECT_CAST (object),

   552           pspecs[i]);

   553     }

   554 

   555     old_parent = parent;

   556     parent = gst_object_get_parent (old_parent);

   557     gst_object_unref (old_parent);

   558   }

   559   g_free (name);

   560 }

   561 

   562 /**

   563  * gst_object_default_deep_notify:

   564  * @object: the #GObject that signalled the notify.

   565  * @orig: a #GstObject that initiated the notify.

   566  * @pspec: a #GParamSpec of the property.

   567  * @excluded_props: a set of user-specified properties to exclude or

   568  *  NULL to show all changes.

   569  *

   570  * A default deep_notify signal callback for an object. The user data

   571  * should contain a pointer to an array of strings that should be excluded

   572  * from the notify. The default handler will print the new value of the property

   573  * using g_print.

   574  *

   575  * MT safe. This function grabs and releases @object's LOCK for getting its

   576  *          path string.

   577  */

   578 #ifdef __SYMBIAN32__

   579 EXPORT_C

   580 #endif

   581 

   582 void

   583 gst_object_default_deep_notify (GObject * object, GstObject * orig,

   584     GParamSpec * pspec, gchar ** excluded_props)

   585 {

   586   GValue value = { 0, };        /* the important thing is that value.type = 0 */

   587   gchar *str = NULL;

   588   gchar *name = NULL;

   589 

   590   if (pspec->flags & G_PARAM_READABLE) {

   591     /* let's not print these out for excluded properties... */

   592     while (excluded_props != NULL && *excluded_props != NULL) {

   593       if (strcmp (pspec->name, *excluded_props) == 0)

   594         return;

   595       excluded_props++;

   596     }

   597     g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (pspec));

   598     g_object_get_property (G_OBJECT (orig), pspec->name, &value);

   599 

   600     if (G_IS_PARAM_SPEC_ENUM (pspec)) {

   601       GEnumValue *enum_value;

   602 

   603       enum_value =

   604           g_enum_get_value (G_ENUM_CLASS (g_type_class_ref (pspec->value_type)),

   605           g_value_get_enum (&value));

   606 

   607       str = g_strdup_printf ("%s (%d)", enum_value->value_nick,

   608           enum_value->value);

   609     } else {

   610       str = g_strdup_value_contents (&value);

   611     }

   612     name = gst_object_get_path_string (orig);

   613     g_print ("%s: %s = %s\n", name, pspec->name, str);

   614     g_free (name);

   615     g_free (str);

   616     g_value_unset (&value);

   617   } else {

   618     name = gst_object_get_path_string (orig);

   619     g_warning ("Parameter %s not readable in %s.", pspec->name, name);

   620     g_free (name);

   621   }

   622 }

   623 

   624 static gboolean

   625 gst_object_set_name_default (GstObject * object)

   626 {

   627   const gchar *type_name;

   628   gint count;

   629   gchar *name, *tmp;

   630   gboolean result;

   631   GQuark q;

   632 

   633   /* to ensure guaranteed uniqueness across threads, only one thread

   634    * may ever assign a name */

   635   G_LOCK (object_name_mutex);

   636 

   637   if (!object_name_counts) {

   638     g_datalist_init (&object_name_counts);

   639   }

   640 

   641   q = g_type_qname (G_OBJECT_TYPE (object));

   642   count = GPOINTER_TO_INT (g_datalist_id_get_data (&object_name_counts, q));

   643   g_datalist_id_set_data (&object_name_counts, q, GINT_TO_POINTER (count + 1));

   644 

   645   G_UNLOCK (object_name_mutex);

   646 

   647   /* GstFooSink -> foosinkN */

   648   type_name = g_quark_to_string (q);

   649   if (strncmp (type_name, "Gst", 3) == 0)

   650     type_name += 3;

   651   tmp = g_strdup_printf ("%s%d", type_name, count);

   652   name = g_ascii_strdown (tmp, strlen (tmp));

   653   g_free (tmp);

   654 

   655   result = gst_object_set_name (object, name);

   656   g_free (name);

   657 

   658   return result;

   659 }

   660 

   661 /**

   662  * gst_object_set_name:

   663  * @object: a #GstObject

   664  * @name:   new name of object

   665  *

   666  * Sets the name of @object, or gives @object a guaranteed unique

   667  * name (if @name is NULL).

   668  * This function makes a copy of the provided name, so the caller

   669  * retains ownership of the name it sent.

   670  *

   671  * Returns: TRUE if the name could be set. Since Objects that have

   672  * a parent cannot be renamed, this function returns FALSE in those

   673  * cases.

   674  *

   675  * MT safe.  This function grabs and releases @object's LOCK.

   676  */

   677 #ifdef __SYMBIAN32__

   678 EXPORT_C

   679 #endif

   680 

   681 gboolean

   682 gst_object_set_name (GstObject * object, const gchar * name)

   683 {

   684   gboolean result;

   685 

   686   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);

   687 

   688   GST_OBJECT_LOCK (object);

   689 

   690   /* parented objects cannot be renamed */

   691   if (G_UNLIKELY (object->parent != NULL))

   692     goto had_parent;

   693 

   694   if (name != NULL) {

   695     g_free (object->name);

   696     object->name = g_strdup (name);

   697     GST_OBJECT_UNLOCK (object);

   698     result = TRUE;

   699   } else {

   700     GST_OBJECT_UNLOCK (object);

   701     result = gst_object_set_name_default (object);

   702   }

   703   return result;

   704 

   705   /* error */

   706 had_parent:

   707   {

   708     GST_WARNING ("parented objects can't be renamed");

   709     GST_OBJECT_UNLOCK (object);

   710     return FALSE;

   711   }

   712 }

   713 

   714 /**

   715  * gst_object_get_name:

   716  * @object: a #GstObject

   717  *

   718  * Returns a copy of the name of @object.

   719  * Caller should g_free() the return value after usage.

   720  * For a nameless object, this returns NULL, which you can safely g_free()

   721  * as well.

   722  *

   723  * Returns: the name of @object. g_free() after usage.

   724  *

   725  * MT safe. This function grabs and releases @object's LOCK.

   726  */

   727 #ifdef __SYMBIAN32__

   728 EXPORT_C

   729 #endif 

   730 gchar *

   731 gst_object_get_name (GstObject * object)

   732 {

   733   gchar *result = NULL;

   734 

   735   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);

   736 

   737   GST_OBJECT_LOCK (object);

   738   result = g_strdup (object->name);

   739   GST_OBJECT_UNLOCK (object);

   740 

   741   return result;

   742 }

   743 

   744 /**

   745  * gst_object_set_name_prefix:

   746  * @object:      a #GstObject

   747  * @name_prefix: new name prefix of @object

   748  *

   749  * Sets the name prefix of @object to @name_prefix.

   750  * This function makes a copy of the provided name prefix, so the caller

   751  * retains ownership of the name prefix it sent.

   752  *

   753  * MT safe.  This function grabs and releases @object's LOCK.

   754  */

   755 #ifdef __SYMBIAN32__

   756 EXPORT_C

   757 #endif

   758 

   759 void

   760 gst_object_set_name_prefix (GstObject * object, const gchar * name_prefix)

   761 {

   762   g_return_if_fail (GST_IS_OBJECT (object));

   763 

   764   GST_OBJECT_LOCK (object);

   765   g_free (object->name_prefix);

   766   object->name_prefix = g_strdup (name_prefix); /* NULL gives NULL */

   767   GST_OBJECT_UNLOCK (object);

   768 }

   769 

   770 /**

   771  * gst_object_get_name_prefix:

   772  * @object: a #GstObject

   773  *

   774  * Returns a copy of the name prefix of @object.

   775  * Caller should g_free() the return value after usage.

   776  * For a prefixless object, this returns NULL, which you can safely g_free()

   777  * as well.

   778  *

   779  * Returns: the name prefix of @object. g_free() after usage.

   780  *

   781  * MT safe. This function grabs and releases @object's LOCK.

   782  */

   783 #ifdef __SYMBIAN32__

   784 EXPORT_C

   785 #endif

   786 

   787 gchar *

   788 gst_object_get_name_prefix (GstObject * object)

   789 {

   790   gchar *result = NULL;

   791 

   792   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);

   793 

   794   GST_OBJECT_LOCK (object);

   795   result = g_strdup (object->name_prefix);

   796   GST_OBJECT_UNLOCK (object);

   797 

   798   return result;

   799 }

   800 

   801 /**

   802  * gst_object_set_parent:

   803  * @object: a #GstObject

   804  * @parent: new parent of object

   805  *

   806  * Sets the parent of @object to @parent. The object's reference count will

   807  * be incremented, and any floating reference will be removed (see gst_object_sink()).

   808  *

   809  * This function causes the parent-set signal to be emitted when the parent

   810  * was successfully set.

   811  *

   812  * Returns: TRUE if @parent could be set or FALSE when @object

   813  * already had a parent or @object and @parent are the same.

   814  *

   815  * MT safe. Grabs and releases @object's LOCK.

   816  */

   817 #ifdef __SYMBIAN32__

   818 EXPORT_C

   819 #endif 

   820 gboolean

   821 gst_object_set_parent (GstObject * object, GstObject * parent)

   822 {

   823   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);

   824   g_return_val_if_fail (GST_IS_OBJECT (parent), FALSE);

   825   g_return_val_if_fail (object != parent, FALSE);

   826 

   827   GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object,

   828       "set parent (ref and sink)");

   829 

   830   GST_OBJECT_LOCK (object);

   831   if (G_UNLIKELY (object->parent != NULL))

   832     goto had_parent;

   833 

   834   /* sink object, we don't call our own function because we don't

   835    * need to release/acquire the lock needlessly or touch the refcount

   836    * in the floating case. */

   837   object->parent = parent;

   838   if (G_LIKELY (GST_OBJECT_IS_FLOATING (object))) {

   839     GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "unsetting floating flag");

   840     GST_OBJECT_FLAG_UNSET (object, GST_OBJECT_FLOATING);

   841     GST_OBJECT_UNLOCK (object);

   842   } else {

   843     GST_OBJECT_UNLOCK (object);

   844     gst_object_ref (object);

   845   }

   846 

   847   g_signal_emit (G_OBJECT (object), gst_object_signals[PARENT_SET], 0, parent);

   848 

   849   return TRUE;

   850 

   851   /* ERROR handling */

   852 had_parent:

   853   {

   854     GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object,

   855         "set parent failed, object already had a parent");

   856     GST_OBJECT_UNLOCK (object);

   857     return FALSE;

   858   }

   859 }

   860 

   861 /**

   862  * gst_object_get_parent:

   863  * @object: a #GstObject

   864  *

   865  * Returns the parent of @object. This function increases the refcount

   866  * of the parent object so you should gst_object_unref() it after usage.

   867  *

   868  * Returns: parent of @object, this can be NULL if @object has no

   869  *   parent. unref after usage.

   870  *

   871  * MT safe. Grabs and releases @object's LOCK.

   872  */

   873 #ifdef __SYMBIAN32__

   874 EXPORT_C

   875 #endif

   876 

   877 GstObject *

   878 gst_object_get_parent (GstObject * object)

   879 {

   880   GstObject *result = NULL;

   881 

   882   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);

   883 

   884   GST_OBJECT_LOCK (object);

   885   result = object->parent;

   886   if (G_LIKELY (result))

   887     gst_object_ref (result);

   888   GST_OBJECT_UNLOCK (object);

   889 

   890   return result;

   891 }

   892 

   893 /**

   894  * gst_object_unparent:

   895  * @object: a #GstObject to unparent

   896  *

   897  * Clear the parent of @object, removing the associated reference.

   898  * This function decreases the refcount of @object.

   899  *

   900  * MT safe. Grabs and releases @object's lock.

   901  */

   902 #ifdef __SYMBIAN32__

   903 EXPORT_C

   904 #endif 

   905 void

   906 gst_object_unparent (GstObject * object)

   907 {

   908   GstObject *parent;

   909 

   910   g_return_if_fail (GST_IS_OBJECT (object));

   911 

   912   GST_OBJECT_LOCK (object);

   913   parent = object->parent;

   914 

   915   if (G_LIKELY (parent != NULL)) {

   916     GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "unparent");

   917     object->parent = NULL;

   918     GST_OBJECT_UNLOCK (object);

   919 

   920     g_signal_emit (G_OBJECT (object), gst_object_signals[PARENT_UNSET], 0,

   921         parent);

   922 

   923     gst_object_unref (object);

   924   } else {

   925     GST_OBJECT_UNLOCK (object);

   926   }

   927 }

   928 

   929 /**

   930  * gst_object_has_ancestor:

   931  * @object: a #GstObject to check

   932  * @ancestor: a #GstObject to check as ancestor

   933  *

   934  * Check if @object has an ancestor @ancestor somewhere up in

   935  * the hierarchy.

   936  *

   937  * Returns: TRUE if @ancestor is an ancestor of @object.

   938  *

   939  * MT safe. Grabs and releases @object's locks.

   940  */

   941 #ifdef __SYMBIAN32__

   942 EXPORT_C

   943 #endif

   944 

   945 gboolean

   946 gst_object_has_ancestor (GstObject * object, GstObject * ancestor)

   947 {

   948   GstObject *parent;

   949   gboolean result = FALSE;

   950 

   951   if (object == NULL)

   952     return FALSE;

   953 

   954   if (object == ancestor)

   955     return TRUE;

   956 

   957   parent = gst_object_get_parent (object);

   958   result = gst_object_has_ancestor (parent, ancestor);

   959   if (parent)

   960     gst_object_unref (parent);

   961 

   962   return result;

   963 }

   964 

   965 /**

   966  * gst_object_check_uniqueness:

   967  * @list: a list of #GstObject to check through

   968  * @name: the name to search for

   969  *

   970  * Checks to see if there is any object named @name in @list. This function

   971  * does not do any locking of any kind. You might want to protect the

   972  * provided list with the lock of the owner of the list. This function

   973  * will lock each #GstObject in the list to compare the name, so be

   974  * carefull when passing a list with a locked object.

   975  *

   976  * Returns: TRUE if a #GstObject named @name does not appear in @list,

   977  * FALSE if it does.

   978  *

   979  * MT safe. Grabs and releases the LOCK of each object in the list.

   980  */

   981 #ifdef __SYMBIAN32__

   982 EXPORT_C

   983 #endif

   984 

   985 gboolean

   986 gst_object_check_uniqueness (GList * list, const gchar * name)

   987 {

   988   gboolean result = TRUE;

   989 

   990   g_return_val_if_fail (name != NULL, FALSE);

   991 

   992   for (; list; list = g_list_next (list)) {

   993     GstObject *child;

   994     gboolean eq;

   995 

   996     child = GST_OBJECT (list->data);

   997 

   998     GST_OBJECT_LOCK (child);

   999     eq = strcmp (GST_OBJECT_NAME (child), name) == 0;

  1000     GST_OBJECT_UNLOCK (child);

  1001 

  1002     if (G_UNLIKELY (eq)) {

  1003       result = FALSE;

  1004       break;

  1005     }

  1006   }

  1007   return result;

  1008 }

  1009 

  1010 

  1011 #ifndef GST_DISABLE_LOADSAVE

  1012 /**

  1013  * gst_object_save_thyself:

  1014  * @object: a #GstObject to save

  1015  * @parent: The parent XML node to save @object into

  1016  *

  1017  * Saves @object into the parent XML node.

  1018  *

  1019  * Returns: the new xmlNodePtr with the saved object

  1020  */

  1021 xmlNodePtr

  1022 gst_object_save_thyself (GstObject * object, xmlNodePtr parent)

  1023 {

  1024   GstObjectClass *oclass;

  1025 

  1026   g_return_val_if_fail (GST_IS_OBJECT (object), parent);

  1027   g_return_val_if_fail (parent != NULL, parent);

  1028 

  1029   oclass = GST_OBJECT_GET_CLASS (object);

  1030 

  1031   if (oclass->save_thyself)

  1032     oclass->save_thyself (object, parent);

  1033 

  1034   g_signal_emit (G_OBJECT (object), gst_object_signals[OBJECT_SAVED], 0,

  1035       parent);

  1036 

  1037   return parent;

  1038 }

  1039 

  1040 /**

  1041  * gst_object_restore_thyself:

  1042  * @object: a #GstObject to load into

  1043  * @self: The XML node to load @object from

  1044  *

  1045  * Restores @object with the data from the parent XML node.

  1046  */

  1047 void

  1048 gst_object_restore_thyself (GstObject * object, xmlNodePtr self)

  1049 {

  1050   GstObjectClass *oclass;

  1051 

  1052   g_return_if_fail (GST_IS_OBJECT (object));

  1053   g_return_if_fail (self != NULL);

  1054 

  1055   oclass = GST_OBJECT_GET_CLASS (object);

  1056 

  1057   if (oclass->restore_thyself)

  1058     oclass->restore_thyself (object, self);

  1059 }

  1060 

  1061 static void

  1062 gst_object_real_restore_thyself (GstObject * object, xmlNodePtr self)

  1063 {

  1064   g_return_if_fail (GST_IS_OBJECT (object));

  1065   g_return_if_fail (self != NULL);

  1066 

  1067   gst_class_signal_emit_by_name (object, "object_loaded", self);

  1068 }

  1069 #endif /* GST_DISABLE_LOADSAVE */

  1070 

  1071 static void

  1072 gst_object_set_property (GObject * object, guint prop_id,

  1073     const GValue * value, GParamSpec * pspec)

  1074 {

  1075   GstObject *gstobject;

  1076 

  1077   gstobject = GST_OBJECT (object);

  1078 

  1079   switch (prop_id) {

  1080     case ARG_NAME:

  1081       gst_object_set_name (gstobject, g_value_get_string (value));

  1082       break;

  1083     default:

  1084       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);

  1085       break;

  1086   }

  1087 }

  1088 

  1089 static void

  1090 gst_object_get_property (GObject * object, guint prop_id,

  1091     GValue * value, GParamSpec * pspec)

  1092 {

  1093   GstObject *gstobject;

  1094 

  1095   gstobject = GST_OBJECT (object);

  1096 

  1097   switch (prop_id) {

  1098     case ARG_NAME:

  1099       g_value_take_string (value, gst_object_get_name (gstobject));

  1100       break;

  1101     default:

  1102       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);

  1103       break;

  1104   }

  1105 }

  1106 

  1107 /**

  1108  * gst_object_get_path_string:

  1109  * @object: a #GstObject

  1110  *

  1111  * Generates a string describing the path of @object in

  1112  * the object hierarchy. Only useful (or used) for debugging.

  1113  *

  1114  * Returns: a string describing the path of @object. You must

  1115  *          g_free() the string after usage.

  1116  *

  1117  * MT safe. Grabs and releases the #GstObject's LOCK for all objects

  1118  *          in the hierarchy.

  1119  */

  1120 #ifdef __SYMBIAN32__

  1121 EXPORT_C

  1122 #endif

  1123 

  1124 gchar *

  1125 gst_object_get_path_string (GstObject * object)

  1126 {

  1127   GSList *parentage;

  1128   GSList *parents;

  1129   void *parent;

  1130   gchar *prevpath, *path;

  1131   gchar *component;

  1132   gchar *separator;

  1133 

  1134   /* ref object before adding to list */