gst/gstobject.c

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