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