From 30f871d274e8a544779c287a1a4c188f22c2066f Mon Sep 17 00:00:00 2001 From: =?utf8?q?Sebastian=20Dr=C3=B6ge?= Date: Mon, 15 May 2017 14:32:00 +0300 Subject: [PATCH] gst: Correctly annotate functions taking floating reference parameters and returning floating references https://bugzilla.gnome.org/show_bug.cgi?id=702960 --- gst/gstdevicemonitor.c | 2 +- gst/gstdeviceprovider.c | 11 ++++++++--- gst/gstelement.c | 7 +++++-- gst/gstghostpad.c | 6 +++--- gst/gstobject.c | 7 ++++--- gst/gstpadtemplate.c | 2 +- gst/gstplugin.c | 4 ++++ gst/gstregistry.c | 12 ++++++++---- gst/gststreamcollection.c | 2 +- gst/gststreams.c | 2 +- gst/gsttracerrecord.c | 2 +- gst/gstutils.c | 4 ++-- libs/gst/controller/gstproxycontrolbinding.c | 2 +- libs/gst/net/gstnettimeprovider.c | 2 +- 14 files changed, 41 insertions(+), 24 deletions(-) diff --git a/gst/gstdevicemonitor.c b/gst/gstdevicemonitor.c index 79c65ce..123d284 100644 --- a/gst/gstdevicemonitor.c +++ b/gst/gstdevicemonitor.c @@ -785,7 +785,7 @@ gst_device_monitor_remove_filter (GstDeviceMonitor * monitor, guint filter_id) * * Create a new #GstDeviceMonitor * - * Returns: (transfer full): a new device monitor. + * Returns: (transfer floating): a new device monitor. * * Since: 1.4 */ diff --git a/gst/gstdeviceprovider.c b/gst/gstdeviceprovider.c index f5ba92e..8038d02 100644 --- a/gst/gstdeviceprovider.c +++ b/gst/gstdeviceprovider.c @@ -543,13 +543,16 @@ gst_device_provider_get_bus (GstDeviceProvider * provider) /** * gst_device_provider_device_add: * @provider: a #GstDeviceProvider - * @device: (transfer full): a #GstDevice that has been added + * @device: (transfer floating): a #GstDevice that has been added * * Posts a message on the provider's #GstBus to inform applications that * a new device has been added. * * This is for use by subclasses. * + * @device's reference count will be incremented, and any floating reference + * will be removed (see gst_object_ref_sink()). + * * Since: 1.4 */ void @@ -568,8 +571,10 @@ gst_device_provider_device_add (GstDeviceProvider * provider, } GST_OBJECT_LOCK (provider); - provider->devices = g_list_prepend (provider->devices, - gst_object_ref (device)); + /* Take an additional reference so we can be sure nobody removed it from the + * provider in the meantime and we can safely emit the message */ + gst_object_ref (device); + provider->devices = g_list_prepend (provider->devices, device); GST_OBJECT_UNLOCK (provider); message = gst_message_new_device_added (GST_OBJECT (provider), device); diff --git a/gst/gstelement.c b/gst/gstelement.c index e4f68da..231fd83 100644 --- a/gst/gstelement.c +++ b/gst/gstelement.c @@ -635,7 +635,7 @@ gst_element_get_index (GstElement * element) /** * gst_element_add_pad: * @element: a #GstElement to add the pad to. - * @pad: (transfer full): the #GstPad to add to the element. + * @pad: (transfer floating): the #GstPad to add to the element. * * Adds a pad (link point) to @element. @pad's parent will be set to @element; * see gst_object_set_parent() for refcounting information. @@ -1250,12 +1250,15 @@ gst_element_iterate_sink_pads (GstElement * element) /** * gst_element_class_add_pad_template: * @klass: the #GstElementClass to add the pad template to. - * @templ: (transfer full): a #GstPadTemplate to add to the element class. + * @templ: (transfer floating): a #GstPadTemplate to add to the element class. * * Adds a padtemplate to an element class. This is mainly used in the _class_init * functions of classes. If a pad template with the same name as an already * existing one is added the old one is replaced by the new one. * + * @templ's reference count will be incremented, and any floating + * reference will be removed (see gst_object_ref_sink()) + * */ void gst_element_class_add_pad_template (GstElementClass * klass, diff --git a/gst/gstghostpad.c b/gst/gstghostpad.c index cd96668..478d274 100644 --- a/gst/gstghostpad.c +++ b/gst/gstghostpad.c @@ -658,7 +658,7 @@ construct_failed: * * The created ghostpad will not have a padtemplate. * - * Returns: (transfer full) (nullable): a new #GstPad, or %NULL in + * Returns: (transfer floating) (nullable): a new #GstPad, or %NULL in * case of an error. */ GstPad * @@ -726,7 +726,7 @@ set_target_failed: * * Will ref the target. * - * Returns: (transfer full) (nullable): a new #GstPad, or %NULL in + * Returns: (transfer floating) (nullable): a new #GstPad, or %NULL in * case of an error. */ @@ -769,7 +769,7 @@ set_target_failed: * Create a new ghostpad based on @templ, without setting a target. The * direction will be taken from the @templ. * - * Returns: (transfer full) (nullable): a new #GstPad, or %NULL in + * Returns: (transfer floating) (nullable): a new #GstPad, or %NULL in * case of an error. */ GstPad * diff --git a/gst/gstobject.c b/gst/gstobject.c index 50fa1c7..1bf9f72 100644 --- a/gst/gstobject.c +++ b/gst/gstobject.c @@ -650,7 +650,7 @@ 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 @@ -1202,12 +1202,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. diff --git a/gst/gstpadtemplate.c b/gst/gstpadtemplate.c index ce272ca..8666ed1 100644 --- a/gst/gstpadtemplate.c +++ b/gst/gstpadtemplate.c @@ -284,7 +284,7 @@ G_DEFINE_POINTER_TYPE (GstStaticPadTemplate, gst_static_pad_template); * * Converts a #GstStaticPadTemplate into a #GstPadTemplate. * - * Returns: (transfer full): a new #GstPadTemplate. + * Returns: (transfer floating): a new #GstPadTemplate. */ /* FIXME0.11: rename to gst_pad_template_new_from_static_pad_template() */ GstPadTemplate * diff --git a/gst/gstplugin.c b/gst/gstplugin.c index 7331a31..ac27c16 100644 --- a/gst/gstplugin.c +++ b/gst/gstplugin.c @@ -710,6 +710,10 @@ extract_symname (const char *filename) return symname; } +/* Note: The return value is (transfer full) although we work with floating + * references here. If a new plugin instance is created, it is always sinked + * in the registry first and a new reference is returned + */ GstPlugin * _priv_gst_plugin_load_file_for_registry (const gchar * filename, GstRegistry * registry, GError ** error) diff --git a/gst/gstregistry.c b/gst/gstregistry.c index 198ca5f..983946f 100644 --- a/gst/gstregistry.c +++ b/gst/gstregistry.c @@ -410,10 +410,12 @@ gst_registry_get_path_list (GstRegistry * registry) /** * gst_registry_add_plugin: * @registry: the registry to add the plugin to - * @plugin: (transfer full): the plugin to add + * @plugin: (transfer floating): the plugin to add * * Add the plugin to the registry. The plugin-added signal will be emitted. - * This function will sink @plugin. + * + * @plugin's reference count will be incremented, and any floating + * reference will be removed (see gst_object_ref_sink()) * * Returns: %TRUE on success. * @@ -542,10 +544,12 @@ gst_registry_remove_plugin (GstRegistry * registry, GstPlugin * plugin) /** * gst_registry_add_feature: * @registry: the registry to add the plugin to - * @feature: (transfer full): the feature to add + * @feature: (transfer floating): the feature to add * * Add the feature to the registry. The feature-added signal will be emitted. - * This function sinks @feature. + * + * @feature's reference count will be incremented, and any floating + * reference will be removed (see gst_object_ref_sink()) * * Returns: %TRUE on success. * diff --git a/gst/gststreamcollection.c b/gst/gststreamcollection.c index 5ad8940..c1d4674 100644 --- a/gst/gststreamcollection.c +++ b/gst/gststreamcollection.c @@ -184,7 +184,7 @@ gst_stream_collection_finalize (GObject * object) * * Create a new #GstStreamCollection. * - * Returns: The new #GstStreamCollection. + * Returns: (transfer floating): The new #GstStreamCollection. * * Since: 1.10 */ diff --git a/gst/gststreams.c b/gst/gststreams.c index b61e61b..8873aad 100644 --- a/gst/gststreams.c +++ b/gst/gststreams.c @@ -210,7 +210,7 @@ gst_stream_finalize (GObject * object) * Create a new #GstStream for the given @stream_id, @caps, @type * and @flags * - * Returns: The new #GstStream + * Returns: (transfer floating): The new #GstStream * * Since: 1.10 */ diff --git a/gst/gsttracerrecord.c b/gst/gsttracerrecord.c index c6651d2..889479d 100644 --- a/gst/gsttracerrecord.c +++ b/gst/gsttracerrecord.c @@ -178,7 +178,7 @@ gst_tracer_record_init (GstTracerRecord * self) * * > Please note that this is still under discussion and subject to change. * - * Returns: a new #GstTracerRecord + * Returns: (transfer floating): a new #GstTracerRecord */ GstTracerRecord * gst_tracer_record_new (const gchar * name, const gchar * firstfield, ...) diff --git a/gst/gstutils.c b/gst/gstutils.c index 94fb513..3d26d47 100644 --- a/gst/gstutils.c +++ b/gst/gstutils.c @@ -2567,8 +2567,8 @@ gst_object_default_error (GstObject * source, const GError * error, /** * gst_bin_add_many: * @bin: a #GstBin - * @element_1: (transfer full): the #GstElement element to add to the bin - * @...: (transfer full): additional elements to add to the bin + * @element_1: (transfer floating): the #GstElement element to add to the bin + * @...: (transfer floating): additional elements to add to the bin * * Adds a %NULL-terminated list of elements to a bin. This function is * equivalent to calling gst_bin_add() for each member of the list. The return diff --git a/libs/gst/controller/gstproxycontrolbinding.c b/libs/gst/controller/gstproxycontrolbinding.c index 17a08a7..660a3df 100644 --- a/libs/gst/controller/gstproxycontrolbinding.c +++ b/libs/gst/controller/gstproxycontrolbinding.c @@ -174,7 +174,7 @@ gst_proxy_control_binding_class_init (GstProxyControlBindingClass * klass) * requests from @property_name on @object to the control binding at * @ref_property_name on @ref_object. * - * Returns: a new #GstControlBinding that proxies the control interface between + * Returns: (transfer floating): a new #GstControlBinding that proxies the control interface between * properties on different #GstObject's * * Since: 1.12 diff --git a/libs/gst/net/gstnettimeprovider.c b/libs/gst/net/gstnettimeprovider.c index fee3ec1..0c0ef69 100644 --- a/libs/gst/net/gstnettimeprovider.c +++ b/libs/gst/net/gstnettimeprovider.c @@ -434,7 +434,7 @@ gst_net_time_provider_initable_iface_init (gpointer g_iface) * * Allows network clients to get the current time of @clock. * - * Returns: the new #GstNetTimeProvider, or NULL on error + * Returns: (transfer floating): the new #GstNetTimeProvider, or NULL on error */ GstNetTimeProvider * gst_net_time_provider_new (GstClock * clock, const gchar * address, gint port) -- 2.7.4