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