X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gst%2Fgstobject.c;h=3aa20c44351ad0924ba840c6028c6b94009b8358;hb=dac5966da6a0f53d0443dfa1ac239289028c415d;hp=24c3fa0769e673ee466fda377279aa108cd224bc;hpb=bbc26fffc26b38dc6c83702d1ff1c969f33e60dc;p=platform%2Fupstream%2Fgstreamer.git diff --git a/gst/gstobject.c b/gst/gstobject.c index 24c3fa0..3aa20c4 100644 --- a/gst/gstobject.c +++ b/gst/gstobject.c @@ -23,6 +23,7 @@ /** * SECTION:gstobject + * @title: GstObject * @short_description: Base class for the GStreamer object hierarchy * * #GstObject provides a root for the object hierarchy tree filed in by the @@ -42,9 +43,8 @@ * gst_object_set_name() and gst_object_get_name() are used to set/get the name * of the object. * - * - * controlled properties - * + * ## controlled properties + * * Controlled properties offers a lightweight way to adjust gobject properties * over stream-time. It works by using time-stamped value pairs that are queued * for element-properties. At run-time the elements continuously pull value @@ -52,44 +52,29 @@ * * What needs to be changed in a #GstElement? * Very little - it is just two steps to make a plugin controllable! - * - * - * mark gobject-properties paramspecs that make sense to be controlled, + * + * * mark gobject-properties paramspecs that make sense to be controlled, * by GST_PARAM_CONTROLLABLE. - * - * - * when processing data (get, chain, loop function) at the beginning call + * + * * when processing data (get, chain, loop function) at the beginning call * gst_object_sync_values(element,timestamp). - * This will make the controller to update all gobject properties that are under - * control with the current values based on timestamp. - * - * - * - * What needs to be done in applications? - * Again it's not a lot to change. - * - * - * create a #GstControlSource. + * This will make the controller update all GObject properties that are + * under its control with the current values based on the timestamp. + * + * What needs to be done in applications? Again it's not a lot to change. + * + * * create a #GstControlSource. * csource = gst_interpolation_control_source_new (); * g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL); - * - * - * Attach the #GstControlSource on the controller to a property. + * + * * Attach the #GstControlSource on the controller to a property. * gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource)); - * - * - * Set the control values + * + * * Set the control values * gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1); * gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2); - * - * - * start your pipeline - * - * - * - * - * - * Last reviewed on 2012-03-29 (0.11.3) + * + * * start your pipeline */ #include "gst_private.h" @@ -103,11 +88,6 @@ #include "gstparamspecs.h" #include "gstutils.h" -#ifndef GST_DISABLE_TRACE -#include "gsttrace.h" -static GstAllocTrace *_gst_object_trace; -#endif - #define DEBUG_REFCOUNT /* Object signals and args */ @@ -156,15 +136,18 @@ static GParamSpec *properties[PROP_LAST]; G_DEFINE_ABSTRACT_TYPE (GstObject, gst_object, G_TYPE_INITIALLY_UNOWNED); static void +gst_object_constructed (GObject * object) +{ + GST_TRACER_OBJECT_CREATED (GST_OBJECT_CAST (object)); + + ((GObjectClass *) gst_object_parent_class)->constructed (object); +} + +static void gst_object_class_init (GstObjectClass * klass) { GObjectClass *gobject_class = G_OBJECT_CLASS (klass); -#ifndef GST_DISABLE_TRACE - _gst_object_trace = - _gst_alloc_trace_register (g_type_name (GST_TYPE_OBJECT), -2); -#endif - gobject_class->set_property = gst_object_set_property; gobject_class->get_property = gst_object_get_property; @@ -172,6 +155,15 @@ gst_object_class_init (GstObjectClass * klass) g_param_spec_string ("name", "Name", "The name of the object", NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS); + /** + * GstObject:parent: + * + * The parent of the object. Please note, that when changing the 'parent' + * property, we don't emit #GObject::notify and #GstObject::deep-notify + * signals due to locking issues. In some cases one can use + * #GstBin::element-added or #GstBin::element-removed signals on the parent to + * achieve a similar effect. + */ properties[PROP_PARENT] = g_param_spec_object ("parent", "Parent", "The parent of the object", GST_TYPE_OBJECT, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); @@ -201,6 +193,7 @@ gst_object_class_init (GstObjectClass * klass) gobject_class->dispatch_properties_changed = GST_DEBUG_FUNCPTR (gst_object_dispatch_properties_changed); + gobject_class->constructed = gst_object_constructed; gobject_class->dispose = gst_object_dispose; gobject_class->finalize = gst_object_finalize; } @@ -213,10 +206,6 @@ gst_object_init (GstObject * object) object->name = NULL; GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p new", object); -#ifndef GST_DISABLE_TRACE - _gst_alloc_trace_new (_gst_object_trace, object); -#endif - object->flags = 0; object->control_rate = 100 * GST_MSECOND; @@ -242,6 +231,7 @@ gst_object_ref (gpointer object) { g_return_val_if_fail (object != NULL, NULL); + GST_TRACER_OBJECT_REFFED (object, ((GObject *) object)->ref_count + 1); #ifdef DEBUG_REFCOUNT GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p ref %d->%d", object, ((GObject *) object)->ref_count, ((GObject *) object)->ref_count + 1); @@ -268,6 +258,7 @@ gst_object_unref (gpointer object) g_return_if_fail (object != NULL); g_return_if_fail (((GObject *) object)->ref_count > 0); + GST_TRACER_OBJECT_UNREFFED (object, ((GObject *) object)->ref_count - 1); #ifdef DEBUG_REFCOUNT GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p unref %d->%d", object, ((GObject *) object)->ref_count, ((GObject *) object)->ref_count - 1); @@ -287,6 +278,9 @@ gst_object_unref (gpointer object) * the floating flag while leaving the reference count unchanged. If the object * is not floating, then this call adds a new normal reference increasing the * reference count by one. + * + * For more background on "floating references" please see the #GObject + * documentation. */ gpointer gst_object_ref_sink (gpointer object) @@ -302,18 +296,42 @@ gst_object_ref_sink (gpointer object) } /** + * gst_clear_object: (skip) + * @object_ptr: a pointer to a #GstObject reference + * + * Clears a reference to a #GstObject. + * + * @object_ptr must not be %NULL. + * + * If the reference is %NULL then this function does nothing. + * Otherwise, the reference count of the object is decreased using + * gst_object_unref() and the pointer is set to %NULL. + * + * A macro is also included that allows this function to be used without + * pointer casts. + * + * Since: 1.16 + **/ +#undef gst_clear_object +void +gst_clear_object (GstObject ** object_ptr) +{ + g_clear_pointer (object_ptr, gst_object_unref); +} + +/** * gst_object_replace: - * @oldobj: (inout) (transfer full): pointer to a place of a #GstObject to - * replace - * @newobj: (transfer none): a new #GstObject + * @oldobj: (inout) (transfer full) (nullable): pointer to a place of + * a #GstObject to replace + * @newobj: (transfer none) (allow-none): a new #GstObject * * Atomically modifies a pointer to point to a new object. * The reference count of @oldobj is decreased and the reference count of * @newobj is increased. * - * Either @newobj and the value pointed to by @oldobj may be NULL. + * Either @newobj and the value pointed to by @oldobj may be %NULL. * - * Returns: TRUE if @newobj was different from @oldobj + * Returns: %TRUE if @newobj was different from @oldobj */ gboolean gst_object_replace (GstObject ** oldobj, GstObject * newobj) @@ -359,7 +377,7 @@ gst_object_dispose (GObject * object) GstObject *self = (GstObject *) object; GstObject *parent; - GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "dispose"); + GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p dispose", object); GST_OBJECT_LOCK (object); if ((parent = GST_OBJECT_PARENT (object))) @@ -401,16 +419,14 @@ gst_object_finalize (GObject * object) { GstObject *gstobject = GST_OBJECT_CAST (object); - GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "finalize"); + GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p finalize", object); g_signal_handlers_destroy (object); g_free (gstobject->name); g_mutex_clear (&gstobject->lock); -#ifndef GST_DISABLE_TRACE - _gst_alloc_trace_free (_gst_object_trace, object); -#endif + GST_TRACER_OBJECT_DESTROYED (gstobject); ((GObjectClass *) gst_object_parent_class)->finalize (object); } @@ -474,7 +490,7 @@ gst_object_dispatch_properties_changed (GObject * object, * @orig: a #GstObject that initiated the notify. * @pspec: a #GParamSpec of the property. * @excluded_props: (array zero-terminated=1) (element-type gchar*) (allow-none): - * a set of user-specified properties to exclude or NULL to show + * a set of user-specified properties to exclude or %NULL to show * all changes. * * A default deep_notify signal callback for an object. The user data @@ -581,15 +597,15 @@ had_parent: /** * gst_object_set_name: * @object: a #GstObject - * @name: new name of object + * @name: (allow-none): new name of object * * Sets the name of @object, or gives @object a guaranteed unique - * name (if @name is NULL). + * name (if @name is %NULL). * This function makes a copy of the provided name, so the caller * retains ownership of the name it sent. * - * Returns: TRUE if the name could be set. Since Objects that have - * a parent cannot be renamed, this function returns FALSE in those + * Returns: %TRUE if the name could be set. Since Objects that have + * a parent cannot be renamed, this function returns %FALSE in those * cases. * * MT safe. This function grabs and releases @object's LOCK. @@ -616,10 +632,8 @@ gst_object_set_name (GstObject * object, const gchar * name) GST_OBJECT_UNLOCK (object); result = gst_object_set_name_default (object); } - /* FIXME-0.11: this misses a g_object_notify (object, "name"); unless called - * from gst_object_set_property. - * Ideally remove such custom setters (or make it static). - */ + + g_object_notify (G_OBJECT (object), "name"); return result; /* error */ @@ -637,12 +651,13 @@ had_parent: * * Returns a copy of the name of @object. * Caller should g_free() the return value after usage. - * For a nameless object, this returns NULL, which you can safely g_free() + * For a nameless object, this returns %NULL, which you can safely g_free() * as well. * * Free-function: g_free * - * Returns: (transfer full): the name of @object. g_free() after usage. + * Returns: (transfer full) (nullable): the name of @object. g_free() + * after usage. * * MT safe. This function grabs and releases @object's LOCK. */ @@ -662,13 +677,13 @@ gst_object_get_name (GstObject * object) /** * gst_object_set_parent: - * @object: a #GstObject + * @object: (transfer floating): a #GstObject * @parent: new parent of object * * Sets the parent of @object to @parent. The object's reference count will * be incremented, and any floating reference will be removed (see gst_object_ref_sink()). * - * Returns: TRUE if @parent could be set or FALSE when @object + * Returns: %TRUE if @parent could be set or %FALSE when @object * already had a parent or @object and @parent are the same. * * MT safe. Grabs and releases @object's LOCK. @@ -691,9 +706,11 @@ gst_object_set_parent (GstObject * object, GstObject * parent) gst_object_ref_sink (object); GST_OBJECT_UNLOCK (object); - /* FIXME, this does not work, the deep notify takes the lock from the parent - * object and deadlocks when the parent holds its lock when calling this - * function (like _element_add_pad()) */ + /* FIXME-2.0: this does not work, the deep notify takes the lock from the + * parent object and deadlocks when the parent holds its lock when calling + * this function (like _element_add_pad()), we need to use a GRecMutex + * for locking the parent instead. + */ /* g_object_notify_by_pspec ((GObject *)object, properties[PROP_PARENT]); */ return TRUE; @@ -703,6 +720,8 @@ had_parent: { GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object, "set parent failed, object already had a parent"); + gst_object_ref_sink (object); + gst_object_unref (object); GST_OBJECT_UNLOCK (object); return FALSE; } @@ -715,8 +734,8 @@ had_parent: * Returns the parent of @object. This function increases the refcount * of the parent object so you should gst_object_unref() it after usage. * - * Returns: (transfer full): parent of @object, this can be NULL if @object - * has no parent. unref after usage. + * Returns: (transfer full) (nullable): parent of @object, this can be + * %NULL if @object has no parent. unref after usage. * * MT safe. Grabs and releases @object's LOCK. */ @@ -769,19 +788,47 @@ gst_object_unparent (GstObject * object) } /** - * gst_object_has_ancestor: + * gst_object_has_as_parent: + * @object: a #GstObject to check + * @parent: a #GstObject to check as parent + * + * Check if @parent is the parent of @object. + * E.g. a #GstElement can check if it owns a given #GstPad. + * + * Returns: %FALSE if either @object or @parent is %NULL. %TRUE if @parent is + * the parent of @object. Otherwise %FALSE. + * + * MT safe. Grabs and releases @object's locks. + * Since: 1.6 + */ +gboolean +gst_object_has_as_parent (GstObject * object, GstObject * parent) +{ + gboolean result = FALSE; + + if (G_LIKELY (GST_IS_OBJECT (object) && GST_IS_OBJECT (parent))) { + GST_OBJECT_LOCK (object); + result = GST_OBJECT_PARENT (object) == parent; + GST_OBJECT_UNLOCK (object); + } + + return result; +} + +/** + * gst_object_has_as_ancestor: * @object: a #GstObject to check * @ancestor: a #GstObject to check as ancestor * * Check if @object has an ancestor @ancestor somewhere up in * the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline. * - * Returns: TRUE if @ancestor is an ancestor of @object. + * Returns: %TRUE if @ancestor is an ancestor of @object. * * MT safe. Grabs and releases @object's locks. */ gboolean -gst_object_has_ancestor (GstObject * object, GstObject * ancestor) +gst_object_has_as_ancestor (GstObject * object, GstObject * ancestor) { GstObject *parent, *tmp; @@ -804,6 +851,28 @@ gst_object_has_ancestor (GstObject * object, GstObject * ancestor) } /** + * gst_object_has_ancestor: + * @object: a #GstObject to check + * @ancestor: a #GstObject to check as ancestor + * + * Check if @object has an ancestor @ancestor somewhere up in + * the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline. + * + * Returns: %TRUE if @ancestor is an ancestor of @object. + * + * Deprecated: Use gst_object_has_as_ancestor() instead. + * + * MT safe. Grabs and releases @object's locks. + */ +#ifndef GST_REMOVE_DEPRECATED +gboolean +gst_object_has_ancestor (GstObject * object, GstObject * ancestor) +{ + return gst_object_has_as_ancestor (object, ancestor); +} +#endif + +/** * gst_object_check_uniqueness: * @list: (transfer none) (element-type Gst.Object): a list of #GstObject to * check through @@ -813,10 +882,10 @@ gst_object_has_ancestor (GstObject * object, GstObject * ancestor) * does not do any locking of any kind. You might want to protect the * provided list with the lock of the owner of the list. This function * will lock each #GstObject in the list to compare the name, so be - * carefull when passing a list with a locked object. + * careful when passing a list with a locked object. * - * Returns: TRUE if a #GstObject named @name does not appear in @list, - * FALSE if it does. + * Returns: %TRUE if a #GstObject named @name does not appear in @list, + * %FALSE if it does. * * MT safe. Grabs and releases the LOCK of each object in the list. */ @@ -921,7 +990,7 @@ gst_object_get_path_string (GstObject * object) path = g_strdup (""); /* first walk the object hierarchy to build a list of the parents, - * be carefull here with refcounting. */ + * be careful here with refcounting. */ do { if (GST_IS_OBJECT (object)) { parent = gst_object_get_parent (object); @@ -983,8 +1052,8 @@ gst_object_get_path_string (GstObject * object) * * Searches the list of properties under control. * - * Returns: a #GstControlBinding or %NULL if the property is not being - * controlled. + * Returns: (nullable): a #GstControlBinding or %NULL if the property + * is not being controlled. */ static GstControlBinding * gst_object_find_control_binding (GstObject * self, const gchar * name) @@ -1085,7 +1154,7 @@ gst_object_sync_values (GstObject * object, GstClockTime timestamp) * gst_object_has_active_control_bindings: * @object: the object that has controlled properties * - * Check if the @object has an active controlled properties. + * Check if the @object has active controlled properties. * * Returns: %TRUE if the object has active controlled properties */ @@ -1136,8 +1205,8 @@ gst_object_set_control_bindings_disabled (GstObject * object, gboolean disabled) * @disabled: boolean that specifies whether to disable the controller * or not. * - * This function is used to disable the #GstController on a property for - * some time, i.e. gst_controller_sync_values() will do nothing for the + * This function is used to disable the control bindings on a property for + * some time, i.e. gst_object_sync_values() will do nothing for the * property. */ void @@ -1160,12 +1229,13 @@ gst_object_set_control_binding_disabled (GstObject * object, /** * gst_object_add_control_binding: * @object: the controller object - * @binding: (transfer full): the #GstControlBinding that should be used + * @binding: (transfer floating): the #GstControlBinding that should be used * * Attach the #GstControlBinding to the object. If there already was a * #GstControlBinding for this property it will be replaced. * - * The @object will take ownership of the @binding. + * The object's reference count will be incremented, and any floating + * reference will be removed (see gst_object_ref_sink()) * * Returns: %FALSE if the given @binding has not been setup for this object or * has been setup for a non suitable property, %TRUE otherwise. @@ -1201,8 +1271,8 @@ gst_object_add_control_binding (GstObject * object, GstControlBinding * binding) * Gets the corresponding #GstControlBinding for the property. This should be * unreferenced again after use. * - * Returns: (transfer full): the #GstControlBinding for @property_name or %NULL if - * the property is not controlled. + * Returns: (transfer full) (nullable): the #GstControlBinding for + * @property_name or %NULL if the property is not controlled. */ GstControlBinding * gst_object_get_control_binding (GstObject * object, const gchar * property_name) @@ -1227,7 +1297,7 @@ gst_object_get_control_binding (GstObject * object, const gchar * property_name) * @binding: the binding * * Removes the corresponding #GstControlBinding. If it was the - * last ref of the binding, it will be disposed. + * last ref of the binding, it will be disposed. * * Returns: %TRUE if the binding could be removed. */ @@ -1262,8 +1332,8 @@ gst_object_remove_control_binding (GstObject * object, * * Gets the value for the given controlled property at the requested time. * - * Returns: the GValue of the property at the given time, or %NULL if the - * property isn't controlled. + * Returns: (nullable): the GValue of the property at the given time, + * or %NULL if the property isn't controlled. */ GValue * gst_object_get_value (GstObject * object, const gchar * property_name, @@ -1286,7 +1356,7 @@ gst_object_get_value (GstObject * object, const gchar * property_name, } /** - * gst_object_get_value_array: + * gst_object_get_value_array: (skip) * @object: the object that has controlled properties * @property_name: the name of the property to get * @timestamp: the time that should be processed @@ -1301,7 +1371,7 @@ gst_object_get_value (GstObject * object, const gchar * property_name, * This function is useful if one wants to e.g. draw a graph of the control * curve or apply a control curve sample by sample. * - * The values are unboxed and ready to be used. The similar function + * The values are unboxed and ready to be used. The similar function * gst_object_get_g_value_array() returns the array as #GValues and is * better suites for bindings. * @@ -1337,7 +1407,7 @@ gst_object_get_value_array (GstObject * object, const gchar * property_name, * @timestamp: the time that should be processed * @interval: the time spacing between subsequent values * @n_values: the number of values - * @values: array to put control-values in + * @values: (array length=n_values): array to put control-values in * * Gets a number of #GValues for the given controlled property starting at the * requested time. The array @values need to hold enough space for @n_values of @@ -1378,7 +1448,7 @@ gst_object_get_g_value_array (GstObject * object, const gchar * property_name, * * Obtain the control-rate for this @object. Audio processing #GstElement * objects will use this rate to sub-divide their processing loop and call - * gst_object_sync_values() inbetween. The length of the processing segment + * gst_object_sync_values() in between. The length of the processing segment * should be up to @control-rate nanoseconds. * * If the @object is not under property control, this will return @@ -1404,7 +1474,7 @@ gst_object_get_control_rate (GstObject * object) * * Change the control-rate for this @object. Audio processing #GstElement * objects will use this rate to sub-divide their processing loop and call - * gst_object_sync_values() inbetween. The length of the processing segment + * gst_object_sync_values() in between. The length of the processing segment * should be up to @control-rate nanoseconds. * * The control-rate should not change if the element is in %GST_STATE_PAUSED or