c4f9d304363cf22756c39c3f5224c1a371d96de5
[glsdk/gstreamer0-10.git] / 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  * SECTION:gstobject
25  * @short_description: Base class for the GStreamer object hierarchy
26  *
27  * GstObject provides a root for the object hierarchy tree filed in by the
28  * GST library.  It is currently a thin wrapper on top of
29  * #GObject. It is an abstract class that is not very usable on its own.
30  *
31  * GstObject gives us basic refcounting, parenting functionality and locking.
32  * Most of the function are just extended for special gstreamer needs and can be
33  * found under the same name in the base class of GstObject which is GObject
34  * (e.g. g_object_ref() becomes gst_object_ref()).
35  *
36  * The most interesting difference between GstObject and GObject is the "floating"
37  * reference count. A GObject is created with a reference count of 1, owned by the
38  * creator of the GObject. (The owner of a reference is the code section that has
39  * the right to call gst_object_unref() in order to remove that reference.)
40  * A GstObject is created with a reference count of 1 also, but it isn't owned by
41  * anyone; calling gst_object_unref() on the newly-created GtkObject is incorrect.
42  * Instead, the initial reference count of a GstObject is "floating". The floating
43  * reference can be removed by anyone at any time, by calling gst_object_sink().
44  * gst_object_sink() does nothing if an object is already sunk (has no floating
45  * reference).
46  * 
47  * When you add a GstElement to its parent container, the parent container will do
48  * 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 (since
56  * it called gst_object_ref()), and the child element has no floating reference.
57  *
58  * The purpose of the floating reference is to keep the child element alive until
59  * you add it to a parent container:
60  * <informalexample>
61  * <programlisting>
62  *    element = gst_element_factory_make (factoryname, name);
63  *    // element has one floating reference to keep it alive
64  *    gst_bin_add (GST_BIN (bin), element);
65  *    // element has one non-floating reference owned by the container
66  * </programlisting>
67  * </informalexample>
68  *
69  * Another effect of this is, that calling gst_object_unref() on a bin object, will
70  * also destoy all the GstElement objects in it. The same is true for calling
71  * gst_bin_remove().
72  * 
73  * In contrast to GObject instances GstObject add a name property. The functions
74  * gst_object_set_name() and gst_object_get_name() are used to set/get the name
75  * of the object.
76  */
78 #include "gst_private.h"
80 #include "gstobject.h"
81 #include "gstmarshal.h"
82 #include "gstinfo.h"
83 #include "gstutils.h"
85 #ifndef GST_DISABLE_TRACE
86 #include "gsttrace.h"
87 #endif
89 #define DEBUG_REFCOUNT
90 #ifndef GST_HAVE_GLIB_2_8
91 #define REFCOUNT_HACK
92 #endif
94 /* Refcount hack: since glib is not threadsafe, the glib refcounter can be
95  * screwed up and the object can be freed unexpectedly. We use an evil hack
96  * to work around this problem. We set the glib refcount to a high value so
97  * that glib will never unref the object under realistic circumstances. Then
98  * we use our own atomic refcounting to do proper MT safe refcounting.
99  *
100  * The hack has several side-effect. At first you should use
101  * gst_object_ref/unref() whenever you can. Next when using g_value_set/get_object();
102  * you need to manually fix the refcount.
103  *
104  * A proper fix is of course to make the glib refcounting threadsafe which is
105  * planned. Update: atomic refcounting is now in glib >= 2.7.3
106  */
107 #ifdef REFCOUNT_HACK
108 #define PATCH_REFCOUNT(obj)    ((GObject*)(obj))->ref_count = 100000;
109 #define PATCH_REFCOUNT1(obj)    ((GObject*)(obj))->ref_count = 1;
110 #else
111 #define PATCH_REFCOUNT(obj)
112 #define PATCH_REFCOUNT1(obj)
113 #endif
115 /* Object signals and args */
116 enum
118   PARENT_SET,
119   PARENT_UNSET,
120 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
121   OBJECT_SAVED,
122 #endif
123   DEEP_NOTIFY,
124   LAST_SIGNAL
125 };
127 enum
129   ARG_0,
130   ARG_NAME
131       /* FILL ME */
132 };
134 enum
136   SO_OBJECT_LOADED,
137   SO_LAST_SIGNAL
138 };
140 GType _gst_object_type = 0;
141 static GHashTable *object_name_counts = NULL;
143 G_LOCK_DEFINE_STATIC (object_name_mutex);
145 typedef struct _GstSignalObject GstSignalObject;
146 typedef struct _GstSignalObjectClass GstSignalObjectClass;
148 static GType gst_signal_object_get_type (void);
149 static void gst_signal_object_class_init (GstSignalObjectClass * klass);
150 static void gst_signal_object_init (GstSignalObject * object);
152 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
153 static guint gst_signal_object_signals[SO_LAST_SIGNAL] = { 0 };
154 #endif
156 static void gst_object_class_init (GstObjectClass * klass);
157 static void gst_object_init (GTypeInstance * instance, gpointer g_class);
159 #ifndef GST_DISABLE_TRACE
160 static GObject *gst_object_constructor (GType type,
161     guint n_construct_properties, GObjectConstructParam * construct_params);
162 #endif
164 static void gst_object_set_property (GObject * object, guint prop_id,
165     const GValue * value, GParamSpec * pspec);
166 static void gst_object_get_property (GObject * object, guint prop_id,
167     GValue * value, GParamSpec * pspec);
168 static void gst_object_dispatch_properties_changed (GObject * object,
169     guint n_pspecs, GParamSpec ** pspecs);
171 static void gst_object_dispose (GObject * object);
172 static void gst_object_finalize (GObject * object);
174 static gboolean gst_object_set_name_default (GstObject * object,
175     const gchar * type_name);
177 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
178 static void gst_object_real_restore_thyself (GstObject * object,
179     xmlNodePtr self);
180 #endif
182 static GObjectClass *parent_class = NULL;
183 static guint gst_object_signals[LAST_SIGNAL] = { 0 };
185 GType
186 gst_object_get_type (void)
188   if (!_gst_object_type) {
189     static const GTypeInfo object_info = {
190       sizeof (GstObjectClass),
191       NULL,
192       NULL,
193       (GClassInitFunc) gst_object_class_init,
194       NULL,
195       NULL,
196       sizeof (GstObject),
197       0,
198       gst_object_init,
199       NULL
200     };
202     _gst_object_type =
203         g_type_register_static (G_TYPE_OBJECT, "GstObject", &object_info,
204         G_TYPE_FLAG_ABSTRACT);
205   }
206   return _gst_object_type;
209 static void
210 gst_object_class_init (GstObjectClass * klass)
212   GObjectClass *gobject_class;
214   gobject_class = (GObjectClass *) klass;
216   parent_class = g_type_class_ref (G_TYPE_OBJECT);
218   gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_object_set_property);
219   gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_object_get_property);
221   g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_NAME,
222       g_param_spec_string ("name", "Name", "The name of the object",
223           NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
225   /**
226    * GstObject::parent-set:
227    * @gstobject: the object which received the signal.
228    * @parent: the new parent
229    *
230    * Is emitted when the parent of an object is set.
231    */
232   gst_object_signals[PARENT_SET] =
233       g_signal_new ("parent-set", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
234       G_STRUCT_OFFSET (GstObjectClass, parent_set), NULL, NULL,
235       g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
237   /**
238    * GstObject::parent-unset:
239    * @gstobject: the object which received the signal.
240    * @parent: the old parent
241    *
242    * Is emitted when the parent of an object is unset.
243    */
244   gst_object_signals[PARENT_UNSET] =
245       g_signal_new ("parent-unset", G_TYPE_FROM_CLASS (klass),
246       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstObjectClass, parent_unset), NULL,
247       NULL, g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
249 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
250   /**
251    * GstObject::object-saved:
252    * @gstobject: the object which received the signal.
253    * @xml_node: the xmlNodePtr of the parent node
254    *
255    * Is trigered whenever a new object is saved to XML. You can connect to this
256    * signal to insert custom XML tags into the core XML.
257    */
258   /* FIXME This should be the GType of xmlNodePtr instead of G_TYPE_POINTER
259    *       (if libxml would use GObject)
260    */
261   gst_object_signals[OBJECT_SAVED] =
262       g_signal_new ("object-saved", G_TYPE_FROM_CLASS (klass),
263       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstObjectClass, object_saved), NULL,
264       NULL, g_cclosure_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_POINTER);
266   klass->restore_thyself = gst_object_real_restore_thyself;
267 #endif
269   /**
270    * GstObject::deep-notify:
271    * @gstobject: the object which received the signal.
272    * @prop_object: the object that originated the signal
273    * @prop: the property that changed
274    *
275    * The deep notify signal is used to be notified of property changes. It is
276    * typically attached to the toplevel bin to receive notifications from all
277    * the elements contained in that bin.
278    */
279   gst_object_signals[DEEP_NOTIFY] =
280       g_signal_new ("deep-notify", G_TYPE_FROM_CLASS (klass),
281       G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_DETAILED |
282       G_SIGNAL_NO_HOOKS, G_STRUCT_OFFSET (GstObjectClass, deep_notify), NULL,
283       NULL, gst_marshal_VOID__OBJECT_PARAM, G_TYPE_NONE, 2, G_TYPE_OBJECT,
284       G_TYPE_PARAM);
286   klass->path_string_separator = "/";
287   klass->lock = g_new0 (GStaticRecMutex, 1);
288   g_static_rec_mutex_init (klass->lock);
290   klass->signal_object = g_object_new (gst_signal_object_get_type (), NULL);
292   /* see the comments at gst_object_dispatch_properties_changed */
293   gobject_class->dispatch_properties_changed
294       = GST_DEBUG_FUNCPTR (gst_object_dispatch_properties_changed);
296   gobject_class->dispose = gst_object_dispose;
297   gobject_class->finalize = gst_object_finalize;
298 #ifndef GST_DISABLE_TRACE
299   gobject_class->constructor = gst_object_constructor;
300 #endif
303 static void
304 gst_object_init (GTypeInstance * instance, gpointer g_class)
306   GstObject *object = GST_OBJECT (instance);
308   object->lock = g_mutex_new ();
309   object->parent = NULL;
310   object->name = NULL;
311   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p new", object);
312 #ifdef REFCOUNT_HACK
313   gst_atomic_int_set (&object->refcount, 1);
314 #endif
315   PATCH_REFCOUNT (object);
317   object->flags = 0;
318   GST_FLAG_SET (object, GST_OBJECT_FLOATING);
321 #ifndef GST_DISABLE_TRACE
322 static GObject *
323 gst_object_constructor (GType type, guint n_construct_properties,
324     GObjectConstructParam * construct_params)
326   const gchar *name;
327   GstAllocTrace *trace;
328   GObject *obj =
329       G_OBJECT_CLASS (parent_class)->constructor (type, n_construct_properties,
330       construct_params);
332   name = g_type_name (type);
334   trace = gst_alloc_trace_get (name);
335   if (!trace) {
336     trace = gst_alloc_trace_register (name);
337   }
338   gst_alloc_trace_new (trace, obj);
340   return obj;
342 #endif
343 /**
344  * gst_object_ref:
345  * @object: GstObject to reference
346  *
347  * Increments the refence count on the object. This function
348  * does not take the lock on the object because it relies on
349  * atomic refcounting.
350  *
351  * This object returns the input parameter to ease writing
352  * constructs like :
353  *  result = gst_object_ref (object->parent);
354  *
355  * Returns: A pointer to the object
356  */
357 gpointer
358 gst_object_ref (gpointer object)
360   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
362 #ifdef DEBUG_REFCOUNT
363 #ifdef REFCOUNT_HACK
364   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p ref %d->%d",
365       object,
366       GST_OBJECT_REFCOUNT_VALUE (object),
367       GST_OBJECT_REFCOUNT_VALUE (object) + 1);
368 #else
369   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p ref %d->%d",
370       object,
371       ((GObject *) object)->ref_count, ((GObject *) object)->ref_count + 1);
372 #endif
373 #endif
375 #ifdef REFCOUNT_HACK
376   g_atomic_int_inc (&((GstObject *) object)->refcount);
377   PATCH_REFCOUNT (object);
378 #else
379   /* FIXME, not MT safe because glib is not MT safe */
380   g_object_ref (object);
381 #endif
383   return object;
386 /**
387  * gst_object_unref:
388  * @object: GstObject to unreference
389  *
390  * Decrements the refence count on the object.  If reference count hits
391  * zero, destroy the object. This function does not take the lock
392  * on the object as it relies on atomic refcounting.
393  *
394  * The unref method should never be called with the LOCK held since
395  * this might deadlock the dispose function.
396  */
397 void
398 gst_object_unref (gpointer object)
400   g_return_if_fail (GST_IS_OBJECT (object));
402 #ifdef REFCOUNT_HACK
403   g_return_if_fail (GST_OBJECT_REFCOUNT_VALUE (object) > 0);
404 #else
405   g_return_if_fail (((GObject *) object)->ref_count > 0);
406 #endif
408 #ifdef DEBUG_REFCOUNT
409 #ifdef REFCOUNT_HACK
410   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p unref %d->%d",
411       object,
412       GST_OBJECT_REFCOUNT_VALUE (object),
413       GST_OBJECT_REFCOUNT_VALUE (object) - 1);
414 #else
415   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p unref %d->%d",
416       object,
417       ((GObject *) object)->ref_count, ((GObject *) object)->ref_count - 1);
418 #endif
419 #endif
421 #ifdef REFCOUNT_HACK
422   if (G_UNLIKELY (g_atomic_int_dec_and_test (&((GstObject *) object)->
423               refcount))) {
424     PATCH_REFCOUNT1 (object);
425     g_object_unref (object);
426   } else {
427     PATCH_REFCOUNT (object);
428   }
429 #else
430   /* FIXME, not MT safe because glib is not MT safe */
431   g_object_unref (object);
432 #endif
435 /**
436  * gst_object_sink:
437  * @object: GstObject to sink
438  *
439  * Removes floating reference on an object.  Any newly created object has
440  * a refcount of 1 and is FLOATING.  This function should be used when
441  * creating a new object to symbolically 'take ownership' of the object.
442  * Use #gst_object_set_parent to have this done for you.
443  *
444  * MT safe. This function grabs and releases the object lock.
445  */
446 void
447 gst_object_sink (gpointer object)
449   g_return_if_fail (GST_IS_OBJECT (object));
451   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "sink");
453   GST_LOCK (object);
454   if (G_LIKELY (GST_OBJECT_IS_FLOATING (object))) {
455     GST_FLAG_UNSET (object, GST_OBJECT_FLOATING);
456     GST_UNLOCK (object);
457     gst_object_unref (object);
458   } else {
459     GST_UNLOCK (object);
460   }
463 /**
464  * gst_object_replace:
465  * @oldobj: pointer to place of old GstObject
466  * @newobj: new GstObject
467  *
468  * Unrefs the object pointer to by oldobj, refs the newobj and
469  * puts the newobj in *oldobj. Be carefull when calling this
470  * function, it does not take any locks. You might want to lock
471  * the object owning the oldobj pointer before calling this
472  * function.
473  *
474  * Make sure not to LOCK the oldobj because it might be unreffed
475  * which could cause a deadlock when it is disposed.
476  */
477 void
478 gst_object_replace (GstObject ** oldobj, GstObject * newobj)
480   g_return_if_fail (oldobj != NULL);
481   g_return_if_fail (*oldobj == NULL || GST_IS_OBJECT (*oldobj));
482   g_return_if_fail (newobj == NULL || GST_IS_OBJECT (newobj));
484 #ifdef DEBUG_REFCOUNT
485 #ifdef REFCOUNT_HACK
486   GST_CAT_LOG (GST_CAT_REFCOUNTING, "replace %s (%d) with %s (%d)",
487       *oldobj ? GST_STR_NULL (GST_OBJECT_NAME (*oldobj)) : "(NONE)",
488       *oldobj ? GST_OBJECT_REFCOUNT_VALUE (*oldobj) : 0,
489       newobj ? GST_STR_NULL (GST_OBJECT_NAME (newobj)) : "(NONE)",
490       newobj ? GST_OBJECT_REFCOUNT_VALUE (newobj) : 0);
491 #else
492   GST_CAT_LOG (GST_CAT_REFCOUNTING, "replace %s (%d) with %s (%d)",
493       *oldobj ? GST_STR_NULL (GST_OBJECT_NAME (*oldobj)) : "(NONE)",
494       *oldobj ? G_OBJECT (*oldobj)->ref_count : 0,
495       newobj ? GST_STR_NULL (GST_OBJECT_NAME (newobj)) : "(NONE)",
496       newobj ? G_OBJECT (newobj)->ref_count : 0);
497 #endif
498 #endif
500   if (G_LIKELY (*oldobj != newobj)) {
501     if (newobj)
502       gst_object_ref (newobj);
503     if (*oldobj)
504       gst_object_unref (*oldobj);
506     *oldobj = newobj;
507   }
510 /* dispose is called when the object has to release all links
511  * to other objects */
512 static void
513 gst_object_dispose (GObject * object)
515   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "dispose");
517   GST_LOCK (object);
518   GST_OBJECT_PARENT (object) = NULL;
519   GST_UNLOCK (object);
521   /* need to patch refcount so it is finalized */
522   PATCH_REFCOUNT1 (object);
524   parent_class->dispose (object);
527 /* finalize is called when the object has to free its resources */
528 static void
529 gst_object_finalize (GObject * object)
531   GstObject *gstobject = GST_OBJECT (object);
533   GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "finalize");
535   g_signal_handlers_destroy (object);
537   g_free (gstobject->name);
538   g_mutex_free (gstobject->lock);
540 #ifndef GST_DISABLE_TRACE
541   {
542     const gchar *name;
543     GstAllocTrace *trace;
545     name = g_type_name (G_OBJECT_TYPE (object));
546     trace = gst_alloc_trace_get (name);
547     g_assert (trace);
548     gst_alloc_trace_free (trace, object);
549   }
550 #endif
552   parent_class->finalize (object);
555 /* Changing a GObject property of a GstObject will result in "deep_notify"
556  * signals being emitted by the object itself, as well as in each parent
557  * object. This is so that an application can connect a listener to the
558  * top-level bin to catch property-change notifications for all contained
559  * elements. 
560  *
561  * This function is not MT safe in glib so we need to lock it with a 
562  * classwide mutex.
563  *
564  * MT safe.
565  */
566 static void
567 gst_object_dispatch_properties_changed (GObject * object,
568     guint n_pspecs, GParamSpec ** pspecs)
570   GstObject *gst_object, *parent, *old_parent;
571   guint i;
572   gchar *name, *debug_name;
573   GstObjectClass *klass;
575   /* we fail when this is not a GstObject */
576   g_return_if_fail (GST_IS_OBJECT (object));
578   klass = GST_OBJECT_GET_CLASS (object);
580   GST_CLASS_LOCK (klass);
581   /* do the standard dispatching */
582   PATCH_REFCOUNT (object);
583   G_OBJECT_CLASS (parent_class)->dispatch_properties_changed (object, n_pspecs,
584       pspecs);
585   PATCH_REFCOUNT (object);
587   gst_object = GST_OBJECT_CAST (object);
588   name = gst_object_get_name (gst_object);
589   debug_name = GST_STR_NULL (name);
591   /* now let the parent dispatch those, too */
592   parent = gst_object_get_parent (gst_object);
593   while (parent) {
594     /* for debugging ... */
595     gchar *parent_name = gst_object_get_name (parent);
597 #ifndef GST_DISABLE_GST_DEBUG
598     gchar *debug_parent_name = GST_STR_NULL (parent_name);
599 #endif
601     /* need own category? */
602     for (i = 0; i < n_pspecs; i++) {
603       GST_CAT_LOG (GST_CAT_EVENT, "deep notification from %s to %s (%s)",
604           debug_name, debug_parent_name, pspecs[i]->name);
606       /* not MT safe because of glib, fixed by taking class lock higher up */
607       PATCH_REFCOUNT (parent);
608       PATCH_REFCOUNT (object);
609       g_signal_emit (parent, gst_object_signals[DEEP_NOTIFY],
610           g_quark_from_string (pspecs[i]->name), GST_OBJECT_CAST (object),
611           pspecs[i]);
612       PATCH_REFCOUNT (parent);
613       PATCH_REFCOUNT (object);
614     }
615     g_free (parent_name);
617     old_parent = parent;
618     parent = gst_object_get_parent (old_parent);
619     gst_object_unref (old_parent);
620   }
621   g_free (name);
622   GST_CLASS_UNLOCK (klass);
625 /** 
626  * gst_object_default_deep_notify:
627  * @object: the #GObject that signalled the notify.
628  * @orig: a #GstObject that initiated the notify.
629  * @pspec: a #GParamSpec of the property.
630  * @excluded_props: a set of user-specified properties to exclude or
631  *  NULL to show all changes.
632  *
633  * A default deep_notify signal callback for an element. The user data 
634  * should contain a pointer to an array of strings that should be excluded 
635  * from the notify. The default handler will print the new value of the property 
636  * using g_print.
637  *
638  * MT safe. This function grabs and releases the object's LOCK or getting the
639  *          path string of the object.
640  */
641 void
642 gst_object_default_deep_notify (GObject * object, GstObject * orig,
643     GParamSpec * pspec, gchar ** excluded_props)
645   GValue value = { 0, };        /* the important thing is that value.type = 0 */
646   gchar *str = NULL;
647   gchar *name = NULL;
649   if (pspec->flags & G_PARAM_READABLE) {
650     /* let's not print these out for excluded properties... */
651     while (excluded_props != NULL && *excluded_props != NULL) {
652       if (strcmp (pspec->name, *excluded_props) == 0)
653         return;
654       excluded_props++;
655     }
656     g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (pspec));
657     g_object_get_property (G_OBJECT (orig), pspec->name, &value);
659     if (G_IS_PARAM_SPEC_ENUM (pspec)) {
660       GEnumValue *enum_value;
662       enum_value =
663           g_enum_get_value (G_ENUM_CLASS (g_type_class_ref (pspec->value_type)),
664           g_value_get_enum (&value));
666       str = g_strdup_printf ("%s (%d)", enum_value->value_nick,
667           enum_value->value);
668     } else {
669       str = g_strdup_value_contents (&value);
670     }
671     name = gst_object_get_path_string (orig);
672     g_print ("%s: %s = %s\n", name, pspec->name, str);
673     g_free (name);
674     g_free (str);
675     g_value_unset (&value);
676   } else {
677     name = gst_object_get_path_string (orig);
678     g_warning ("Parameter %s not readable in %s.", pspec->name, name);
679     g_free (name);
680   }
683 static gboolean
684 gst_object_set_name_default (GstObject * object, const gchar * type_name)
686   gint count;
687   gchar *name, *tmp;
688   gboolean result;
690   /* to ensure guaranteed uniqueness across threads, only one thread
691    * may ever assign a name */
692   G_LOCK (object_name_mutex);
694   if (!object_name_counts) {
695     object_name_counts = g_hash_table_new_full (g_str_hash, g_str_equal,
696         g_free, NULL);
697   }
699   count = GPOINTER_TO_INT (g_hash_table_lookup (object_name_counts, type_name));
700   g_hash_table_insert (object_name_counts, g_strdup (type_name),
701       GINT_TO_POINTER (count + 1));
703   G_UNLOCK (object_name_mutex);
705   /* GstFooSink -> foosinkN */
706   if (strncmp (type_name, "Gst", 3) == 0)
707     type_name += 3;
708   tmp = g_strdup_printf ("%s%d", type_name, count);
709   name = g_ascii_strdown (tmp, strlen (tmp));
710   g_free (tmp);
712   result = gst_object_set_name (object, name);
713   g_free (name);
715   return result;
718 /**
719  * gst_object_set_name:
720  * @object: a #GstObject to set the name of
721  * @name:   new name of object
722  *
723  * Sets the name of the object, or gives the object a guaranteed unique
724  * name (if @name is NULL).
725  * This function makes a copy of the provided name, so the caller
726  * retains ownership of the name it sent.
727  *
728  * Returns: TRUE if the name could be set. Objects that have
729  * a parent cannot be renamed.
730  *
731  * MT safe.  This function grabs and releases the object's LOCK.
732  */
733 gboolean
734 gst_object_set_name (GstObject * object, const gchar * name)
736   gboolean result;
738   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
740   GST_LOCK (object);
742   /* parented objects cannot be renamed */
743   if (G_UNLIKELY (object->parent != NULL))
744     goto had_parent;
746   if (name != NULL) {
747     g_free (object->name);
748     object->name = g_strdup (name);
749     GST_UNLOCK (object);
750     result = TRUE;
751   } else {
752     GST_UNLOCK (object);
753     result = gst_object_set_name_default (object, G_OBJECT_TYPE_NAME (object));
754   }
755   return result;
757   /* error */
758 had_parent:
759   {
760     GST_UNLOCK (object);
761     return FALSE;
762   }
765 /**
766  * gst_object_get_name:
767  * @object: a #GstObject to get the name of
768  *
769  * Returns a copy of the name of the object.
770  * Caller should g_free() the return value after usage.
771  * For a nameless object, this returns NULL, which you can safely g_free()
772  * as well.
773  *
774  * Returns: the name of the object. g_free() after usage.
775  *
776  * MT safe. This function grabs and releases the object's LOCK.
777  */
778 gchar *
779 gst_object_get_name (GstObject * object)
781   gchar *result = NULL;
783   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
785   GST_LOCK (object);
786   result = g_strdup (object->name);
787   GST_UNLOCK (object);
789   return result;
792 /**
793  * gst_object_set_name_prefix:
794  * @object:      a #GstObject to set the name prefix of
795  * @name_prefix: new name prefix of object
796  *
797  * Sets the name prefix of the object.
798  * This function makes a copy of the provided name prefix, so the caller
799  * retains ownership of the name prefix it sent.
800  *
801  * MT safe.  This function grabs and releases the object's LOCK.
802  */
803 void
804 gst_object_set_name_prefix (GstObject * object, const gchar * name_prefix)
806   g_return_if_fail (GST_IS_OBJECT (object));
808   GST_LOCK (object);
809   g_free (object->name_prefix);
810   object->name_prefix = g_strdup (name_prefix); /* NULL gives NULL */
811   GST_UNLOCK (object);
814 /**
815  * gst_object_get_name_prefix:
816  * @object: a #GstObject to get the name prefix of
817  *
818  * Returns a copy of the name prefix of the object.
819  * Caller should g_free() the return value after usage.
820  * For a prefixless object, this returns NULL, which you can safely g_free()
821  * as well.
822  *
823  * Returns: the name prefix of the object. g_free() after usage.
824  *
825  * MT safe. This function grabs and releases the object's LOCK.
826  */
827 gchar *
828 gst_object_get_name_prefix (GstObject * object)
830   gchar *result = NULL;
832   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
834   GST_LOCK (object);
835   result = g_strdup (object->name_prefix);
836   GST_UNLOCK (object);
838   return result;
841 /**
842  * gst_object_set_parent:
843  * @object: GstObject to set parent of
844  * @parent: new parent of object
845  *
846  * Sets the parent of @object. The object's reference count will be incremented,
847  * and any floating reference will be removed (see gst_object_sink()).
848  *
849  * Causes the parent-set signal to be emitted.
850  *
851  * Returns: TRUE if the parent could be set or FALSE when the object
852  * already had a parent, the object and parent are the same or wrong
853  * parameters were provided.
854  *
855  * MT safe. Grabs and releases the object's LOCK.
856  */
857 gboolean
858 gst_object_set_parent (GstObject * object, GstObject * parent)
860   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
861   g_return_val_if_fail (GST_IS_OBJECT (parent), FALSE);
862   g_return_val_if_fail (object != parent, FALSE);
864   GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object,
865       "set parent (ref and sink)");
867   GST_LOCK (object);
868   if (G_UNLIKELY (object->parent != NULL))
869     goto had_parent;
871   /* sink object, we don't call our own function because we don't
872    * need to release/acquire the lock needlessly or touch the refcount
873    * in the floating case. */
874   object->parent = parent;
875   if (G_LIKELY (GST_OBJECT_IS_FLOATING (object))) {
876     GST_FLAG_UNSET (object, GST_OBJECT_FLOATING);
877     GST_UNLOCK (object);
878   } else {
879     GST_UNLOCK (object);
880     gst_object_ref (object);
881   }
883   g_signal_emit (G_OBJECT (object), gst_object_signals[PARENT_SET], 0, parent);
885   return TRUE;
887   /* ERROR handling */
888 had_parent:
889   {
890     GST_UNLOCK (object);
891     return FALSE;
892   }
895 /**
896  * gst_object_get_parent:
897  * @object: GstObject to get parent of
898  *
899  * Returns the parent of @object. This function increases the refcount
900  * of the parent object so you should gst_object_unref() it after usage.
901  *
902  * Returns: parent of the object, this can be NULL if the object has no
903  *   parent. unref after usage.
904  *
905  * MT safe. Grabs and releases the object's LOCK.
906  */
907 GstObject *
908 gst_object_get_parent (GstObject * object)
910   GstObject *result = NULL;
912   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
914   GST_LOCK (object);
915   result = object->parent;
916   if (G_LIKELY (result))
917     gst_object_ref (result);
918   GST_UNLOCK (object);
920   return result;
923 /**
924  * gst_object_unparent:
925  * @object: GstObject to unparent
926  *
927  * Clear the parent of @object, removing the associated reference.
928  * This function decreases the refcount of the object so the object
929  * might not point to valid memory anymore after calling this function.
930  *
931  * MT safe. Grabs and releases the object's lock.
932  */
933 void
934 gst_object_unparent (GstObject * object)
936   GstObject *parent;
938   g_return_if_fail (GST_IS_OBJECT (object));
940   GST_LOCK (object);
941   parent = object->parent;
943   if (G_LIKELY (parent != NULL)) {
944     GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "unparent");
945     object->parent = NULL;
946     GST_UNLOCK (object);
948     g_signal_emit (G_OBJECT (object), gst_object_signals[PARENT_UNSET], 0,
949         parent);
951     gst_object_unref (object);
952   } else {
953     GST_UNLOCK (object);
954   }
957 /**
958  * gst_object_has_ancestor:
959  * @object: GstObject to check
960  * @ancestor: GstObject to check as ancestor
961  *
962  * Check if @object has an ancestor @ancestor somewhere up in
963  * the hierarchy.
964  *
965  * Returns: TRUE if @ancestor is an ancestor of @object.
966  *
967  * MT safe. Grabs and releases the object's locks.
968  */
969 gboolean
970 gst_object_has_ancestor (GstObject * object, GstObject * ancestor)
972   GstObject *parent;
973   gboolean result = FALSE;
975   if (object == NULL)
976     return FALSE;
978   if (object == ancestor)
979     return TRUE;
981   parent = gst_object_get_parent (object);
982   result = gst_object_has_ancestor (parent, ancestor);
983   if (parent)
984     gst_object_unref (parent);
986   return result;
989 /**
990  * gst_object_check_uniqueness:
991  * @list: a list of #GstObject to check through
992  * @name: the name to search for
993  *
994  * Checks to see if there is any object named @name in @list. This function
995  * does not do any locking of any kind. You might want to protect the
996  * provided list with the lock of the owner of the list. This function
997  * will lock each GstObject in the list to compare the name, so be
998  * carefull when passing a list with a locked object.
999  *
1000  * Returns: TRUE if the name does not appear in the list, FALSE if it does.
1001  *
1002  * MT safe. Grabs and releases the LOCK of each object in the list.
1003  */
1004 gboolean
1005 gst_object_check_uniqueness (GList * list, const gchar * name)
1007   gboolean result = TRUE;
1009   g_return_val_if_fail (name != NULL, FALSE);
1011   for (; list; list = g_list_next (list)) {
1012     GstObject *child;
1013     gboolean eq;
1015     child = GST_OBJECT (list->data);
1017     GST_LOCK (child);
1018     eq = strcmp (GST_OBJECT_NAME (child), name) == 0;
1019     GST_UNLOCK (child);
1021     if (G_UNLIKELY (eq)) {
1022       result = FALSE;
1023       break;
1024     }
1025   }
1026   return result;
1030 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
1031 /**
1032  * gst_object_save_thyself:
1033  * @object: GstObject to save
1034  * @parent: The parent XML node to save the object into
1035  *
1036  * Saves the given object into the parent XML node.
1037  *
1038  * Returns: the new xmlNodePtr with the saved object
1039  */
1040 xmlNodePtr
1041 gst_object_save_thyself (GstObject * object, xmlNodePtr parent)
1043   GstObjectClass *oclass;
1045   g_return_val_if_fail (GST_IS_OBJECT (object), parent);
1046   g_return_val_if_fail (parent != NULL, parent);
1048   oclass = GST_OBJECT_GET_CLASS (object);
1050   if (oclass->save_thyself)
1051     oclass->save_thyself (object, parent);
1053   g_signal_emit (G_OBJECT (object), gst_object_signals[OBJECT_SAVED], 0,
1054       parent);
1056   return parent;
1059 /**
1060  * gst_object_restore_thyself:
1061  * @object: GstObject to load into
1062  * @self: The XML node to load the object from
1063  *
1064  * Restores the given object with the data from the parent XML node.
1065  */
1066 void
1067 gst_object_restore_thyself (GstObject * object, xmlNodePtr self)
1069   GstObjectClass *oclass;
1071   g_return_if_fail (GST_IS_OBJECT (object));
1072   g_return_if_fail (self != NULL);
1074   oclass = GST_OBJECT_GET_CLASS (object);
1076   if (oclass->restore_thyself)
1077     oclass->restore_thyself (object, self);
1080 static void
1081 gst_object_real_restore_thyself (GstObject * object, xmlNodePtr self)
1083   g_return_if_fail (GST_IS_OBJECT (object));
1084   g_return_if_fail (self != NULL);
1086   gst_class_signal_emit_by_name (object, "object_loaded", self);
1088 #endif /* GST_DISABLE_LOADSAVE_REGISTRY */
1090 static void
1091 gst_object_set_property (GObject * object, guint prop_id,
1092     const GValue * value, GParamSpec * pspec)
1094   GstObject *gstobject;
1096   gstobject = GST_OBJECT (object);
1098   switch (prop_id) {
1099     case ARG_NAME:
1100       gst_object_set_name (gstobject, g_value_get_string (value));
1101       break;
1102     default:
1103       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1104       break;
1105   }
1108 static void
1109 gst_object_get_property (GObject * object, guint prop_id,
1110     GValue * value, GParamSpec * pspec)
1112   GstObject *gstobject;
1114   gstobject = GST_OBJECT (object);
1116   switch (prop_id) {
1117     case ARG_NAME:
1118       g_value_take_string (value, gst_object_get_name (gstobject));
1119       break;
1120     default:
1121       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1122       break;
1123   }
1126 /**
1127  * gst_object_get_path_string:
1128  * @object: GstObject to get the path from
1129  *
1130  * Generates a string describing the path of the object in
1131  * the object hierarchy. Only useful (or used) for debugging.
1132  *
1133  * Returns: a string describing the path of the object. You must
1134  *          g_free() the string after usage. 
1135  *
1136  * MT safe. Grabs and releases the object's LOCK for all objects
1137  *          in the hierarchy.
1138  */
1139 gchar *
1140 gst_object_get_path_string (GstObject * object)
1142   GSList *parentage;
1143   GSList *parents;
1144   void *parent;
1145   gchar *prevpath, *path;
1146   gchar *component;
1147   gchar *separator;
1149   /* ref object before adding to list */
1150   gst_object_ref (object);
1151   parentage = g_slist_prepend (NULL, object);
1153   path = g_strdup ("");
1155   /* first walk the object hierarchy to build a list of the parents,
1156    * be carefull here with refcounting. */
1157   do {
1158     if (GST_IS_OBJECT (object)) {
1159       parent = gst_object_get_parent (object);
1160       /* add parents to list, refcount remains increased while
1161        * we handle the object */
1162       if (parent)
1163         parentage = g_slist_prepend (parentage, parent);
1164     } else {
1165       break;
1166     }
1167     object = parent;
1168   } while (object != NULL);
1170   /* then walk the parent list and print them out. we need to
1171    * decrease the refcounting on each element after we handled
1172    * it. */
1173   for (parents = parentage; parents; parents = g_slist_next (parents)) {
1174     if (GST_IS_OBJECT (parents->data)) {
1175       GstObject *item = GST_OBJECT_CAST (parents->data);
1176       GstObjectClass *oclass = GST_OBJECT_GET_CLASS (item);
1178       component = gst_object_get_name (item);
1179       separator = oclass->path_string_separator;
1180       /* and unref now */
1181       gst_object_unref (item);
1182     } else {
1183       component = g_strdup_printf ("%p", parents->data);
1184       separator = "/";
1185     }
1187     prevpath = path;
1188     path = g_strjoin (separator, prevpath, component, NULL);
1189     g_free (prevpath);
1190     g_free (component);
1191   }
1193   g_slist_free (parentage);
1195   return path;
1198 struct _GstSignalObject
1200   GObject object;
1201 };
1203 struct _GstSignalObjectClass
1205   GObjectClass parent_class;
1207   /* signals */
1208 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
1209   void (*object_loaded) (GstSignalObject * object, GstObject * new,
1210       xmlNodePtr self);
1211 #endif                          /* GST_DISABLE_LOADSAVE_REGISTRY */
1212 };
1214 static GType
1215 gst_signal_object_get_type (void)
1217   static GType signal_object_type = 0;
1219   if (!signal_object_type) {
1220     static const GTypeInfo signal_object_info = {
1221       sizeof (GstSignalObjectClass),
1222       NULL,
1223       NULL,
1224       (GClassInitFunc) gst_signal_object_class_init,
1225       NULL,
1226       NULL,
1227       sizeof (GstSignalObject),
1228       0,
1229       (GInstanceInitFunc) gst_signal_object_init,
1230       NULL
1231     };
1233     signal_object_type =
1234         g_type_register_static (G_TYPE_OBJECT, "GstSignalObject",
1235         &signal_object_info, 0);
1236   }
1237   return signal_object_type;
1240 static void
1241 gst_signal_object_class_init (GstSignalObjectClass * klass)
1243   GObjectClass *gobject_class;
1245   gobject_class = (GObjectClass *) klass;
1247   parent_class = g_type_class_ref (G_TYPE_OBJECT);
1249 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
1250   gst_signal_object_signals[SO_OBJECT_LOADED] =
1251       g_signal_new ("object-loaded", G_TYPE_FROM_CLASS (klass),
1252       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstSignalObjectClass, object_loaded),
1253       NULL, NULL, gst_marshal_VOID__OBJECT_POINTER, G_TYPE_NONE, 2,
1254       G_TYPE_OBJECT, G_TYPE_POINTER);
1255 #endif
1258 static void
1259 gst_signal_object_init (GstSignalObject * object)
1263 /**
1264  * gst_class_signal_connect
1265  * @klass: the GstObjectClass to attach the signal to
1266  * @name: the name of the signal to attach to
1267  * @func: the signal function
1268  * @func_data: a pointer to user data
1269  *
1270  * Connect to a class signal.
1271  *
1272  * Returns: the signal id.
1273  */
1274 guint
1275 gst_class_signal_connect (GstObjectClass * klass,
1276     const gchar * name, gpointer func, gpointer func_data)
1278   return g_signal_connect (klass->signal_object, name, func, func_data);
1281 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
1282 /**
1283  * gst_class_signal_emit_by_name:
1284  * @object: the object that sends the signal
1285  * @name: the name of the signal to emit
1286  * @self: data for the signal
1287  *
1288  * emits the named class signal.
1289  */
1290 void
1291 gst_class_signal_emit_by_name (GstObject * object,
1292     const gchar * name, xmlNodePtr self)
1294   GstObjectClass *oclass;
1296   oclass = GST_OBJECT_GET_CLASS (object);
1298   g_signal_emit_by_name (oclass->signal_object, name, object, self);
1301 #endif /* GST_DISABLE_LOADSAVE_REGISTRY */