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>
6 * gstobject.c: Fundamental class used for all of GStreamer
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.
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.
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., 51 Franklin St, Fifth Floor,
21 * Boston, MA 02110-1301, USA.
26 * @short_description: Base class for the GStreamer object hierarchy
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 * #GInitiallyUnowned. It is an abstract class that is not very usable on its own.
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()).
37 * Since #GstObject dereives from #GInitiallyUnowned, it also inherits the
38 * floating reference. Be aware that functions such as gst_bin_add() and
39 * gst_element_add_pad() take ownership of the floating reference.
41 * In contrast to #GObject instances, #GstObject adds a name property. The functions
42 * gst_object_set_name() and gst_object_get_name() are used to set/get the name
46 * <title>controlled properties</title>
48 * Controlled properties offers a lightweight way to adjust gobject
49 * properties over stream-time. It works by using time-stamped value pairs that
50 * are queued for element-properties. At run-time the elements continously pull
51 * values changes for the current stream-time.
53 * What needs to be changed in a #GstElement?
54 * Very little - it is just two steps to make a plugin controllable!
57 * mark gobject-properties paramspecs that make sense to be controlled,
58 * by GST_PARAM_CONTROLLABLE.
61 * when processing data (get, chain, loop function) at the beginning call
62 * gst_object_sync_values(element,timestamp).
63 * This will made the controller to update all gobject properties that are under
64 * control with the current values based on timestamp.
68 * What needs to be done in applications?
69 * Again it's not a lot to change.
72 * create a #GstControlSource.
73 * csource = gst_interpolation_control_source_new ();
74 * g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);
77 * Attach the #GstControlSource on the controller to a property.
78 * gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource));
81 * Set the control values
82 * gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1);
83 * gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2);
92 * Last reviewed on 2012-03-29 (0.11.3)
95 #include "gst_private.h"
96 #include "glib-compat-private.h"
98 #include "gstobject.h"
100 #include "gstcontrolbinding.h"
101 #include "gstcontrolsource.h"
103 #include "gstparamspecs.h"
104 #include "gstutils.h"
106 #ifndef GST_DISABLE_TRACE
107 #include "gsttrace.h"
108 static GstAllocTrace *_gst_object_trace;
111 #define DEBUG_REFCOUNT
113 /* Object signals and args */
134 /* maps type name quark => count */
135 static GData *object_name_counts = NULL;
137 G_LOCK_DEFINE_STATIC (object_name_mutex);
139 static void gst_object_set_property (GObject * object, guint prop_id,
140 const GValue * value, GParamSpec * pspec);
141 static void gst_object_get_property (GObject * object, guint prop_id,
142 GValue * value, GParamSpec * pspec);
144 static void gst_object_dispatch_properties_changed (GObject * object,
145 guint n_pspecs, GParamSpec ** pspecs);
147 static void gst_object_dispose (GObject * object);
148 static void gst_object_finalize (GObject * object);
150 static gboolean gst_object_set_name_default (GstObject * object);
152 static guint gst_object_signals[LAST_SIGNAL] = { 0 };
154 static GParamSpec *properties[PROP_LAST];
156 G_DEFINE_ABSTRACT_TYPE (GstObject, gst_object, G_TYPE_INITIALLY_UNOWNED);
159 gst_object_class_init (GstObjectClass * klass)
161 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
163 #ifndef GST_DISABLE_TRACE
165 _gst_alloc_trace_register (g_type_name (GST_TYPE_OBJECT), -2);
168 gobject_class->set_property = gst_object_set_property;
169 gobject_class->get_property = gst_object_get_property;
171 properties[PROP_NAME] =
172 g_param_spec_string ("name", "Name", "The name of the object", NULL,
173 G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS);
175 properties[PROP_PARENT] =
176 g_param_spec_object ("parent", "Parent", "The parent of the object",
177 GST_TYPE_OBJECT, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
179 g_object_class_install_properties (gobject_class, PROP_LAST, properties);
182 * GstObject::deep-notify:
183 * @gstobject: a #GstObject
184 * @prop_object: the object that originated the signal
185 * @prop: the property that changed
187 * The deep notify signal is used to be notified of property changes. It is
188 * typically attached to the toplevel bin to receive notifications from all
189 * the elements contained in that bin.
191 gst_object_signals[DEEP_NOTIFY] =
192 g_signal_new ("deep-notify", G_TYPE_FROM_CLASS (klass),
193 G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_DETAILED |
194 G_SIGNAL_NO_HOOKS, G_STRUCT_OFFSET (GstObjectClass, deep_notify), NULL,
195 NULL, g_cclosure_marshal_generic, G_TYPE_NONE, 2, GST_TYPE_OBJECT,
198 klass->path_string_separator = "/";
200 /* see the comments at gst_object_dispatch_properties_changed */
201 gobject_class->dispatch_properties_changed
202 = GST_DEBUG_FUNCPTR (gst_object_dispatch_properties_changed);
204 gobject_class->dispose = gst_object_dispose;
205 gobject_class->finalize = gst_object_finalize;
209 gst_object_init (GstObject * object)
211 g_mutex_init (&object->lock);
212 object->parent = NULL;
214 GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p new", object);
216 #ifndef GST_DISABLE_TRACE
217 _gst_alloc_trace_new (_gst_object_trace, object);
222 object->control_rate = 100 * GST_MSECOND;
223 object->last_sync = GST_CLOCK_TIME_NONE;
228 * @object: (type Gst.Object): a #GstObject to reference
230 * Increments the reference count on @object. This function
231 * does not take the lock on @object because it relies on
232 * atomic refcounting.
234 * This object returns the input parameter to ease writing
236 * result = gst_object_ref (object->parent);
238 * Returns: (transfer full) (type Gst.Object): A pointer to @object
241 gst_object_ref (gpointer object)
243 g_return_val_if_fail (object != NULL, NULL);
245 #ifdef DEBUG_REFCOUNT
246 GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p ref %d->%d", object,
247 ((GObject *) object)->ref_count, ((GObject *) object)->ref_count + 1);
249 g_object_ref (object);
256 * @object: (type Gst.Object): a #GstObject to unreference
258 * Decrements the reference count on @object. If reference count hits
259 * zero, destroy @object. This function does not take the lock
260 * on @object as it relies on atomic refcounting.
262 * The unref method should never be called with the LOCK held since
263 * this might deadlock the dispose function.
266 gst_object_unref (gpointer object)
268 g_return_if_fail (object != NULL);
269 g_return_if_fail (((GObject *) object)->ref_count > 0);
271 #ifdef DEBUG_REFCOUNT
272 GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p unref %d->%d", object,
273 ((GObject *) object)->ref_count, ((GObject *) object)->ref_count - 1);
275 g_object_unref (object);
279 * gst_object_ref_sink: (skip)
280 * @object: a #GstObject to sink
282 * Increase the reference count of @object, and possibly remove the floating
283 * reference, if @object has a floating reference.
285 * In other words, if the object is floating, then this call "assumes ownership"
286 * of the floating reference, converting it to a normal reference by clearing
287 * the floating flag while leaving the reference count unchanged. If the object
288 * is not floating, then this call adds a new normal reference increasing the
289 * reference count by one.
292 gst_object_ref_sink (gpointer object)
294 g_return_val_if_fail (object != NULL, NULL);
296 #ifdef DEBUG_REFCOUNT
297 GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p ref_sink %d->%d",
298 object, ((GObject *) object)->ref_count,
299 ((GObject *) object)->ref_count + 1);
301 return g_object_ref_sink (object);
305 * gst_object_replace:
306 * @oldobj: (inout) (transfer full): pointer to a place of a #GstObject to
308 * @newobj: (transfer none): a new #GstObject
310 * Atomically modifies a pointer to point to a new object.
311 * The reference count of @oldobj is decreased and the reference count of
312 * @newobj is increased.
314 * Either @newobj and the value pointed to by @oldobj may be NULL.
316 * Returns: TRUE if @newobj was different from @oldobj
319 gst_object_replace (GstObject ** oldobj, GstObject * newobj)
323 g_return_val_if_fail (oldobj != NULL, FALSE);
325 #ifdef DEBUG_REFCOUNT
326 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "replace %p %s (%d) with %p %s (%d)",
327 *oldobj, *oldobj ? GST_STR_NULL (GST_OBJECT_NAME (*oldobj)) : "(NONE)",
328 *oldobj ? G_OBJECT (*oldobj)->ref_count : 0,
329 newobj, newobj ? GST_STR_NULL (GST_OBJECT_NAME (newobj)) : "(NONE)",
330 newobj ? G_OBJECT (newobj)->ref_count : 0);
333 oldptr = g_atomic_pointer_get ((gpointer *) oldobj);
335 if (G_UNLIKELY (oldptr == newobj))
339 gst_object_ref (newobj);
341 while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
342 oldobj, oldptr, newobj))) {
343 oldptr = g_atomic_pointer_get ((gpointer *) oldobj);
344 if (G_UNLIKELY (oldptr == newobj))
349 gst_object_unref (oldptr);
351 return oldptr != newobj;
354 /* dispose is called when the object has to release all links
355 * to other objects */
357 gst_object_dispose (GObject * object)
359 GstObject *self = (GstObject *) object;
362 GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "dispose");
364 GST_OBJECT_LOCK (object);
365 if ((parent = GST_OBJECT_PARENT (object)))
367 GST_OBJECT_PARENT (object) = NULL;
368 GST_OBJECT_UNLOCK (object);
370 if (self->control_bindings) {
373 for (node = self->control_bindings; node; node = g_list_next (node)) {
374 gst_object_unparent (node->data);
376 g_list_free (self->control_bindings);
377 self->control_bindings = NULL;
380 ((GObjectClass *) gst_object_parent_class)->dispose (object);
387 g_critical ("\nTrying to dispose object \"%s\", but it still has a "
388 "parent \"%s\".\nYou need to let the parent manage the "
389 "object instead of unreffing the object directly.\n",
390 GST_OBJECT_NAME (object), GST_OBJECT_NAME (parent));
391 GST_OBJECT_UNLOCK (object);
392 /* ref the object again to revive it in this error case */
393 gst_object_ref (object);
398 /* finalize is called when the object has to free its resources */
400 gst_object_finalize (GObject * object)
402 GstObject *gstobject = GST_OBJECT_CAST (object);
404 GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "finalize");
406 g_signal_handlers_destroy (object);
408 g_free (gstobject->name);
409 g_mutex_clear (&gstobject->lock);
411 #ifndef GST_DISABLE_TRACE
412 _gst_alloc_trace_free (_gst_object_trace, object);
415 ((GObjectClass *) gst_object_parent_class)->finalize (object);
418 /* Changing a GObject property of a GstObject will result in "deep-notify"
419 * signals being emitted by the object itself, as well as in each parent
420 * object. This is so that an application can connect a listener to the
421 * top-level bin to catch property-change notifications for all contained
427 gst_object_dispatch_properties_changed (GObject * object,
428 guint n_pspecs, GParamSpec ** pspecs)
430 GstObject *gst_object, *parent, *old_parent;
432 #ifndef GST_DISABLE_GST_DEBUG
434 const gchar *debug_name;
437 /* do the standard dispatching */
439 gst_object_parent_class)->dispatch_properties_changed (object, n_pspecs,
442 gst_object = GST_OBJECT_CAST (object);
443 #ifndef GST_DISABLE_GST_DEBUG
444 if (G_UNLIKELY (_gst_debug_min >= GST_LEVEL_LOG)) {
445 name = gst_object_get_name (gst_object);
446 debug_name = GST_STR_NULL (name);
451 /* now let the parent dispatch those, too */
452 parent = gst_object_get_parent (gst_object);
454 for (i = 0; i < n_pspecs; i++) {
455 GST_CAT_LOG_OBJECT (GST_CAT_PROPERTIES, parent,
456 "deep notification from %s (%s)", debug_name, pspecs[i]->name);
458 g_signal_emit (parent, gst_object_signals[DEEP_NOTIFY],
459 g_quark_from_string (pspecs[i]->name), gst_object, pspecs[i]);
463 parent = gst_object_get_parent (old_parent);
464 gst_object_unref (old_parent);
466 #ifndef GST_DISABLE_GST_DEBUG
472 * gst_object_default_deep_notify:
473 * @object: the #GObject that signalled the notify.
474 * @orig: a #GstObject that initiated the notify.
475 * @pspec: a #GParamSpec of the property.
476 * @excluded_props: (array zero-terminated=1) (element-type gchar*) (allow-none):
477 * a set of user-specified properties to exclude or NULL to show
480 * A default deep_notify signal callback for an object. The user data
481 * should contain a pointer to an array of strings that should be excluded
482 * from the notify. The default handler will print the new value of the property
485 * MT safe. This function grabs and releases @object's LOCK for getting its
489 gst_object_default_deep_notify (GObject * object, GstObject * orig,
490 GParamSpec * pspec, gchar ** excluded_props)
492 GValue value = { 0, }; /* the important thing is that value.type = 0 */
496 if (pspec->flags & G_PARAM_READABLE) {
497 /* let's not print these out for excluded properties... */
498 while (excluded_props != NULL && *excluded_props != NULL) {
499 if (strcmp (pspec->name, *excluded_props) == 0)
503 g_value_init (&value, pspec->value_type);
504 g_object_get_property (G_OBJECT (orig), pspec->name, &value);
506 if (G_VALUE_HOLDS_STRING (&value))
507 str = g_value_dup_string (&value);
509 str = gst_value_serialize (&value);
510 name = gst_object_get_path_string (orig);
511 g_print ("%s: %s = %s\n", name, pspec->name, str);
514 g_value_unset (&value);
516 name = gst_object_get_path_string (orig);
517 g_warning ("Parameter %s not readable in %s.", pspec->name, name);
523 gst_object_set_name_default (GstObject * object)
525 const gchar *type_name;
531 /* to ensure guaranteed uniqueness across threads, only one thread
532 * may ever assign a name */
533 G_LOCK (object_name_mutex);
535 if (!object_name_counts) {
536 g_datalist_init (&object_name_counts);
539 q = g_type_qname (G_OBJECT_TYPE (object));
540 count = GPOINTER_TO_INT (g_datalist_id_get_data (&object_name_counts, q));
541 g_datalist_id_set_data (&object_name_counts, q, GINT_TO_POINTER (count + 1));
543 G_UNLOCK (object_name_mutex);
545 /* GstFooSink -> foosink<N> */
546 type_name = g_quark_to_string (q);
547 if (strncmp (type_name, "Gst", 3) == 0)
549 /* give the 20th "queue" element and the first "queue2" different names */
550 l = strlen (type_name);
551 if (l > 0 && g_ascii_isdigit (type_name[l - 1])) {
552 name = g_strdup_printf ("%s-%d", type_name, count);
554 name = g_strdup_printf ("%s%d", type_name, count);
558 for (i = 0; i < l; i++)
559 name[i] = g_ascii_tolower (name[i]);
561 GST_OBJECT_LOCK (object);
562 if (G_UNLIKELY (object->parent != NULL))
565 g_free (object->name);
568 GST_OBJECT_UNLOCK (object);
575 GST_WARNING ("parented objects can't be renamed");
576 GST_OBJECT_UNLOCK (object);
582 * gst_object_set_name:
583 * @object: a #GstObject
584 * @name: new name of object
586 * Sets the name of @object, or gives @object a guaranteed unique
587 * name (if @name is NULL).
588 * This function makes a copy of the provided name, so the caller
589 * retains ownership of the name it sent.
591 * Returns: TRUE if the name could be set. Since Objects that have
592 * a parent cannot be renamed, this function returns FALSE in those
595 * MT safe. This function grabs and releases @object's LOCK.
598 gst_object_set_name (GstObject * object, const gchar * name)
602 g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
604 GST_OBJECT_LOCK (object);
606 /* parented objects cannot be renamed */
607 if (G_UNLIKELY (object->parent != NULL))
611 g_free (object->name);
612 object->name = g_strdup (name);
613 GST_OBJECT_UNLOCK (object);
616 GST_OBJECT_UNLOCK (object);
617 result = gst_object_set_name_default (object);
619 /* FIXME-0.11: this misses a g_object_notify (object, "name"); unless called
620 * from gst_object_set_property.
621 * Ideally remove such custom setters (or make it static).
628 GST_WARNING ("parented objects can't be renamed");
629 GST_OBJECT_UNLOCK (object);
635 * gst_object_get_name:
636 * @object: a #GstObject
638 * Returns a copy of the name of @object.
639 * Caller should g_free() the return value after usage.
640 * For a nameless object, this returns NULL, which you can safely g_free()
643 * Free-function: g_free
645 * Returns: (transfer full): the name of @object. g_free() after usage.
647 * MT safe. This function grabs and releases @object's LOCK.
650 gst_object_get_name (GstObject * object)
652 gchar *result = NULL;
654 g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
656 GST_OBJECT_LOCK (object);
657 result = g_strdup (object->name);
658 GST_OBJECT_UNLOCK (object);
664 * gst_object_set_parent:
665 * @object: a #GstObject
666 * @parent: new parent of object
668 * Sets the parent of @object to @parent. The object's reference count will
669 * be incremented, and any floating reference will be removed (see gst_object_ref_sink()).
671 * Returns: TRUE if @parent could be set or FALSE when @object
672 * already had a parent or @object and @parent are the same.
674 * MT safe. Grabs and releases @object's LOCK.
677 gst_object_set_parent (GstObject * object, GstObject * parent)
679 g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
680 g_return_val_if_fail (GST_IS_OBJECT (parent), FALSE);
681 g_return_val_if_fail (object != parent, FALSE);
683 GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object,
684 "set parent (ref and sink)");
686 GST_OBJECT_LOCK (object);
687 if (G_UNLIKELY (object->parent != NULL))
690 object->parent = parent;
691 gst_object_ref_sink (object);
692 GST_OBJECT_UNLOCK (object);
694 /* FIXME, this does not work, the deep notify takes the lock from the parent
695 * object and deadlocks when the parent holds its lock when calling this
696 * function (like _element_add_pad()) */
697 /* g_object_notify_by_pspec ((GObject *)object, properties[PROP_PARENT]); */
704 GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object,
705 "set parent failed, object already had a parent");
706 GST_OBJECT_UNLOCK (object);
712 * gst_object_get_parent:
713 * @object: a #GstObject
715 * Returns the parent of @object. This function increases the refcount
716 * of the parent object so you should gst_object_unref() it after usage.
718 * Returns: (transfer full): parent of @object, this can be NULL if @object
719 * has no parent. unref after usage.
721 * MT safe. Grabs and releases @object's LOCK.
724 gst_object_get_parent (GstObject * object)
726 GstObject *result = NULL;
728 g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
730 GST_OBJECT_LOCK (object);
731 result = object->parent;
732 if (G_LIKELY (result))
733 gst_object_ref (result);
734 GST_OBJECT_UNLOCK (object);
740 * gst_object_unparent:
741 * @object: a #GstObject to unparent
743 * Clear the parent of @object, removing the associated reference.
744 * This function decreases the refcount of @object.
746 * MT safe. Grabs and releases @object's lock.
749 gst_object_unparent (GstObject * object)
753 g_return_if_fail (GST_IS_OBJECT (object));
755 GST_OBJECT_LOCK (object);
756 parent = object->parent;
758 if (G_LIKELY (parent != NULL)) {
759 GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "unparent");
760 object->parent = NULL;
761 GST_OBJECT_UNLOCK (object);
763 /* g_object_notify_by_pspec ((GObject *)object, properties[PROP_PARENT]); */
765 gst_object_unref (object);
767 GST_OBJECT_UNLOCK (object);
772 * gst_object_has_ancestor:
773 * @object: a #GstObject to check
774 * @ancestor: a #GstObject to check as ancestor
776 * Check if @object has an ancestor @ancestor somewhere up in
777 * the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline.
779 * Returns: TRUE if @ancestor is an ancestor of @object.
781 * MT safe. Grabs and releases @object's locks.
784 gst_object_has_ancestor (GstObject * object, GstObject * ancestor)
786 GstObject *parent, *tmp;
788 if (!ancestor || !object)
791 parent = gst_object_ref (object);
793 if (parent == ancestor) {
794 gst_object_unref (parent);
798 tmp = gst_object_get_parent (parent);
799 gst_object_unref (parent);
807 * gst_object_check_uniqueness:
808 * @list: (transfer none) (element-type Gst.Object): a list of #GstObject to
810 * @name: the name to search for
812 * Checks to see if there is any object named @name in @list. This function
813 * does not do any locking of any kind. You might want to protect the
814 * provided list with the lock of the owner of the list. This function
815 * will lock each #GstObject in the list to compare the name, so be
816 * carefull when passing a list with a locked object.
818 * Returns: TRUE if a #GstObject named @name does not appear in @list,
821 * MT safe. Grabs and releases the LOCK of each object in the list.
824 gst_object_check_uniqueness (GList * list, const gchar * name)
826 gboolean result = TRUE;
828 g_return_val_if_fail (name != NULL, FALSE);
830 for (; list; list = g_list_next (list)) {
834 child = GST_OBJECT_CAST (list->data);
836 GST_OBJECT_LOCK (child);
837 eq = strcmp (GST_OBJECT_NAME (child), name) == 0;
838 GST_OBJECT_UNLOCK (child);
840 if (G_UNLIKELY (eq)) {
850 gst_object_set_property (GObject * object, guint prop_id,
851 const GValue * value, GParamSpec * pspec)
853 GstObject *gstobject;
855 gstobject = GST_OBJECT_CAST (object);
859 gst_object_set_name (gstobject, g_value_get_string (value));
862 gst_object_set_parent (gstobject, g_value_get_object (value));
865 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
871 gst_object_get_property (GObject * object, guint prop_id,
872 GValue * value, GParamSpec * pspec)
874 GstObject *gstobject;
876 gstobject = GST_OBJECT_CAST (object);
880 g_value_take_string (value, gst_object_get_name (gstobject));
883 g_value_take_object (value, gst_object_get_parent (gstobject));
886 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
892 * gst_object_get_path_string:
893 * @object: a #GstObject
895 * Generates a string describing the path of @object in
896 * the object hierarchy. Only useful (or used) for debugging.
898 * Free-function: g_free
900 * Returns: (transfer full): a string describing the path of @object. You must
901 * g_free() the string after usage.
903 * MT safe. Grabs and releases the #GstObject's LOCK for all objects
907 gst_object_get_path_string (GstObject * object)
912 gchar *prevpath, *path;
913 const gchar *typename;
915 const gchar *separator;
917 /* ref object before adding to list */
918 gst_object_ref (object);
919 parentage = g_slist_prepend (NULL, object);
921 path = g_strdup ("");
923 /* first walk the object hierarchy to build a list of the parents,
924 * be carefull here with refcounting. */
926 if (GST_IS_OBJECT (object)) {
927 parent = gst_object_get_parent (object);
928 /* add parents to list, refcount remains increased while
929 * we handle the object */
931 parentage = g_slist_prepend (parentage, parent);
936 } while (object != NULL);
938 /* then walk the parent list and print them out. we need to
939 * decrease the refcounting on each element after we handled
941 for (parents = parentage; parents; parents = g_slist_next (parents)) {
942 if (G_IS_OBJECT (parents->data)) {
943 typename = G_OBJECT_TYPE_NAME (parents->data);
947 if (GST_IS_OBJECT (parents->data)) {
948 GstObject *item = GST_OBJECT_CAST (parents->data);
949 GstObjectClass *oclass = GST_OBJECT_GET_CLASS (item);
950 gchar *objname = gst_object_get_name (item);
952 component = g_strdup_printf ("%s:%s", typename, objname);
953 separator = oclass->path_string_separator;
955 gst_object_unref (item);
959 component = g_strdup_printf ("%s:%p", typename, parents->data);
961 component = g_strdup_printf ("%p", parents->data);
967 path = g_strjoin (separator, prevpath, component, NULL);
972 g_slist_free (parentage);
977 /* controller helper functions */
980 * gst_object_find_control_binding:
981 * @self: the gobject to search for a property in
982 * @name: the gobject property name to look for
984 * Searches the list of properties under control.
986 * Returns: a #GstControlBinding or %NULL if the property is not being
989 static GstControlBinding *
990 gst_object_find_control_binding (GstObject * self, const gchar * name)
992 GstControlBinding *binding;
995 for (node = self->control_bindings; node; node = g_list_next (node)) {
996 binding = node->data;
997 /* FIXME: eventually use GQuark to speed it up */
998 if (!strcmp (binding->name, name)) {
999 GST_DEBUG_OBJECT (self, "found control binding for property '%s'", name);
1003 GST_DEBUG_OBJECT (self, "controller does not manage property '%s'", name);
1008 /* controller functions */
1011 * gst_object_suggest_next_sync:
1012 * @object: the object that has controlled properties
1014 * Returns a suggestion for timestamps where buffers should be split
1015 * to get best controller results.
1017 * Returns: Returns the suggested timestamp or %GST_CLOCK_TIME_NONE
1018 * if no control-rate was set.
1021 gst_object_suggest_next_sync (GstObject * object)
1025 g_return_val_if_fail (GST_IS_OBJECT (object), GST_CLOCK_TIME_NONE);
1026 g_return_val_if_fail (object->control_rate != GST_CLOCK_TIME_NONE,
1027 GST_CLOCK_TIME_NONE);
1029 GST_OBJECT_LOCK (object);
1031 /* TODO: Implement more logic, depending on interpolation mode and control
1033 * FIXME: we need playback direction
1035 ret = object->last_sync + object->control_rate;
1037 GST_OBJECT_UNLOCK (object);
1043 * gst_object_sync_values:
1044 * @object: the object that has controlled properties
1045 * @timestamp: the time that should be processed
1047 * Sets the properties of the object, according to the #GstControlSources that
1048 * (maybe) handle them and for the given timestamp.
1050 * If this function fails, it is most likely the application developers fault.
1051 * Most probably the control sources are not setup correctly.
1053 * Returns: %TRUE if the controller values could be applied to the object
1054 * properties, %FALSE otherwise
1057 gst_object_sync_values (GstObject * object, GstClockTime timestamp)
1060 gboolean ret = TRUE;
1062 g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1063 g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
1065 GST_LOG_OBJECT (object, "sync_values");
1066 if (!object->control_bindings)
1069 /* FIXME: this deadlocks */
1070 /* GST_OBJECT_LOCK (object); */
1071 g_object_freeze_notify ((GObject *) object);
1072 for (node = object->control_bindings; node; node = g_list_next (node)) {
1073 ret &= gst_control_binding_sync_values ((GstControlBinding *) node->data,
1074 object, timestamp, object->last_sync);
1076 object->last_sync = timestamp;
1077 g_object_thaw_notify ((GObject *) object);
1078 /* GST_OBJECT_UNLOCK (object); */
1085 * gst_object_has_active_control_bindings:
1086 * @object: the object that has controlled properties
1088 * Check if the @object has an active controlled properties.
1090 * Returns: %TRUE if the object has active controlled properties
1093 gst_object_has_active_control_bindings (GstObject * object)
1095 gboolean res = FALSE;
1098 g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1100 GST_OBJECT_LOCK (object);
1101 for (node = object->control_bindings; node; node = g_list_next (node)) {
1102 res |= !gst_control_binding_is_disabled ((GstControlBinding *) node->data);
1104 GST_OBJECT_UNLOCK (object);
1109 * gst_object_set_control_bindings_disabled:
1110 * @object: the object that has controlled properties
1111 * @disabled: boolean that specifies whether to disable the controller
1114 * This function is used to disable all controlled properties of the @object for
1115 * some time, i.e. gst_object_sync_values() will do nothing.
1118 gst_object_set_control_bindings_disabled (GstObject * object, gboolean disabled)
1122 g_return_if_fail (GST_IS_OBJECT (object));
1124 GST_OBJECT_LOCK (object);
1125 for (node = object->control_bindings; node; node = g_list_next (node)) {
1126 gst_control_binding_set_disabled ((GstControlBinding *) node->data,
1129 GST_OBJECT_UNLOCK (object);
1133 * gst_object_set_control_binding_disabled:
1134 * @object: the object that has controlled properties
1135 * @property_name: property to disable
1136 * @disabled: boolean that specifies whether to disable the controller
1139 * This function is used to disable the #GstController on a property for
1140 * some time, i.e. gst_controller_sync_values() will do nothing for the
1144 gst_object_set_control_binding_disabled (GstObject * object,
1145 const gchar * property_name, gboolean disabled)
1147 GstControlBinding *binding;
1149 g_return_if_fail (GST_IS_OBJECT (object));
1150 g_return_if_fail (property_name);
1152 GST_OBJECT_LOCK (object);
1153 if ((binding = gst_object_find_control_binding (object, property_name))) {
1154 gst_control_binding_set_disabled (binding, disabled);
1156 GST_OBJECT_UNLOCK (object);
1161 * gst_object_add_control_binding:
1162 * @object: the controller object
1163 * @binding: (transfer full): the #GstControlBinding that should be used
1165 * Sets the #GstControlBinding. If there already was a #GstControlBinding
1166 * for this property it will be replaced.
1167 * The @object will take ownership of the @binding.
1169 * Returns: %FALSE if the given @binding has not been setup for this object or
1173 gst_object_add_control_binding (GstObject * object, GstControlBinding * binding)
1175 GstControlBinding *old;
1177 g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1178 g_return_val_if_fail (GST_IS_CONTROL_BINDING (binding), FALSE);
1180 GST_OBJECT_LOCK (object);
1181 if ((old = gst_object_find_control_binding (object, binding->name))) {
1182 GST_DEBUG_OBJECT (object, "controlled property %s removed", old->name);
1183 object->control_bindings = g_list_remove (object->control_bindings, old);
1184 gst_object_unparent (GST_OBJECT_CAST (old));
1186 object->control_bindings = g_list_prepend (object->control_bindings, binding);
1187 gst_object_set_parent (GST_OBJECT_CAST (binding), object);
1188 GST_DEBUG_OBJECT (object, "controlled property %s added", binding->name);
1189 GST_OBJECT_UNLOCK (object);
1195 * gst_object_get_control_binding:
1196 * @object: the object
1197 * @property_name: name of the property
1199 * Gets the corresponding #GstControlBinding for the property. This should be
1200 * unreferenced again after use.
1202 * Returns: (transfer full): the #GstControlBinding for @property_name or %NULL if
1203 * the property is not controlled.
1206 gst_object_get_control_binding (GstObject * object, const gchar * property_name)
1208 GstControlBinding *binding;
1210 g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
1211 g_return_val_if_fail (property_name, NULL);
1213 GST_OBJECT_LOCK (object);
1214 if ((binding = gst_object_find_control_binding (object, property_name))) {
1215 gst_object_ref (binding);
1217 GST_OBJECT_UNLOCK (object);
1223 * gst_object_remove_control_binding:
1224 * @object: the object
1225 * @binding: the binding
1227 * Removes the corresponding #GstControlBinding. If it was the
1228 * last ref of the binding, it will be disposed.
1230 * Returns: %TRUE if the binding could be removed.
1233 gst_object_remove_control_binding (GstObject * object,
1234 GstControlBinding * binding)
1237 gboolean ret = FALSE;
1239 g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1240 g_return_val_if_fail (GST_IS_CONTROL_BINDING (binding), FALSE);
1242 GST_OBJECT_LOCK (object);
1243 if ((node = g_list_find (object->control_bindings, binding))) {
1244 GST_DEBUG_OBJECT (object, "controlled property %s removed", binding->name);
1245 object->control_bindings =
1246 g_list_delete_link (object->control_bindings, node);
1247 gst_object_unparent (GST_OBJECT_CAST (binding));
1250 GST_OBJECT_UNLOCK (object);
1256 * gst_object_get_value:
1257 * @object: the object that has controlled properties
1258 * @property_name: the name of the property to get
1259 * @timestamp: the time the control-change should be read from
1261 * Gets the value for the given controlled property at the requested time.
1263 * Returns: the GValue of the property at the given time, or %NULL if the
1264 * property isn't controlled.
1267 gst_object_get_value (GstObject * object, const gchar * property_name,
1268 GstClockTime timestamp)
1270 GstControlBinding *binding;
1273 g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
1274 g_return_val_if_fail (property_name, NULL);
1275 g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), NULL);
1277 GST_OBJECT_LOCK (object);
1278 if ((binding = gst_object_find_control_binding (object, property_name))) {
1279 val = gst_control_binding_get_value (binding, timestamp);
1281 GST_OBJECT_UNLOCK (object);
1287 * gst_object_get_value_array:
1288 * @object: the object that has controlled properties
1289 * @property_name: the name of the property to get
1290 * @timestamp: the time that should be processed
1291 * @interval: the time spacing between subsequent values
1292 * @n_values: the number of values
1293 * @values: array to put control-values in
1295 * Gets a number of values for the given controlled property starting at the
1296 * requested time. The array @values need to hold enough space for @n_values of
1297 * the same type as the objects property's type.
1299 * This function is useful if one wants to e.g. draw a graph of the control
1300 * curve or apply a control curve sample by sample.
1302 * The values are unboxed and ready to be used. The similar function
1303 * gst_object_get_g_value_array() returns the array as #GValues and is
1304 * better suites for bindings.
1306 * Returns: %TRUE if the given array could be filled, %FALSE otherwise
1309 gst_object_get_value_array (GstObject * object, const gchar * property_name,
1310 GstClockTime timestamp, GstClockTime interval, guint n_values,
1313 gboolean res = FALSE;
1314 GstControlBinding *binding;
1316 g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1317 g_return_val_if_fail (property_name, FALSE);
1318 g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
1319 g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (interval), FALSE);
1320 g_return_val_if_fail (values, FALSE);
1322 GST_OBJECT_LOCK (object);
1323 if ((binding = gst_object_find_control_binding (object, property_name))) {
1324 res = gst_control_binding_get_value_array (binding, timestamp, interval,
1327 GST_OBJECT_UNLOCK (object);
1332 * gst_object_get_g_value_array:
1333 * @object: the object that has controlled properties
1334 * @property_name: the name of the property to get
1335 * @timestamp: the time that should be processed
1336 * @interval: the time spacing between subsequent values
1337 * @n_values: the number of values
1338 * @values: array to put control-values in
1340 * Gets a number of #GValues for the given controlled property starting at the
1341 * requested time. The array @values need to hold enough space for @n_values of
1344 * This function is useful if one wants to e.g. draw a graph of the control
1345 * curve or apply a control curve sample by sample.
1347 * Returns: %TRUE if the given array could be filled, %FALSE otherwise
1350 gst_object_get_g_value_array (GstObject * object, const gchar * property_name,
1351 GstClockTime timestamp, GstClockTime interval, guint n_values,
1354 gboolean res = FALSE;
1355 GstControlBinding *binding;
1357 g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1358 g_return_val_if_fail (property_name, FALSE);
1359 g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
1360 g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (interval), FALSE);
1361 g_return_val_if_fail (values, FALSE);
1363 GST_OBJECT_LOCK (object);
1364 if ((binding = gst_object_find_control_binding (object, property_name))) {
1365 res = gst_control_binding_get_g_value_array (binding, timestamp, interval,
1368 GST_OBJECT_UNLOCK (object);
1374 * gst_object_get_control_rate:
1375 * @object: the object that has controlled properties
1377 * Obtain the control-rate for this @object. Audio processing #GstElement
1378 * objects will use this rate to sub-divide their processing loop and call
1379 * gst_object_sync_values() inbetween. The length of the processing segment
1380 * should be up to @control-rate nanoseconds.
1382 * If the @object is not under property control, this will return
1383 * %GST_CLOCK_TIME_NONE. This allows the element to avoid the sub-dividing.
1385 * The control-rate is not expected to change if the element is in
1386 * %GST_STATE_PAUSED or %GST_STATE_PLAYING.
1388 * Returns: the control rate in nanoseconds
1391 gst_object_get_control_rate (GstObject * object)
1393 g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1395 return object->control_rate;
1399 * gst_object_set_control_rate:
1400 * @object: the object that has controlled properties
1401 * @control_rate: the new control-rate in nanoseconds.
1403 * Change the control-rate for this @object. Audio processing #GstElement
1404 * objects will use this rate to sub-divide their processing loop and call
1405 * gst_object_sync_values() inbetween. The length of the processing segment
1406 * should be up to @control-rate nanoseconds.
1408 * The control-rate should not change if the element is in %GST_STATE_PAUSED or
1409 * %GST_STATE_PLAYING.
1412 gst_object_set_control_rate (GstObject * object, GstClockTime control_rate)
1414 g_return_if_fail (GST_IS_OBJECT (object));
1416 object->control_rate = control_rate;