[gstreamer-bugs] [Bug 533856] gst_buffer_join() documentation is unclear

[GStreamer (bugzilla.gnome.org)]

If you have any questions why you received this email, please see the text at
the end of this email. Replies to this email are NOT read, please see the text
at the end of this email. You can add comments to this bug at:
  http://bugzilla.gnome.org/show_bug.cgi?id=533856

  GStreamer | gstreamer (core) | Ver: HEAD CVS

Tim-Philipp Müller changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |t.i.m at zen.co.uk
             Status|UNCONFIRMED                 |NEEDINFO




------- Comment #1 from Tim-Philipp Müller  2008-05-19 14:48 UTC -------
> The gst_buffer_join() documentation says that it unrefs the input parameters
> and mentions using their data without copying it. This suggests that the input
> parameters are made invalid, meaning I shouldn't use them again, regardless of
> their refcount. Is this true?

No, this isn't true. In the case where no copying is done the input buffers are
adjacent subbuffers of the same parent buffer, which makes the input buffer
already not-writable (gst_buffer_is_writable), and the returned buffer will
also be not writable in that case.

The caller may keep a reference to the input buffers and in that case continue
to access the data and metadata as it likes (within the usual constrains that
are true for any buffer, ie. not modify the data if it's not writable and not
modify the metadata if the metadata is not writable).

(Anything else doesn't really make sense either, since any other piece of code,
be it another element or the application, could still hold a reference to any
of the input buffers.)

Would be great if you could edit/extend the gtk-doc documentation blurb in
gstutils.c so that it makes sense to you (doesn't have to be a patch if you
don't have a checkout at hand):

http://webcvs.freedesktop.org/gstreamer/gstreamer/gst/gstutils.c?view=markup


> Unrefing of input parameters is generally weird and awkward for language
> bindings, by the way.

Well, it's a utility function for C programmers that want to avoid the tedious
unrefs. You don't have to wrap it if it doesn't make sense in the context of
your language binding.


-- 
See http://bugzilla.gnome.org/page.cgi?id=email.html for more info about why you received
this email, why you can't respond via email, how to stop receiving
emails (or reduce the number you receive), and how to contact someone
if you are having problems with the system.

You can add comments to this bug at http://bugzilla.gnome.org/show_bug.cgi?id=533856.