gst/gstobject.c

   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 #include "gst_private.h"
  87
  88 #include "gstobject.h"
  89 #include "gstmarshal.h"
  90 #include "gstinfo.h"
  91 #include "gstutils.h"
  92
  93 #ifndef GST_DISABLE_TRACE
  94 #include "gsttrace.h"
  95 static GstAllocTrace *_gst_object_trace;
  96 #endif
  97
  98 #define DEBUG_REFCOUNT
  99
 100 /* Object signals and args */
 101 enum
 102 {
 103   PARENT_SET,
 104   PARENT_UNSET,
 105 #ifndef GST_DISABLE_LOADSAVE
 106   OBJECT_SAVED,
 107 #endif
 108   DEEP_NOTIFY,
 109   LAST_SIGNAL
 110 };
 111
 112 enum
 113 {
 114   ARG_0,
 115   ARG_NAME
 116       /* FILL ME */
 117 };
 118
 119 enum
 120 {
 121   SO_OBJECT_LOADED,
 122   SO_LAST_SIGNAL
 123 };
 124
 125 /* maps type name quark => count */
 126 static GData *object_name_counts = NULL;
 127
 128 G_LOCK_DEFINE_STATIC (object_name_mutex);
 129
 130 typedef struct _GstSignalObject GstSignalObject;
 131 typedef struct _GstSignalObjectClass GstSignalObjectClass;
 132
 133 static GType gst_signal_object_get_type (void);
 134 static void gst_signal_object_class_init (GstSignalObjectClass * klass);
 135 static void gst_signal_object_init (GstSignalObject * object);
 136
 137 #ifndef GST_DISABLE_LOADSAVE
 138 static guint gst_signal_object_signals[SO_LAST_SIGNAL] = { 0 };
 139 #endif
 140
 141 static void gst_object_class_init (GstObjectClass * klass);
 142 static void gst_object_init (GTypeInstance * instance, gpointer g_class);
 143
 144 static void gst_object_set_property (GObject * object, guint prop_id,
 145     const GValue * value, GParamSpec * pspec);
 146 static void gst_object_get_property (GObject * object, guint prop_id,
 147     GValue * value, GParamSpec * pspec);
 148 static void gst_object_dispatch_properties_changed (GObject * object,
 149     guint n_pspecs, GParamSpec ** pspecs);
 150
 151 static void gst_object_dispose (GObject * object);
 152 static void gst_object_finalize (GObject * object);
 153
 154 static gboolean gst_object_set_name_default (GstObject * object);
 155
 156 #ifndef GST_DISABLE_LOADSAVE
 157 static void gst_object_real_restore_thyself (GstObject * object,
 158     xmlNodePtr self);
 159 #endif
 160
 161 static GObjectClass *parent_class = NULL;
 162 static guint gst_object_signals[LAST_SIGNAL] = { 0 };
 163
 164 GType
 165 gst_object_get_type (void)
 166 {
 167   static GType gst_object_type = 0;
 168
 169   if (G_UNLIKELY (gst_object_type == 0)) {
 170     static const GTypeInfo object_info = {
 171       sizeof (GstObjectClass),
 172       NULL,
 173       NULL,
 174       (GClassInitFunc) gst_object_class_init,
 175       NULL,
 176       NULL,
 177       sizeof (GstObject),
 178       0,
 179       gst_object_init,
 180       NULL
 181     };
 182
 183     gst_object_type =
 184         g_type_register_static (G_TYPE_OBJECT, "GstObject", &object_info,
 185         G_TYPE_FLAG_ABSTRACT);
 186   }
 187   return gst_object_type;
 188 }
 189
 190 static void
 191 gst_object_class_init (GstObjectClass * klass)
 192 {
 193   GObjectClass *gobject_class;
 194
 195   gobject_class = G_OBJECT_CLASS (klass);
 196
 197   parent_class = g_type_class_peek_parent (klass);
 198
 199 #ifndef GST_DISABLE_TRACE
 200   _gst_object_trace = gst_alloc_trace_register (g_type_name (GST_TYPE_OBJECT));
 201 #endif
 202
 203   gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_object_set_property);
 204   gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_object_get_property);
 205
 206   g_object_class_install_property (gobject_class, ARG_NAME,
 207       g_param_spec_string ("name", "Name", "The name of the object",
 208           NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 209
 210   /**
 211    * GstObject::parent-set:
 212    * @gstobject: a #GstObject
 213    * @parent: the new parent
 214    *
 215    * Emitted when the parent of an object is set.
 216    */
 217   gst_object_signals[PARENT_SET] =
 218       g_signal_new ("parent-set", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 219       G_STRUCT_OFFSET (GstObjectClass, parent_set), NULL, NULL,
 220       g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
 221
 222   /**
 223    * GstObject::parent-unset:
 224    * @gstobject: a #GstObject
 225    * @parent: the old parent
 226    *
 227    * Emitted when the parent of an object is unset.
 228    */
 229   gst_object_signals[PARENT_UNSET] =
 230       g_signal_new ("parent-unset", G_TYPE_FROM_CLASS (klass),
 231       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstObjectClass, parent_unset), NULL,
 232       NULL, g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
 233
 234 #ifndef GST_DISABLE_LOADSAVE
 235   /**
 236    * GstObject::object-saved:
 237    * @gstobject: a #GstObject
 238    * @xml_node: the xmlNodePtr of the parent node
 239    *
 240    * Trigered whenever a new object is saved to XML. You can connect to this
 241    * signal to insert custom XML tags into the core XML.
 242    */
 243   /* FIXME This should be the GType of xmlNodePtr instead of G_TYPE_POINTER
 244    *       (if libxml would use GObject)
 245    */
 246   gst_object_signals[OBJECT_SAVED] =
 247       g_signal_new ("object-saved", G_TYPE_FROM_CLASS (klass),
 248       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstObjectClass, object_saved), NULL,
 249       NULL, g_cclosure_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_POINTER);
 250
 251   klass->restore_thyself = gst_object_real_restore_thyself;
 252 #endif
 253
 254   /**
 255    * GstObject::deep-notify:
 256    * @gstobject: a #GstObject
 257    * @prop_object: the object that originated the signal
 258    * @prop: the property that changed
 259    *
 260    * The deep notify signal is used to be notified of property changes. It is
 261    * typically attached to the toplevel bin to receive notifications from all
 262    * the elements contained in that bin.
 263    */
 264   gst_object_signals[DEEP_NOTIFY] =
 265       g_signal_new ("deep-notify", G_TYPE_FROM_CLASS (klass),
 266       G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_DETAILED |
 267       G_SIGNAL_NO_HOOKS, G_STRUCT_OFFSET (GstObjectClass, deep_notify), NULL,
 268       NULL, gst_marshal_VOID__OBJECT_PARAM, G_TYPE_NONE, 2, GST_TYPE_OBJECT,
 269       G_TYPE_PARAM);
 270
 271   klass->path_string_separator = "/";
 272   klass->lock = g_new0 (GStaticRecMutex, 1);
 273   g_static_rec_mutex_init (klass->lock);
 274
 275   klass->signal_object = g_object_new (gst_signal_object_get_type (), NULL);
 276
 277   /* see the comments at gst_object_dispatch_properties_changed */
 278   gobject_class->dispatch_properties_changed
 279       = GST_DEBUG_FUNCPTR (gst_object_dispatch_properties_changed);
 280
 281   gobject_class->dispose = gst_object_dispose;
 282   gobject_class->finalize = gst_object_finalize;
 283 }
 284
 285 static void
 286 gst_object_init (GTypeInstance * instance, gpointer g_class)
 287 {
 288   GstObject *object = GST_OBJECT (instance);
 289
 290   object->lock = g_mutex_new ();
 291   object->parent = NULL;
 292   object->name = NULL;
 293   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p new", object);
 294
 295 #ifndef GST_DISABLE_TRACE
 296   gst_alloc_trace_new (_gst_object_trace, object);
 297 #endif
 298
 299   object->flags = 0;
 300   GST_OBJECT_FLAG_SET (object, GST_OBJECT_FLOATING);
 301 }
 302
 303 /**
 304  * gst_object_ref:
 305  * @object: a #GstObject to reference
 306  *
 307  * Increments the refence count on @object. This function
 308  * does not take the lock on @object because it relies on
 309  * atomic refcounting.
 310  *
 311  * This object returns the input parameter to ease writing
 312  * constructs like :
 313  *  result = gst_object_ref (object->parent);
 314  *
 315  * Returns: A pointer to @object
 316  */
 317 gpointer
 318 gst_object_ref (gpointer object)
 319 {
 320   g_return_val_if_fail (object != NULL, NULL);
 321
 322 #ifdef DEBUG_REFCOUNT
 323   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p ref %d->%d",
 324       object,
 325       ((GObject *) object)->ref_count, ((GObject *) object)->ref_count + 1);
 326 #endif
 327   g_object_ref (object);
 328
 329   return object;
 330 }
 331
 332 /**
 333  * gst_object_unref:
 334  * @object: a #GstObject to unreference
 335  *
 336  * Decrements the refence count on @object.  If reference count hits
 337  * zero, destroy @object. This function does not take the lock
 338  * on @object as it relies on atomic refcounting.
 339  *
 340  * The unref method should never be called with the LOCK held since
 341  * this might deadlock the dispose function.
 342  */
 343 void
 344 gst_object_unref (gpointer object)
 345 {
 346   g_return_if_fail (object != NULL);
 347   g_return_if_fail (((GObject *) object)->ref_count > 0);
 348
 349 #ifdef DEBUG_REFCOUNT
 350   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p unref %d->%d",
 351       object,
 352       ((GObject *) object)->ref_count, ((GObject *) object)->ref_count - 1);
 353 #endif
 354   g_object_unref (object);
 355 }
 356
 357 /**
 358  * gst_object_sink:
 359  * @object: a #GstObject to sink
 360  *
 361  * If @object was floating, the #GST_OBJECT_FLOATING flag is removed
 362  * and @object is unreffed. When @object was not floating,
 363  * this function does nothing.
 364  *
 365  * Any newly created object has a refcount of 1 and is floating.
 366  * This function should be used when creating a new object to
 367  * symbolically 'take ownership' of @object. This done by first doing a
 368  * gst_object_ref() to keep a reference to @object and then gst_object_sink()
 369  * to remove and unref any floating references to @object.
 370  * Use gst_object_set_parent() to have this done for you.
 371  *
 372  * MT safe. This function grabs and releases @object lock.
 373  */
 374 void
 375 gst_object_sink (gpointer object)
 376 {
 377   g_return_if_fail (GST_IS_OBJECT (object));
 378
 379   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "sink");
 380
 381   GST_OBJECT_LOCK (object);
 382   if (G_LIKELY (GST_OBJECT_IS_FLOATING (object))) {
 383     GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "clear floating flag");
 384     GST_OBJECT_FLAG_UNSET (object, GST_OBJECT_FLOATING);
 385     GST_OBJECT_UNLOCK (object);
 386     gst_object_unref (object);
 387   } else {
 388     GST_OBJECT_UNLOCK (object);
 389   }
 390 }
 391
 392 /**
 393  * gst_object_replace:
 394  * @oldobj: pointer to a place of a #GstObject to replace
 395  * @newobj: a new #GstObject
 396  *
 397  * Unrefs the #GstObject pointed to by @oldobj, refs @newobj and
 398  * puts @newobj in *@oldobj. Be carefull when calling this
 399  * function, it does not take any locks. You might want to lock
 400  * the object owning @oldobj pointer before calling this
 401  * function.
 402  *
 403  * Make sure not to LOCK @oldobj because it might be unreffed
 404  * which could cause a deadlock when it is disposed.
 405  */
 406 void
 407 gst_object_replace (GstObject ** oldobj, GstObject * newobj)
 408 {
 409   g_return_if_fail (oldobj != NULL);
 410   g_return_if_fail (*oldobj == NULL || GST_IS_OBJECT (*oldobj));
 411   g_return_if_fail (newobj == NULL || GST_IS_OBJECT (newobj));
 412
 413 #ifdef DEBUG_REFCOUNT
 414   GST_CAT_LOG (GST_CAT_REFCOUNTING, "replace %s (%d) with %s (%d)",
 415       *oldobj ? GST_STR_NULL (GST_OBJECT_NAME (*oldobj)) : "(NONE)",
 416       *oldobj ? G_OBJECT (*oldobj)->ref_count : 0,
 417       newobj ? GST_STR_NULL (GST_OBJECT_NAME (newobj)) : "(NONE)",
 418       newobj ? G_OBJECT (newobj)->ref_count : 0);
 419 #endif
 420
 421   if (G_LIKELY (*oldobj != newobj)) {
 422     if (newobj)
 423       gst_object_ref (newobj);
 424     if (*oldobj)
 425       gst_object_unref (*oldobj);
 426
 427     *oldobj = newobj;
 428   }
 429 }
 430
 431 /* dispose is called when the object has to release all links
 432  * to other objects */
 433 static void
 434 gst_object_dispose (GObject * object)
 435 {
 436   GstObject *parent;
 437
 438   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "dispose");
 439
 440   GST_OBJECT_LOCK (object);
 441   if ((parent = GST_OBJECT_PARENT (object)))
 442     goto have_parent;
 443   GST_OBJECT_PARENT (object) = NULL;
 444   GST_OBJECT_UNLOCK (object);
 445
 446   parent_class->dispose (object);
 447
 448   return;
 449
 450   /* ERRORS */
 451 have_parent:
 452   {
 453     g_critical ("\nTrying to dispose object \"%s\", but it still has a "
 454         "parent \"%s\".\nYou need to let the parent manage the "
 455         "object instead of unreffing the object directly.\n",
 456         GST_OBJECT_NAME (object), GST_OBJECT_NAME (parent));
 457     GST_OBJECT_UNLOCK (object);
 458     /* ref the object again to revive it in this error case */
 459     object = gst_object_ref (object);
 460     return;
 461   }
 462 }
 463
 464 /* finalize is called when the object has to free its resources */
 465 static void
 466 gst_object_finalize (GObject * object)
 467 {
 468   GstObject *gstobject = GST_OBJECT (object);
 469
 470   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "finalize");
 471
 472   g_signal_handlers_destroy (object);
 473
 474   g_free (gstobject->name);
 475   g_mutex_free (gstobject->lock);
 476
 477 #ifndef GST_DISABLE_TRACE
 478   gst_alloc_trace_free (_gst_object_trace, object);
 479 #endif
 480
 481   parent_class->finalize (object);
 482 }
 483
 484 /* Changing a GObject property of a GstObject will result in "deep_notify"
 485  * signals being emitted by the object itself, as well as in each parent
 486  * object. This is so that an application can connect a listener to the
 487  * top-level bin to catch property-change notifications for all contained
 488  * elements.
 489  *
 490  * This function is not MT safe in glib < 2.8 so we need to lock it with a
 491  * classwide mutex in that case.
 492  *
 493  * MT safe.
 494  */
 495 static void
 496 gst_object_dispatch_properties_changed (GObject * object,
 497     guint n_pspecs, GParamSpec ** pspecs)
 498 {
 499   GstObject *gst_object, *parent, *old_parent;
 500   guint i;
 501   gchar *name, *debug_name;
 502   GstObjectClass *klass;
 503
 504   /* we fail when this is not a GstObject */
 505   g_return_if_fail (GST_IS_OBJECT (object));
 506
 507   klass = GST_OBJECT_GET_CLASS (object);
 508
 509   /* do the standard dispatching */
 510   G_OBJECT_CLASS (parent_class)->dispatch_properties_changed (object, n_pspecs,
 511       pspecs);
 512
 513   gst_object = GST_OBJECT_CAST (object);
 514   name = gst_object_get_name (gst_object);
 515   debug_name = GST_STR_NULL (name);
 516
 517   /* now let the parent dispatch those, too */
 518   parent = gst_object_get_parent (gst_object);
 519   while (parent) {
 520     /* for debugging ... */
 521     gchar *parent_name = gst_object_get_name (parent);
 522
 523 #ifndef GST_DISABLE_GST_DEBUG
 524     gchar *debug_parent_name = GST_STR_NULL (parent_name);
 525 #endif
 526
 527     /* need own category? */
 528     for (i = 0; i < n_pspecs; i++) {
 529       GST_CAT_LOG (GST_CAT_EVENT, "deep notification from %s to %s (%s)",
 530           debug_name, debug_parent_name, pspecs[i]->name);
 531
 532       g_signal_emit (parent, gst_object_signals[DEEP_NOTIFY],
 533           g_quark_from_string (pspecs[i]->name), GST_OBJECT_CAST (object),
 534           pspecs[i]);
 535     }
 536     g_free (parent_name);
 537
 538     old_parent = parent;
 539     parent = gst_object_get_parent (old_parent);
 540     gst_object_unref (old_parent);
 541   }
 542   g_free (name);
 543 }
 544
 545 /**
 546  * gst_object_default_deep_notify:
 547  * @object: the #GObject that signalled the notify.
 548  * @orig: a #GstObject that initiated the notify.
 549  * @pspec: a #GParamSpec of the property.
 550  * @excluded_props: a set of user-specified properties to exclude or
 551  *  NULL to show all changes.
 552  *
 553  * A default deep_notify signal callback for an object. The user data
 554  * should contain a pointer to an array of strings that should be excluded
 555  * from the notify. The default handler will print the new value of the property
 556  * using g_print.
 557  *
 558  * MT safe. This function grabs and releases @object's LOCK for getting its
 559  *          path string.
 560  */
 561 void
 562 gst_object_default_deep_notify (GObject * object, GstObject * orig,
 563     GParamSpec * pspec, gchar ** excluded_props)
 564 {
 565   GValue value = { 0, };        /* the important thing is that value.type = 0 */
 566   gchar *str = NULL;
 567   gchar *name = NULL;
 568
 569   if (pspec->flags & G_PARAM_READABLE) {
 570     /* let's not print these out for excluded properties... */
 571     while (excluded_props != NULL && *excluded_props != NULL) {
 572       if (strcmp (pspec->name, *excluded_props) == 0)
 573         return;
 574       excluded_props++;
 575     }
 576     g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (pspec));
 577     g_object_get_property (G_OBJECT (orig), pspec->name, &value);
 578
 579     if (G_IS_PARAM_SPEC_ENUM (pspec)) {
 580       GEnumValue *enum_value;
 581
 582       enum_value =
 583           g_enum_get_value (G_ENUM_CLASS (g_type_class_ref (pspec->value_type)),
 584           g_value_get_enum (&value));
 585
 586       str = g_strdup_printf ("%s (%d)", enum_value->value_nick,
 587           enum_value->value);
 588     } else {
 589       str = g_strdup_value_contents (&value);
 590     }
 591     name = gst_object_get_path_string (orig);
 592     g_print ("%s: %s = %s\n", name, pspec->name, str);
 593     g_free (name);
 594     g_free (str);
 595     g_value_unset (&value);
 596   } else {
 597     name = gst_object_get_path_string (orig);
 598     g_warning ("Parameter %s not readable in %s.", pspec->name, name);
 599     g_free (name);
 600   }
 601 }
 602
 603 static gboolean
 604 gst_object_set_name_default (GstObject * object)
 605 {
 606   const gchar *type_name;
 607   gint count;
 608   gchar *name, *tmp;
 609   gboolean result;
 610   GQuark q;
 611
 612   /* to ensure guaranteed uniqueness across threads, only one thread
 613    * may ever assign a name */
 614   G_LOCK (object_name_mutex);
 615
 616   if (!object_name_counts) {
 617     g_datalist_init (&object_name_counts);
 618   }
 619
 620   q = g_type_qname (G_OBJECT_TYPE (object));
 621   count = GPOINTER_TO_INT (g_datalist_id_get_data (&object_name_counts, q));
 622   g_datalist_id_set_data (&object_name_counts, q, GINT_TO_POINTER (count + 1));
 623
 624   G_UNLOCK (object_name_mutex);
 625
 626   /* GstFooSink -> foosinkN */
 627   type_name = g_quark_to_string (q);
 628   if (strncmp (type_name, "Gst", 3) == 0)
 629     type_name += 3;
 630   tmp = g_strdup_printf ("%s%d", type_name, count);
 631   name = g_ascii_strdown (tmp, strlen (tmp));
 632   g_free (tmp);
 633
 634   result = gst_object_set_name (object, name);
 635   g_free (name);
 636
 637   return result;
 638 }
 639
 640 /**
 641  * gst_object_set_name:
 642  * @object: a #GstObject
 643  * @name:   new name of object
 644  *
 645  * Sets the name of @object, or gives @object a guaranteed unique
 646  * name (if @name is NULL).
 647  * This function makes a copy of the provided name, so the caller
 648  * retains ownership of the name it sent.
 649  *
 650  * Returns: TRUE if the name could be set. Since Objects that have
 651  * a parent cannot be renamed, this function returns FALSE in those
 652  * cases.
 653  *
 654  * MT safe.  This function grabs and releases @object's LOCK.
 655  */
 656 gboolean
 657 gst_object_set_name (GstObject * object, const gchar * name)
 658 {
 659   gboolean result;
 660
 661   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
 662
 663   GST_OBJECT_LOCK (object);
 664
 665   /* parented objects cannot be renamed */
 666   if (G_UNLIKELY (object->parent != NULL))
 667     goto had_parent;
 668
 669   if (name != NULL) {
 670     g_free (object->name);
 671     object->name = g_strdup (name);
 672     GST_OBJECT_UNLOCK (object);
 673     result = TRUE;
 674   } else {
 675     GST_OBJECT_UNLOCK (object);
 676     result = gst_object_set_name_default (object);
 677   }
 678   return result;
 679
 680   /* error */
 681 had_parent:
 682   {
 683     GST_WARNING ("parented objects can't be renamed");
 684     GST_OBJECT_UNLOCK (object);
 685     return FALSE;
 686   }
 687 }
 688
 689 /**
 690  * gst_object_get_name:
 691  * @object: a #GstObject
 692  *
 693  * Returns a copy of the name of @object.
 694  * Caller should g_free() the return value after usage.
 695  * For a nameless object, this returns NULL, which you can safely g_free()
 696  * as well.
 697  *
 698  * Returns: the name of @object. g_free() after usage.
 699  *
 700  * MT safe. This function grabs and releases @object's LOCK.
 701  */
 702 gchar *
 703 gst_object_get_name (GstObject * object)
 704 {
 705   gchar *result = NULL;
 706
 707   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
 708
 709   GST_OBJECT_LOCK (object);
 710   result = g_strdup (object->name);
 711   GST_OBJECT_UNLOCK (object);
 712
 713   return result;
 714 }
 715
 716 /**
 717  * gst_object_set_name_prefix:
 718  * @object:      a #GstObject
 719  * @name_prefix: new name prefix of @object
 720  *
 721  * Sets the name prefix of @object to @name_prefix.
 722  * This function makes a copy of the provided name prefix, so the caller
 723  * retains ownership of the name prefix it sent.
 724  *
 725  * MT safe.  This function grabs and releases @object's LOCK.
 726  */
 727 void
 728 gst_object_set_name_prefix (GstObject * object, const gchar * name_prefix)
 729 {
 730   g_return_if_fail (GST_IS_OBJECT (object));
 731
 732   GST_OBJECT_LOCK (object);
 733   g_free (object->name_prefix);
 734   object->name_prefix = g_strdup (name_prefix); /* NULL gives NULL */
 735   GST_OBJECT_UNLOCK (object);
 736 }
 737
 738 /**
 739  * gst_object_get_name_prefix:
 740  * @object: a #GstObject
 741  *
 742  * Returns a copy of the name prefix of @object.
 743  * Caller should g_free() the return value after usage.
 744  * For a prefixless object, this returns NULL, which you can safely g_free()
 745  * as well.
 746  *
 747  * Returns: the name prefix of @object. g_free() after usage.
 748  *
 749  * MT safe. This function grabs and releases @object's LOCK.
 750  */
 751 gchar *
 752 gst_object_get_name_prefix (GstObject * object)
 753 {
 754   gchar *result = NULL;
 755
 756   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
 757
 758   GST_OBJECT_LOCK (object);
 759   result = g_strdup (object->name_prefix);
 760   GST_OBJECT_UNLOCK (object);
 761
 762   return result;
 763 }
 764
 765 /**
 766  * gst_object_set_parent:
 767  * @object: a #GstObject
 768  * @parent: new parent of object
 769  *
 770  * Sets the parent of @object to @parent. The object's reference count will
 771  * be incremented, and any floating reference will be removed (see gst_object_sink()).
 772  *
 773  * This function causes the parent-set signal to be emitted when the parent
 774  * was successfully set.
 775  *
 776  * Returns: TRUE if @parent could be set or FALSE when @object
 777  * already had a parent or @object and @parent are the same.
 778  *
 779  * MT safe. Grabs and releases @object's LOCK.
 780  */
 781 gboolean
 782 gst_object_set_parent (GstObject * object, GstObject * parent)
 783 {
 784   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
 785   g_return_val_if_fail (GST_IS_OBJECT (parent), FALSE);
 786   g_return_val_if_fail (object != parent, FALSE);
 787
 788   GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object,
 789       "set parent (ref and sink)");
 790
 791   GST_OBJECT_LOCK (object);
 792   if (G_UNLIKELY (object->parent != NULL))
 793     goto had_parent;
 794
 795   /* sink object, we don't call our own function because we don't
 796    * need to release/acquire the lock needlessly or touch the refcount
 797    * in the floating case. */
 798   object->parent = parent;
 799   if (G_LIKELY (GST_OBJECT_IS_FLOATING (object))) {
 800     GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "unsetting floating flag");
 801     GST_OBJECT_FLAG_UNSET (object, GST_OBJECT_FLOATING);
 802     GST_OBJECT_UNLOCK (object);
 803   } else {
 804     GST_OBJECT_UNLOCK (object);
 805     gst_object_ref (object);
 806   }
 807
 808   g_signal_emit (G_OBJECT (object), gst_object_signals[PARENT_SET], 0, parent);
 809
 810   return TRUE;
 811
 812   /* ERROR handling */
 813 had_parent:
 814   {
 815     GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object,
 816         "set parent failed, object already had a parent");
 817     GST_OBJECT_UNLOCK (object);
 818     return FALSE;
 819   }
 820 }
 821
 822 /**
 823  * gst_object_get_parent:
 824  * @object: a #GstObject
 825  *
 826  * Returns the parent of @object. This function increases the refcount
 827  * of the parent object so you should gst_object_unref() it after usage.
 828  *
 829  * Returns: parent of @object, this can be NULL if @object has no
 830  *   parent. unref after usage.
 831  *
 832  * MT safe. Grabs and releases @object's LOCK.
 833  */
 834 GstObject *
 835 gst_object_get_parent (GstObject * object)
 836 {
 837   GstObject *result = NULL;
 838
 839   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
 840
 841   GST_OBJECT_LOCK (object);
 842   result = object->parent;
 843   if (G_LIKELY (result))
 844     gst_object_ref (result);
 845   GST_OBJECT_UNLOCK (object);
 846
 847   return result;
 848 }
 849
 850 /**
 851  * gst_object_unparent:
 852  * @object: a #GstObject to unparent
 853  *
 854  * Clear the parent of @object, removing the associated reference.
 855  * This function decreases the refcount of @object.
 856  *
 857  * MT safe. Grabs and releases @object's lock.
 858  */
 859 void
 860 gst_object_unparent (GstObject * object)
 861 {
 862   GstObject *parent;
 863
 864   g_return_if_fail (GST_IS_OBJECT (object));
 865
 866   GST_OBJECT_LOCK (object);
 867   parent = object->parent;
 868
 869   if (G_LIKELY (parent != NULL)) {
 870     GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "unparent");
 871     object->parent = NULL;
 872     GST_OBJECT_UNLOCK (object);
 873
 874     g_signal_emit (G_OBJECT (object), gst_object_signals[PARENT_UNSET], 0,
 875         parent);
 876
 877     gst_object_unref (object);
 878   } else {
 879     GST_OBJECT_UNLOCK (object);
 880   }
 881 }
 882
 883 /**
 884  * gst_object_has_ancestor:
 885  * @object: a #GstObject to check
 886  * @ancestor: a #GstObject to check as ancestor
 887  *
 888  * Check if @object has an ancestor @ancestor somewhere up in
 889  * the hierarchy.
 890  *
 891  * Returns: TRUE if @ancestor is an ancestor of @object.
 892  *
 893  * MT safe. Grabs and releases @object's locks.
 894  */
 895 gboolean
 896 gst_object_has_ancestor (GstObject * object, GstObject * ancestor)
 897 {
 898   GstObject *parent;
 899   gboolean result = FALSE;
 900
 901   if (object == NULL)
 902     return FALSE;
 903
 904   if (object == ancestor)
 905     return TRUE;
 906
 907   parent = gst_object_get_parent (object);
 908   result = gst_object_has_ancestor (parent, ancestor);
 909   if (parent)
 910     gst_object_unref (parent);
 911
 912   return result;
 913 }
 914
 915 /**
 916  * gst_object_check_uniqueness:
 917  * @list: a list of #GstObject to check through
 918  * @name: the name to search for
 919  *
 920  * Checks to see if there is any object named @name in @list. This function
 921  * does not do any locking of any kind. You might want to protect the
 922  * provided list with the lock of the owner of the list. This function
 923  * will lock each #GstObject in the list to compare the name, so be
 924  * carefull when passing a list with a locked object.
 925  *
 926  * Returns: TRUE if a #GstObject named @name does not appear in @list,
 927  * FALSE if it does.
 928  *
 929  * MT safe. Grabs and releases the LOCK of each object in the list.
 930  */
 931 gboolean
 932 gst_object_check_uniqueness (GList * list, const gchar * name)
 933 {
 934   gboolean result = TRUE;
 935
 936   g_return_val_if_fail (name != NULL, FALSE);
 937
 938   for (; list; list = g_list_next (list)) {
 939     GstObject *child;
 940     gboolean eq;
 941
 942     child = GST_OBJECT (list->data);
 943
 944     GST_OBJECT_LOCK (child);
 945     eq = strcmp (GST_OBJECT_NAME (child), name) == 0;
 946     GST_OBJECT_UNLOCK (child);
 947
 948     if (G_UNLIKELY (eq)) {
 949       result = FALSE;
 950       break;
 951     }
 952   }
 953   return result;
 954 }
 955
 956
 957 #ifndef GST_DISABLE_LOADSAVE
 958 /**
 959  * gst_object_save_thyself:
 960  * @object: a #GstObject to save
 961  * @parent: The parent XML node to save @object into
 962  *
 963  * Saves @object into the parent XML node.
 964  *
 965  * Returns: the new xmlNodePtr with the saved object
 966  */
 967 xmlNodePtr
 968 gst_object_save_thyself (GstObject * object, xmlNodePtr parent)
 969 {
 970   GstObjectClass *oclass;
 971
 972   g_return_val_if_fail (GST_IS_OBJECT (object), parent);
 973   g_return_val_if_fail (parent != NULL, parent);
 974
 975   oclass = GST_OBJECT_GET_CLASS (object);
 976
 977   if (oclass->save_thyself)
 978     oclass->save_thyself (object, parent);
 979
 980   g_signal_emit (G_OBJECT (object), gst_object_signals[OBJECT_SAVED], 0,
 981       parent);
 982
 983   return parent;
 984 }
 985
 986 /**
 987  * gst_object_restore_thyself:
 988  * @object: a #GstObject to load into
 989  * @self: The XML node to load @object from
 990  *
 991  * Restores @object with the data from the parent XML node.
 992  */
 993 void
 994 gst_object_restore_thyself (GstObject * object, xmlNodePtr self)
 995 {
 996   GstObjectClass *oclass;
 997
 998   g_return_if_fail (GST_IS_OBJECT (object));
 999   g_return_if_fail (self != NULL);
1000
1001   oclass = GST_OBJECT_GET_CLASS (object);
1002
1003   if (oclass->restore_thyself)
1004     oclass->restore_thyself (object, self);
1005 }
1006
1007 static void
1008 gst_object_real_restore_thyself (GstObject * object, xmlNodePtr self)
1009 {
1010   g_return_if_fail (GST_IS_OBJECT (object));
1011   g_return_if_fail (self != NULL);
1012
1013   gst_class_signal_emit_by_name (object, "object_loaded", self);
1014 }
1015 #endif /* GST_DISABLE_LOADSAVE */
1016
1017 static void
1018 gst_object_set_property (GObject * object, guint prop_id,
1019     const GValue * value, GParamSpec * pspec)
1020 {
1021   GstObject *gstobject;
1022
1023   gstobject = GST_OBJECT (object);
1024
1025   switch (prop_id) {
1026     case ARG_NAME:
1027       gst_object_set_name (gstobject, g_value_get_string (value));
1028       break;
1029     default:
1030       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1031       break;
1032   }
1033 }
1034
1035 static void
1036 gst_object_get_property (GObject * object, guint prop_id,
1037     GValue * value, GParamSpec * pspec)
1038 {
1039   GstObject *gstobject;
1040
1041   gstobject = GST_OBJECT (object);
1042
1043   switch (prop_id) {
1044     case ARG_NAME:
1045       g_value_take_string (value, gst_object_get_name (gstobject));
1046       break;
1047     default:
1048       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1049       break;
1050   }
1051 }
1052
1053 /**
1054  * gst_object_get_path_string:
1055  * @object: a #GstObject
1056  *
1057  * Generates a string describing the path of @object in
1058  * the object hierarchy. Only useful (or used) for debugging.
1059  *
1060  * Returns: a string describing the path of @object. You must
1061  *          g_free() the string after usage.
1062  *
1063  * MT safe. Grabs and releases the #GstObject's LOCK for all objects
1064  *          in the hierarchy.
1065  */
1066 gchar *
1067 gst_object_get_path_string (GstObject * object)
1068 {
1069   GSList *parentage;
1070   GSList *parents;
1071   void *parent;
1072   gchar *prevpath, *path;
1073   gchar *component;
1074   gchar *separator;
1075
1076   /* ref object before adding to list */
1077   gst_object_ref (object);
1078   parentage = g_slist_prepend (NULL, object);
1079
1080   path = g_strdup ("");
1081
1082   /* first walk the object hierarchy to build a list of the parents,
1083    * be carefull here with refcounting. */
1084   do {
1085     if (GST_IS_OBJECT (object)) {
1086       parent = gst_object_get_parent (object);
1087       /* add parents to list, refcount remains increased while
1088        * we handle the object */
1089       if (parent)
1090         parentage = g_slist_prepend (parentage, parent);
1091     } else {
1092       break;
1093     }
1094     object = parent;
1095   } while (object != NULL);
1096
1097   /* then walk the parent list and print them out. we need to
1098    * decrease the refcounting on each element after we handled
1099    * it. */
1100   for (parents = parentage; parents; parents = g_slist_next (parents)) {
1101     if (GST_IS_OBJECT (parents->data)) {
1102       GstObject *item = GST_OBJECT_CAST (parents->data);
1103       GstObjectClass *oclass = GST_OBJECT_GET_CLASS (item);
1104
1105       component = gst_object_get_name (item);
1106       separator = oclass->path_string_separator;
1107       /* and unref now */
1108       gst_object_unref (item);
1109     } else {
1110       component = g_strdup_printf ("%p", parents->data);
1111       separator = "/";
1112     }
1113
1114     prevpath = path;
1115     path = g_strjoin (separator, prevpath, component, NULL);
1116     g_free (prevpath);
1117     g_free (component);
1118   }
1119
1120   g_slist_free (parentage);
1121
1122   return path;
1123 }
1124
1125
1126 struct _GstSignalObject
1127 {
1128   GObject object;
1129 };
1130
1131 struct _GstSignalObjectClass
1132 {
1133   GObjectClass parent_class;
1134
1135   /* signals */
1136 #ifndef GST_DISABLE_LOADSAVE
1137   void (*object_loaded) (GstSignalObject * object, GstObject * new,
1138       xmlNodePtr self);
1139 #endif
1140 };
1141
1142 static GType
1143 gst_signal_object_get_type (void)
1144 {
1145   static GType signal_object_type = 0;
1146
1147   if (G_UNLIKELY (signal_object_type == 0)) {
1148     static const GTypeInfo signal_object_info = {
1149       sizeof (GstSignalObjectClass),
1150       NULL,
1151       NULL,
1152       (GClassInitFunc) gst_signal_object_class_init,
1153       NULL,
1154       NULL,
1155       sizeof (GstSignalObject),
1156       0,
1157       (GInstanceInitFunc) gst_signal_object_init,
1158       NULL
1159     };
1160
1161     signal_object_type =
1162         g_type_register_static (G_TYPE_OBJECT, "GstSignalObject",
1163         &signal_object_info, 0);
1164   }
1165   return signal_object_type;
1166 }
1167
1168 static void
1169 gst_signal_object_class_init (GstSignalObjectClass * klass)
1170 {
1171   GObjectClass *gobject_class;
1172
1173   gobject_class = (GObjectClass *) klass;
1174
1175   parent_class = g_type_class_peek_parent (klass);
1176
1177 #ifndef GST_DISABLE_LOADSAVE
1178   gst_signal_object_signals[SO_OBJECT_LOADED] =
1179       g_signal_new ("object-loaded", G_TYPE_FROM_CLASS (klass),
1180       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstSignalObjectClass, object_loaded),
1181       NULL, NULL, gst_marshal_VOID__OBJECT_POINTER, G_TYPE_NONE, 2,
1182       G_TYPE_OBJECT, G_TYPE_POINTER);
1183 #endif
1184 }
1185
1186 static void
1187 gst_signal_object_init (GstSignalObject * object)
1188 {
1189 }
1190
1191 /**
1192  * gst_class_signal_connect
1193  * @klass: a #GstObjectClass to attach the signal to
1194  * @name: the name of the signal to attach to
1195  * @func: the signal function
1196  * @func_data: a pointer to user data
1197  *
1198  * Connect to a class signal.
1199  *
1200  * Returns: the signal id.
1201  */
1202 guint
1203 gst_class_signal_connect (GstObjectClass * klass,
1204     const gchar * name, gpointer func, gpointer func_data)
1205 {
1206   /* [0.11] func parameter needs to be changed to a GCallback *
1207    * doing so now would be an API break. */
1208   return g_signal_connect (klass->signal_object, name, G_CALLBACK (func),
1209       func_data);
1210 }
1211
1212 #ifndef GST_DISABLE_LOADSAVE
1213 /**
1214  * gst_class_signal_emit_by_name:
1215  * @object: a #GstObject that emits the signal
1216  * @name: the name of the signal to emit
1217  * @self: data for the signal
1218  *
1219  * emits the named class signal.
1220  */
1221 void
1222 gst_class_signal_emit_by_name (GstObject * object,
1223     const gchar * name, xmlNodePtr self)
1224 {
1225   GstObjectClass *oclass;
1226
1227   oclass = GST_OBJECT_GET_CLASS (object);
1228
1229   g_signal_emit_by_name (oclass->signal_object, name, object, self);
1230 }
1231
1232 #endif /* GST_DISABLE_LOADSAVE */