mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-08 21:28:45 +00:00
Unify the ad-hoc markup to be asciidoc style in many places. Add a "html" target to Makefile to generate the output.
54 lines
1.6 KiB
Text
54 lines
1.6 KiB
Text
Ownership of dynamic objects
|
|
----------------------------
|
|
|
|
Any object-oriented system or language that doesn't have automatic garbage
|
|
collection has many potential pitfalls as far as the pointers go. Therefore,
|
|
some standards must be adhered to as far as who owns what.
|
|
|
|
Strings
|
|
~~~~~~~
|
|
|
|
Arguments passed into a function are owned by the caller, and the function
|
|
will make a copy of the string for its own internal use. The string should
|
|
be const gchar *. Strings returned from a function are always a copy of the
|
|
original and should be freed after usage by the caller.
|
|
|
|
ex:
|
|
|
|
name = gst_element_get_name (element); /* copy of name is made */
|
|
.. use name ..
|
|
g_free (name); /* free after usage */
|
|
|
|
|
|
Objects
|
|
~~~~~~~
|
|
|
|
Objects passed into a function are owned by the caller, any additional
|
|
reference held to the object after leaving the function should increase the
|
|
refcount of that object.
|
|
|
|
Objects returned from a function are owned by the caller. This means that the
|
|
called should _free() or _unref() the object after usage.
|
|
|
|
ex:
|
|
|
|
peer = gst_pad_get_peer (pad); /* peer with increased refcount */
|
|
if (peer) {
|
|
.. use peer ..
|
|
gst_object_unref (GST_OBJECT (peer)); /* unref peer after usage */
|
|
}
|
|
|
|
|
|
Iterators
|
|
~~~~~~~~~
|
|
|
|
When retrieving multiple objects from an object an iterator should be used.
|
|
The iterator allows you to access the objects one after another while making
|
|
sure that the set of objects retrieved remains consistent.
|
|
|
|
Each object retrieved from an iterator has its refcount increased or is a
|
|
copy of the original. In any case the object should be unreffed or freed
|
|
after usage.
|
|
|
|
|
|
|