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: 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: pointer to a place of a #GstObject to replace
 413  * @newobj: a new #GstObject
 414  *
 415  * Unrefs the #GstObject pointed to by @oldobj, refs @newobj and
 416  * puts @newobj in *@oldobj. Be carefull when calling this
 417  * function, it does not take any locks. You might want to lock
 418  * the object owning @oldobj pointer before calling this
 419  * function.
 420  *
 421  * Make sure not to LOCK @oldobj because it might be unreffed
 422  * which could cause a deadlock when it is disposed.
 423  */
 424 void
 425 gst_object_replace (GstObject ** oldobj, GstObject * newobj)
 426 {
 427   g_return_if_fail (oldobj != NULL);
 428   g_return_if_fail (*oldobj == NULL || GST_IS_OBJECT (*oldobj));
 429   g_return_if_fail (newobj == NULL || GST_IS_OBJECT (newobj));
 430
 431 #ifdef DEBUG_REFCOUNT
 432   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "replace %p %s (%d) with %p %s (%d)",
 433       *oldobj, *oldobj ? GST_STR_NULL (GST_OBJECT_NAME (*oldobj)) : "(NONE)",
 434       *oldobj ? G_OBJECT (*oldobj)->ref_count : 0,
 435       newobj, newobj ? GST_STR_NULL (GST_OBJECT_NAME (newobj)) : "(NONE)",
 436       newobj ? G_OBJECT (newobj)->ref_count : 0);
 437 #endif
 438
 439   if (G_LIKELY (*oldobj != newobj)) {
 440     if (newobj)
 441       gst_object_ref (newobj);
 442     if (*oldobj)
 443       gst_object_unref (*oldobj);
 444
 445     *oldobj = newobj;
 446   }
 447 }
 448
 449 /* dispose is called when the object has to release all links
 450  * to other objects */
 451 static void
 452 gst_object_dispose (GObject * object)
 453 {
 454   GstObject *parent;
 455
 456   GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "dispose");
 457
 458   GST_OBJECT_LOCK (object);
 459   if ((parent = GST_OBJECT_PARENT (object)))
 460     goto have_parent;
 461   GST_OBJECT_PARENT (object) = NULL;
 462   GST_OBJECT_UNLOCK (object);
 463
 464   parent_class->dispose (object);
 465
 466   return;
 467
 468   /* ERRORS */
 469 have_parent:
 470   {
 471     g_critical ("\nTrying to dispose object \"%s\", but it still has a "
 472         "parent \"%s\".\nYou need to let the parent manage the "
 473         "object instead of unreffing the object directly.\n",
 474         GST_OBJECT_NAME (object), GST_OBJECT_NAME (parent));
 475     GST_OBJECT_UNLOCK (object);
 476     /* ref the object again to revive it in this error case */
 477     gst_object_ref (object);
 478     return;
 479   }
 480 }
 481
 482 /* finalize is called when the object has to free its resources */
 483 static void
 484 gst_object_finalize (GObject * object)
 485 {
 486   GstObject *gstobject = GST_OBJECT_CAST (object);
 487
 488   GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "finalize");
 489
 490   g_signal_handlers_destroy (object);
 491
 492   g_free (gstobject->name);
 493   g_mutex_free (gstobject->lock);
 494
 495 #ifndef GST_DISABLE_TRACE
 496   gst_alloc_trace_free (_gst_object_trace, object);
 497 #endif
 498
 499   parent_class->finalize (object);
 500 }
 501
 502 /* Changing a GObject property of a GstObject will result in "deep-notify"
 503  * signals being emitted by the object itself, as well as in each parent
 504  * object. This is so that an application can connect a listener to the
 505  * top-level bin to catch property-change notifications for all contained
 506  * elements.
 507  *
 508  * This function is not MT safe in glib < 2.8 so we need to lock it with a
 509  * classwide mutex in that case.
 510  *
 511  * MT safe.
 512  */
 513 static void
 514 gst_object_dispatch_properties_changed (GObject * object,
 515     guint n_pspecs, GParamSpec ** pspecs)
 516 {
 517   GstObject *gst_object, *parent, *old_parent;
 518   guint i;
 519 #ifndef GST_DISABLE_GST_DEBUG
 520   gchar *name = NULL;
 521   const gchar *debug_name;
 522 #endif
 523
 524   /* do the standard dispatching */
 525   parent_class->dispatch_properties_changed (object, n_pspecs, pspecs);
 526
 527   gst_object = GST_OBJECT_CAST (object);
 528 #ifndef GST_DISABLE_GST_DEBUG
 529   if (G_UNLIKELY (__gst_debug_min >= GST_LEVEL_LOG)) {
 530     name = gst_object_get_name (gst_object);
 531     debug_name = GST_STR_NULL (name);
 532   } else
 533     debug_name = "";
 534 #endif
 535
 536   /* now let the parent dispatch those, too */
 537   parent = gst_object_get_parent (gst_object);
 538   while (parent) {
 539     for (i = 0; i < n_pspecs; i++) {
 540       GST_CAT_LOG_OBJECT (GST_CAT_PROPERTIES, parent,
 541           "deep notification from %s (%s)", debug_name, pspecs[i]->name);
 542
 543       g_signal_emit (parent, gst_object_signals[DEEP_NOTIFY],
 544           g_quark_from_string (pspecs[i]->name), gst_object, pspecs[i]);
 545     }
 546
 547     old_parent = parent;
 548     parent = gst_object_get_parent (old_parent);
 549     gst_object_unref (old_parent);
 550   }
 551 #ifndef GST_DISABLE_GST_DEBUG
 552   g_free (name);
 553 #endif
 554 }
 555
 556 /**
 557  * gst_object_default_deep_notify:
 558  * @object: the #GObject that signalled the notify.
 559  * @orig: a #GstObject that initiated the notify.
 560  * @pspec: a #GParamSpec of the property.
 561  * @excluded_props: a set of user-specified properties to exclude or
 562  *  NULL to show all changes.
 563  *
 564  * A default deep_notify signal callback for an object. The user data
 565  * should contain a pointer to an array of strings that should be excluded
 566  * from the notify. The default handler will print the new value of the property
 567  * using g_print.
 568  *
 569  * MT safe. This function grabs and releases @object's LOCK for getting its
 570  *          path string.
 571  */
 572 void
 573 gst_object_default_deep_notify (GObject * object, GstObject * orig,
 574     GParamSpec * pspec, gchar ** excluded_props)
 575 {
 576   GValue value = { 0, };        /* the important thing is that value.type = 0 */
 577   gchar *str = NULL;
 578   gchar *name = NULL;
 579
 580   if (pspec->flags & G_PARAM_READABLE) {
 581     /* let's not print these out for excluded properties... */
 582     while (excluded_props != NULL && *excluded_props != NULL) {
 583       if (strcmp (pspec->name, *excluded_props) == 0)
 584         return;
 585       excluded_props++;
 586     }
 587     g_value_init (&value, pspec->value_type);
 588     g_object_get_property (G_OBJECT (orig), pspec->name, &value);
 589
 590     /* FIXME: handle flags */
 591     if (G_IS_PARAM_SPEC_ENUM (pspec)) {
 592       GEnumValue *enum_value;
 593       GEnumClass *klass = G_ENUM_CLASS (g_type_class_ref (pspec->value_type));
 594
 595       enum_value = g_enum_get_value (klass, g_value_get_enum (&value));
 596
 597       str = g_strdup_printf ("%s (%d)", enum_value->value_nick,
 598           enum_value->value);
 599       g_type_class_unref (klass);
 600     } else {
 601       str = g_strdup_value_contents (&value);
 602     }
 603     name = gst_object_get_path_string (orig);
 604     g_print ("%s: %s = %s\n", name, pspec->name, str);
 605     g_free (name);
 606     g_free (str);
 607     g_value_unset (&value);
 608   } else {
 609     name = gst_object_get_path_string (orig);
 610     g_warning ("Parameter %s not readable in %s.", pspec->name, name);
 611     g_free (name);
 612   }
 613 }
 614
 615 static gboolean
 616 gst_object_set_name_default (GstObject * object)
 617 {
 618   const gchar *type_name;
 619   gint count;
 620   gchar *name, *tmp;
 621   GQuark q;
 622
 623   /* to ensure guaranteed uniqueness across threads, only one thread
 624    * may ever assign a name */
 625   G_LOCK (object_name_mutex);
 626
 627   if (!object_name_counts) {
 628     g_datalist_init (&object_name_counts);
 629   }
 630
 631   q = g_type_qname (G_OBJECT_TYPE (object));
 632   count = GPOINTER_TO_INT (g_datalist_id_get_data (&object_name_counts, q));
 633   g_datalist_id_set_data (&object_name_counts, q, GINT_TO_POINTER (count + 1));
 634
 635   G_UNLOCK (object_name_mutex);
 636
 637   /* GstFooSink -> foosinkN */
 638   type_name = g_quark_to_string (q);
 639   if (strncmp (type_name, "Gst", 3) == 0)
 640     type_name += 3;
 641   tmp = g_strdup_printf ("%s%d", type_name, count);
 642   name = g_ascii_strdown (tmp, -1);
 643   g_free (tmp);
 644
 645   GST_OBJECT_LOCK (object);
 646   if (G_UNLIKELY (object->parent != NULL))
 647     goto had_parent;
 648   g_free (object->name);
 649   object->name = name;
 650
 651   GST_OBJECT_UNLOCK (object);
 652
 653   return TRUE;
 654
 655 had_parent:
 656   {
 657     g_free (name);
 658     GST_WARNING ("parented objects can't be renamed");
 659     GST_OBJECT_UNLOCK (object);
 660     return FALSE;
 661   }
 662 }
 663
 664 /**
 665  * gst_object_set_name:
 666  * @object: a #GstObject
 667  * @name:   new name of object
 668  *
 669  * Sets the name of @object, or gives @object a guaranteed unique
 670  * name (if @name is NULL).
 671  * This function makes a copy of the provided name, so the caller
 672  * retains ownership of the name it sent.
 673  *
 674  * Returns: TRUE if the name could be set. Since Objects that have
 675  * a parent cannot be renamed, this function returns FALSE in those
 676  * cases.
 677  *
 678  * MT safe.  This function grabs and releases @object's LOCK.
 679  */
 680 gboolean
 681 gst_object_set_name (GstObject * object, const gchar * name)
 682 {
 683   gboolean result;
 684
 685   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
 686
 687   GST_OBJECT_LOCK (object);
 688
 689   /* parented objects cannot be renamed */
 690   if (G_UNLIKELY (object->parent != NULL))
 691     goto had_parent;
 692
 693   if (name != NULL) {
 694     g_free (object->name);
 695     object->name = g_strdup (name);
 696     GST_OBJECT_UNLOCK (object);
 697     result = TRUE;
 698   } else {
 699     GST_OBJECT_UNLOCK (object);
 700     result = gst_object_set_name_default (object);
 701   }
 702   /* FIXME-0.11: this misses a g_object_notify (object, "name"); unless called
 703    * from gst_object_set_property.
 704    * Ideally remove such custom setters (or make it static).
 705    */
 706   return result;
 707
 708   /* error */
 709 had_parent:
 710   {
 711     GST_WARNING ("parented objects can't be renamed");
 712     GST_OBJECT_UNLOCK (object);
 713     return FALSE;
 714   }
 715 }
 716
 717 /**
 718  * gst_object_get_name:
 719  * @object: a #GstObject
 720  *
 721  * Returns a copy of the name of @object.
 722  * Caller should g_free() the return value after usage.
 723  * For a nameless object, this returns NULL, which you can safely g_free()
 724  * as well.
 725  *
 726  * Returns: the name of @object. g_free() after usage.
 727  *
 728  * MT safe. This function grabs and releases @object's LOCK.
 729  */
 730 gchar *
 731 gst_object_get_name (GstObject * object)
 732 {
 733   gchar *result = NULL;
 734
 735   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
 736
 737   GST_OBJECT_LOCK (object);
 738   result = g_strdup (object->name);
 739   GST_OBJECT_UNLOCK (object);
 740
 741   return result;
 742 }
 743
 744 /**
 745  * gst_object_set_name_prefix:
 746  * @object:      a #GstObject
 747  * @name_prefix: new name prefix of @object
 748  *
 749  * Sets the name prefix of @object to @name_prefix.
 750  * This function makes a copy of the provided name prefix, so the caller
 751  * retains ownership of the name prefix it sent.
 752  *
 753  * MT safe.  This function grabs and releases @object's LOCK.
 754  *
 755  * Deprecated: deprecated because the name prefix has never actually been used
 756  *     for anything.
 757  */
 758 #ifndef GST_REMOVE_DEPRECATED
 759 #ifdef GST_DISABLE_DEPRECATED
 760 void gst_object_set_name_prefix (GstObject * object, const gchar * name_prefix);
 761 #endif
 762 void
 763 gst_object_set_name_prefix (GstObject * object, const gchar * name_prefix)
 764 {
 765   g_return_if_fail (GST_IS_OBJECT (object));
 766
 767   GST_OBJECT_LOCK (object);
 768   g_free (object->name_prefix);
 769   object->name_prefix = g_strdup (name_prefix); /* NULL gives NULL */
 770   GST_OBJECT_UNLOCK (object);
 771 }
 772 #endif /* GST_REMOVE_DEPRECATED */
 773
 774 /**
 775  * gst_object_get_name_prefix:
 776  * @object: a #GstObject
 777  *
 778  * Returns a copy of the name prefix of @object.
 779  * Caller should g_free() the return value after usage.
 780  * For a prefixless object, this returns NULL, which you can safely g_free()
 781  * as well.
 782  *
 783  * Returns: the name prefix of @object. g_free() after usage.
 784  *
 785  * MT safe. This function grabs and releases @object's LOCK.
 786  *
 787  * Deprecated: deprecated because the name prefix has never actually been used
 788  *     for anything.
 789  */
 790 #ifndef GST_REMOVE_DEPRECATED
 791 #ifdef GST_DISABLE_DEPRECATED
 792 gchar *gst_object_get_name_prefix (GstObject * object);
 793 #endif
 794 gchar *
 795 gst_object_get_name_prefix (GstObject * object)
 796 {
 797   gchar *result = NULL;
 798
 799   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
 800
 801   GST_OBJECT_LOCK (object);
 802   result = g_strdup (object->name_prefix);
 803   GST_OBJECT_UNLOCK (object);
 804
 805   return result;
 806 }
 807 #endif /* GST_REMOVE_DEPRECATED */
 808
 809 /**
 810  * gst_object_set_parent:
 811  * @object: a #GstObject
 812  * @parent: new parent of object
 813  *
 814  * Sets the parent of @object to @parent. The object's reference count will
 815  * be incremented, and any floating reference will be removed (see gst_object_sink()).
 816  *
 817  * This function causes the parent-set signal to be emitted when the parent
 818  * was successfully set.
 819  *
 820  * Returns: TRUE if @parent could be set or FALSE when @object
 821  * already had a parent or @object and @parent are the same.
 822  *
 823  * MT safe. Grabs and releases @object's LOCK.
 824  */
 825 gboolean
 826 gst_object_set_parent (GstObject * object, GstObject * parent)
 827 {
 828   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
 829   g_return_val_if_fail (GST_IS_OBJECT (parent), FALSE);
 830   g_return_val_if_fail (object != parent, FALSE);
 831
 832   GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object,
 833       "set parent (ref and sink)");
 834
 835   GST_OBJECT_LOCK (object);
 836   if (G_UNLIKELY (object->parent != NULL))
 837     goto had_parent;
 838
 839   /* sink object, we don't call our own function because we don't
 840    * need to release/acquire the lock needlessly or touch the refcount
 841    * in the floating case. */
 842   object->parent = parent;
 843   if (G_LIKELY (GST_OBJECT_IS_FLOATING (object))) {
 844     GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object,
 845         "unsetting floating flag");
 846     GST_OBJECT_FLAG_UNSET (object, GST_OBJECT_FLOATING);
 847     GST_OBJECT_UNLOCK (object);
 848   } else {
 849     GST_OBJECT_UNLOCK (object);
 850     gst_object_ref (object);
 851   }
 852
 853   g_signal_emit (object, gst_object_signals[PARENT_SET], 0, parent);
 854
 855   return TRUE;
 856
 857   /* ERROR handling */
 858 had_parent:
 859   {
 860     GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object,
 861         "set parent failed, object already had a parent");
 862     GST_OBJECT_UNLOCK (object);
 863     return FALSE;
 864   }
 865 }
 866
 867 /**
 868  * gst_object_get_parent:
 869  * @object: a #GstObject
 870  *
 871  * Returns the parent of @object. This function increases the refcount
 872  * of the parent object so you should gst_object_unref() it after usage.
 873  *
 874  * Returns: parent of @object, this can be NULL if @object has no
 875  *   parent. unref after usage.
 876  *
 877  * MT safe. Grabs and releases @object's LOCK.
 878  */
 879 GstObject *
 880 gst_object_get_parent (GstObject * object)
 881 {
 882   GstObject *result = NULL;
 883
 884   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
 885
 886   GST_OBJECT_LOCK (object);
 887   result = object->parent;
 888   if (G_LIKELY (result))
 889     gst_object_ref (result);
 890   GST_OBJECT_UNLOCK (object);
 891
 892   return result;
 893 }
 894
 895 /**
 896  * gst_object_unparent:
 897  * @object: a #GstObject to unparent
 898  *
 899  * Clear the parent of @object, removing the associated reference.
 900  * This function decreases the refcount of @object.
 901  *
 902  * MT safe. Grabs and releases @object's lock.
 903  */
 904 void
 905 gst_object_unparent (GstObject * object)
 906 {
 907   GstObject *parent;
 908
 909   g_return_if_fail (GST_IS_OBJECT (object));
 910
 911   GST_OBJECT_LOCK (object);
 912   parent = object->parent;
 913
 914   if (G_LIKELY (parent != NULL)) {
 915     GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "unparent");
 916     object->parent = NULL;
 917     GST_OBJECT_UNLOCK (object);
 918
 919     g_signal_emit (object, gst_object_signals[PARENT_UNSET], 0, parent);
 920
 921     gst_object_unref (object);
 922   } else {
 923     GST_OBJECT_UNLOCK (object);
 924   }
 925 }
 926
 927 /**
 928  * gst_object_has_ancestor:
 929  * @object: a #GstObject to check
 930  * @ancestor: a #GstObject to check as ancestor
 931  *
 932  * Check if @object has an ancestor @ancestor somewhere up in
 933  * the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline.
 934  *
 935  * Returns: TRUE if @ancestor is an ancestor of @object.
 936  *
 937  * MT safe. Grabs and releases @object's locks.
 938  */
 939 gboolean
 940 gst_object_has_ancestor (GstObject * object, GstObject * ancestor)
 941 {
 942   GstObject *parent, *tmp;
 943
 944   if (!ancestor || !object)
 945     return FALSE;
 946
 947   parent = gst_object_ref (object);
 948   do {
 949     if (parent == ancestor) {
 950       gst_object_unref (parent);
 951       return TRUE;
 952     }
 953
 954     tmp = gst_object_get_parent (parent);
 955     gst_object_unref (parent);
 956     parent = tmp;
 957   } while (parent);
 958
 959   return FALSE;
 960 }
 961
 962 /**
 963  * gst_object_check_uniqueness:
 964  * @list: a list of #GstObject to check through
 965  * @name: the name to search for
 966  *
 967  * Checks to see if there is any object named @name in @list. This function
 968  * does not do any locking of any kind. You might want to protect the
 969  * provided list with the lock of the owner of the list. This function
 970  * will lock each #GstObject in the list to compare the name, so be
 971  * carefull when passing a list with a locked object.
 972  *
 973  * Returns: TRUE if a #GstObject named @name does not appear in @list,
 974  * FALSE if it does.
 975  *
 976  * MT safe. Grabs and releases the LOCK of each object in the list.
 977  */
 978 gboolean
 979 gst_object_check_uniqueness (GList * list, const gchar * name)
 980 {
 981   gboolean result = TRUE;
 982
 983   g_return_val_if_fail (name != NULL, FALSE);
 984
 985   for (; list; list = g_list_next (list)) {
 986     GstObject *child;
 987     gboolean eq;
 988
 989     child = GST_OBJECT_CAST (list->data);
 990
 991     GST_OBJECT_LOCK (child);
 992     eq = strcmp (GST_OBJECT_NAME (child), name) == 0;
 993     GST_OBJECT_UNLOCK (child);
 994
 995     if (G_UNLIKELY (eq)) {
 996       result = FALSE;
 997       break;
 998     }
 999   }
1000   return result;
1001 }
1002
1003
1004 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
1005 /**
1006  * gst_object_save_thyself:
1007  * @object: a #GstObject to save
1008  * @parent: The parent XML node to save @object into
1009  *
1010  * Saves @object into the parent XML node.
1011  *
1012  * Returns: the new xmlNodePtr with the saved object
1013  */
1014 GstXmlNodePtr
1015 gst_object_save_thyself (GstObject * object, GstXmlNodePtr parent)
1016 {
1017   GstObjectClass *oclass;
1018
1019   g_return_val_if_fail (GST_IS_OBJECT (object), parent);
1020   g_return_val_if_fail (parent != NULL, parent);
1021
1022   oclass = GST_OBJECT_GET_CLASS (object);
1023
1024   if (oclass->save_thyself)
1025     oclass->save_thyself (object, parent);
1026
1027   g_signal_emit (object, gst_object_signals[OBJECT_SAVED], 0, parent);
1028
1029   return parent;
1030 }
1031
1032 /**
1033  * gst_object_restore_thyself:
1034  * @object: a #GstObject to load into
1035  * @self: The XML node to load @object from
1036  *
1037  * Restores @object with the data from the parent XML node.
1038  */
1039 void
1040 gst_object_restore_thyself (GstObject * object, GstXmlNodePtr self)
1041 {
1042   GstObjectClass *oclass;
1043
1044   g_return_if_fail (GST_IS_OBJECT (object));
1045   g_return_if_fail (self != NULL);
1046
1047   oclass = GST_OBJECT_GET_CLASS (object);
1048
1049   if (oclass->restore_thyself)
1050     oclass->restore_thyself (object, self);
1051 }
1052
1053 static void
1054 gst_object_real_restore_thyself (GstObject * object, GstXmlNodePtr self)
1055 {
1056   g_return_if_fail (GST_IS_OBJECT (object));
1057   g_return_if_fail (self != NULL);
1058
1059   gst_class_signal_emit_by_name (object, "object_loaded", self);
1060 }
1061 #endif /* GST_DISABLE_LOADSAVE */
1062
1063 static void
1064 gst_object_set_property (GObject * object, guint prop_id,
1065     const GValue * value, GParamSpec * pspec)
1066 {
1067   GstObject *gstobject;
1068
1069   gstobject = GST_OBJECT_CAST (object);
1070
1071   switch (prop_id) {
1072     case ARG_NAME:
1073       gst_object_set_name (gstobject, g_value_get_string (value));
1074       break;
1075     default:
1076       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1077       break;
1078   }
1079 }
1080
1081 static void
1082 gst_object_get_property (GObject * object, guint prop_id,
1083     GValue * value, GParamSpec * pspec)
1084 {
1085   GstObject *gstobject;
1086
1087   gstobject = GST_OBJECT_CAST (object);
1088
1089   switch (prop_id) {
1090     case ARG_NAME:
1091       g_value_take_string (value, gst_object_get_name (gstobject));
1092       break;
1093     default:
1094       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1095       break;
1096   }
1097 }
1098
1099 /**
1100  * gst_object_get_path_string:
1101  * @object: a #GstObject
1102  *
1103  * Generates a string describing the path of @object in
1104  * the object hierarchy. Only useful (or used) for debugging.
1105  *
1106  * Returns: a string describing the path of @object. You must
1107  *          g_free() the string after usage.
1108  *
1109  * MT safe. Grabs and releases the #GstObject's LOCK for all objects
1110  *          in the hierarchy.
1111  */
1112 gchar *
1113 gst_object_get_path_string (GstObject * object)
1114 {
1115   GSList *parentage;
1116   GSList *parents;
1117   void *parent;
1118   gchar *prevpath, *path;
1119   const gchar *typename;
1120   gchar *component;
1121   const gchar *separator;
1122
1123   /* ref object before adding to list */
1124   gst_object_ref (object);
1125   parentage = g_slist_prepend (NULL, object);
1126
1127   path = g_strdup ("");
1128
1129   /* first walk the object hierarchy to build a list of the parents,
1130    * be carefull here with refcounting. */
1131   do {
1132     if (GST_IS_OBJECT (object)) {
1133       parent = gst_object_get_parent (object);
1134       /* add parents to list, refcount remains increased while
1135        * we handle the object */
1136       if (parent)
1137         parentage = g_slist_prepend (parentage, parent);
1138     } else {
1139       break;
1140     }
1141     object = parent;
1142   } while (object != NULL);
1143
1144   /* then walk the parent list and print them out. we need to
1145    * decrease the refcounting on each element after we handled
1146    * it. */
1147   for (parents = parentage; parents; parents = g_slist_next (parents)) {
1148     if (G_IS_OBJECT (parents->data)) {
1149       typename = G_OBJECT_TYPE_NAME (parents->data);
1150     } else {
1151       typename = NULL;
1152     }
1153     if (GST_IS_OBJECT (parents->data)) {
1154       GstObject *item = GST_OBJECT_CAST (parents->data);
1155       GstObjectClass *oclass = GST_OBJECT_GET_CLASS (item);
1156       gchar *objname = gst_object_get_name (item);
1157
1158       component = g_strdup_printf ("%s:%s", typename, objname);
1159       separator = oclass->path_string_separator;
1160       /* and unref now */
1161       gst_object_unref (item);
1162       g_free (objname);
1163     } else {
1164       if (typename) {
1165         component = g_strdup_printf ("%s:%p", typename, parents->data);
1166       } else {
1167         component = g_strdup_printf ("%p", parents->data);
1168       }
1169       separator = "/";
1170     }
1171
1172     prevpath = path;
1173     path = g_strjoin (separator, prevpath, component, NULL);
1174     g_free (prevpath);
1175     g_free (component);
1176   }
1177
1178   g_slist_free (parentage);
1179
1180   return path;
1181 }
1182
1183
1184 struct _GstSignalObject
1185 {
1186   GObject object;
1187 };
1188
1189 struct _GstSignalObjectClass
1190 {
1191   GObjectClass parent_class;
1192
1193   /* signals */
1194 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
1195   void (*object_loaded) (GstSignalObject * object, GstObject * new,
1196       GstXmlNodePtr self);
1197 #endif
1198 };
1199
1200 G_DEFINE_TYPE (GstSignalObject, gst_signal_object, G_TYPE_OBJECT);
1201
1202 static void
1203 gst_signal_object_class_init (GstSignalObjectClass * klass)
1204 {
1205   parent_class = g_type_class_peek_parent (klass);
1206
1207 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
1208   gst_signal_object_signals[SO_OBJECT_LOADED] =
1209       g_signal_new ("object-loaded", G_TYPE_FROM_CLASS (klass),
1210       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstSignalObjectClass, object_loaded),
1211       NULL, NULL, gst_marshal_VOID__OBJECT_POINTER, G_TYPE_NONE, 2,
1212       G_TYPE_OBJECT, G_TYPE_POINTER);
1213 #endif
1214 }
1215
1216 static void
1217 gst_signal_object_init (GstSignalObject * object)
1218 {
1219 }
1220
1221 /**
1222  * gst_class_signal_connect
1223  * @klass: a #GstObjectClass to attach the signal to
1224  * @name: the name of the signal to attach to
1225  * @func: the signal function
1226  * @func_data: a pointer to user data
1227  *
1228  * Connect to a class signal.
1229  *
1230  * Returns: the signal id.
1231  */
1232 guint
1233 gst_class_signal_connect (GstObjectClass * klass,
1234     const gchar * name, gpointer func, gpointer func_data)
1235 {
1236   /* [0.11] func parameter needs to be changed to a GCallback *
1237    * doing so now would be an API break. */
1238   return g_signal_connect (klass->signal_object, name, G_CALLBACK (func),
1239       func_data);
1240 }
1241
1242 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
1243 /**
1244  * gst_class_signal_emit_by_name:
1245  * @object: a #GstObject that emits the signal
1246  * @name: the name of the signal to emit
1247  * @self: data for the signal
1248  *
1249  * emits the named class signal.
1250  */
1251 void
1252 gst_class_signal_emit_by_name (GstObject * object,
1253     const gchar * name, GstXmlNodePtr self)
1254 {
1255   GstObjectClass *oclass;
1256
1257   oclass = GST_OBJECT_GET_CLASS (object);
1258
1259   g_signal_emit_by_name (oclass->signal_object, name, object, self);
1260 }
1261
1262 #endif /* GST_DISABLE_LOADSAVE */