mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-09 05:38:58 +00:00
Original commit message from CVS: * docs/design/part-MT-refcounting.txt: * docs/design/part-clocks.txt: * docs/design/part-gstelement.txt: * docs/design/part-gstobject.txt: * docs/design/part-standards.txt: * gst/gstbin.c: (gst_bin_add_func), (gst_bin_add), (gst_bin_remove_func), (gst_bin_remove): * gst/gstbin.h: * gst/gstbuffer.c: * gst/gstcaps.h: * testsuite/clock/clock1.c: (main): * testsuite/clock/clock2.c: (gst_clock_debug), (element_wait), (main): * testsuite/dlopen/loadgst.c: (do_test): * testsuite/refcounting/bin.c: (add_remove_test1), (add_remove_test2), (main): * testsuite/refcounting/element.c: (main): * testsuite/refcounting/element_pad.c: (main): * testsuite/refcounting/pad.c: (main): * tools/gst-launch.c: (sigint_handler_sighandler): * tools/gst-typefind.c: (main): Doc updates. Added doc about clock. removed gst_bin_iterate_recurse_up(), marked methods for removal. Fix more testsuites.
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.
|
|
|
|
|
|
|