[Bug 793011] GstAdapter: Improve documentation for gst_adapter_available()

[GStreamer (GNOME Bugzilla)]

https://bugzilla.gnome.org/show_bug.cgi?id=793011

--- Comment #4 from Tim-Philipp Müller <t.i.m at zen.co.uk> ---
Comment on attachment 367594
  --> https://bugzilla.gnome.org/attachment.cgi?id=367594
GstAdapter: Improve documentation for gst_adapter_available()

>When I first read the documentation of gst_adapter_available() and
>gst_adapter_available_free() I got quite confused as it seemed that both
>performed the same purpose but one was slower than the other.
>
>I shared it with other people and found they also arrived at the same
>wrong conclusion.
>
>Hopefully this patch will make the actual purpose clearer.

I find it hard to believe that anyone could be confused after reading the
actual description of both functions and return values side by side ("Returns:
number of bytes available in adapter" vs "Returns: number of bytes that are
available in adapter without expensive operations"), but it's always possible
to make things clearer of course :)


>diff --git a/libs/gst/base/gstadapter.c b/libs/gst/base/gstadapter.c
>index e3dff288f..d4c7b8f5e 100644
>--- a/libs/gst/base/gstadapter.c
>+++ b/libs/gst/base/gstadapter.c
>@@ -1313,6 +1313,10 @@ gst_adapter_get_buffer_list (GstAdapter * adapter, gsize nbytes)
>  * value that can be supplied to gst_adapter_map() without that function
>  * returning %NULL.
>  *
>+ * Calling gst_adapter_map() with the amount of bytes returned by this function
>+ * may require expensive operations (like copying the data into a temporary
>+ * buffer) in some cases.
>+ *

How about we also explicitly mention the _fast() variant here for comparison
then?



>@@ -1327,8 +1331,11 @@ gst_adapter_available (GstAdapter * adapter)
>  * gst_adapter_available_fast:
>  * @adapter: a #GstAdapter
>  *
>- * Gets the maximum number of bytes that are immediately available without
>- * requiring any expensive operations (like copying the data into a
>+ * Gets the maximum number of bytes that can be retrieved in a single map
>+ * operation without merging buffers.

Here I think the previous version is actually clearer. You seem very focused on
gst_adapter_map() here, but a user of the adapter API might access the data in
the adapter in a number of ways, and the existing sentence is more generic.
It's not clear to me that talking about "a single map" here makes things much
clearer. It's not the mapping that's the problem, it's the copying/merging. And
the term "map" is overloaded from buffers and memories as well as the adapter
peeking function which probably shouldn't have been called _map() but we are
where we are :)


>+ * Calling gst_adapter_map() with the amount of bytes returned by this function
>+ * will never require any expensive operations (like copying the data into a
>  * temporary buffer).
>  *
>  * Returns: number of bytes that are available in @adapter without expensive

-- 
You are receiving this mail because:
You are the QA Contact for the bug.
You are the assignee for the bug.