appsrc: Clarify buffer ref semantics in signals

The documentation could be read to mean that the caller continuous to
'own' the buffer, and that there is some other mechanism to find out
when to unref it.

Clarify that "not taking ownership" here means "taking a reference",
and specify that you can unref it at any time after calling the
function.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/2110>

diff --git a/subprojects/gst-plugins-base/gst-libs/gst/app/gstappsrc.c b/subprojects/gst-plugins-base/gst-libs/gst/app/gstappsrc.c
index 16d2a325c11e65ca48a56f77338db6955782db71..0a26bdee20d2e22e5956a8b51520ce07082c7b24 100644 (file)
--- a/subprojects/gst-plugins-base/gst-libs/gst/app/gstappsrc.c
+++ b/subprojects/gst-plugins-base/gst-libs/gst/app/gstappsrc.c
@@ -621,11 +621,14 @@ gst_app_src_class_init (GstAppSrcClass * klass)
    /**
     * GstAppSrc::push-buffer:
     * @appsrc: the appsrc
-    * @buffer: a buffer to push
+    * @buffer (transfer none): a buffer to push
     *
     * Adds a buffer to the queue of buffers that the appsrc element will
-    * push to its source pad. This function does not take ownership of the
-    * buffer so the buffer needs to be unreffed after calling this function.
+    * push to its source pad.
+    *
+    * This function does not take ownership of the buffer, but it takes a
+    * reference so the buffer can be unreffed at any time after calling this
+    * function.
     *
     * When the block property is TRUE, this function can block until free space
     * becomes available in the queue.
@@ -639,12 +642,14 @@ gst_app_src_class_init (GstAppSrcClass * klass)
    /**
     * GstAppSrc::push-buffer-list:
     * @appsrc: the appsrc
-    * @buffer_list: a buffer list to push
+    * @buffer_list (transfer none): a buffer list to push
     *
     * Adds a buffer list to the queue of buffers and buffer lists that the
-    * appsrc element will push to its source pad. This function does not take
-    * ownership of the buffer list so the buffer list needs to be unreffed
-    * after calling this function.
+    * appsrc element will push to its source pad.
+    *
+    * This function does not take ownership of the buffer list, but it takes a
+    * reference so the buffer list can be unreffed at any time after calling
+    * this function.
     *
     * When the block property is TRUE, this function can block until free space
     * becomes available in the queue.
@@ -660,7 +665,7 @@ gst_app_src_class_init (GstAppSrcClass * klass)
   /**
     * GstAppSrc::push-sample:
     * @appsrc: the appsrc
-    * @sample: a sample from which extract buffer to push
+    * @sample (transfer none): a sample from which extract buffer to push
     *
     * Extract a buffer from the provided sample and adds the extracted buffer
     * to the queue of buffers that the appsrc element will
@@ -668,8 +673,10 @@ gst_app_src_class_init (GstAppSrcClass * klass)
     * in the sample and reset the caps if they change.
     * Only the caps and the buffer of the provided sample are used and not
     * for example the segment in the sample.
-    * This function does not take ownership of the
-    * sample so the sample needs to be unreffed after calling this function.
+    *
+    * This function does not take ownership of the sample, but it takes a
+    * reference so the sample can be unreffed at any time after calling this
+    * function.
     *
     * When the block property is TRUE, this function can block until free space
     * becomes available in the queue.