mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-05 17:09:48 +00:00
007cff6d75
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.
107 lines
3.8 KiB
Text
107 lines
3.8 KiB
Text
GstObject
|
|
=========
|
|
|
|
The base class for the entire GStreamer hierarchy is the GstObject.
|
|
|
|
Parentage
|
|
---------
|
|
|
|
A pointer is available to store the current parent of the object. This is one
|
|
of the two fundamental requires for a hierarchical system such as GStreamer
|
|
(for the other, read up on GstBin). Three functions are provided:
|
|
_set_parent(), _get_parent(), and _unparent(). The third is required because
|
|
there is an explicit check in _set_parent(): an object must not already have a
|
|
parent if you wish to set one. You must unparent the object first. This
|
|
allows for new additions later.
|
|
|
|
- GstObject's that can be parented:
|
|
GstElement (inside a bin)
|
|
GstPad (inside an element)
|
|
|
|
|
|
Refcounting
|
|
-----------
|
|
- GObject refcount is not threadsafe. This will be changed in the future.
|
|
GStreamer for now sets it to a constant value on each _ref/_unref()
|
|
and uses an atomic int "refcount" instead for threadsafe refcounting
|
|
This implies you should always use gst_object_ref() and gst_object_unref() !
|
|
|
|
|
|
Naming
|
|
------
|
|
- names of objects cannot be changed when they are parented
|
|
- names of objects should be unique across parent
|
|
- set_name() can fail because of this
|
|
- as can gst_element_add_pad()/gst_bin_add_element()
|
|
- gst_object_set_name() only changes the object's name
|
|
|
|
- objects also have a name_prefix that is used to prefix the object name
|
|
during debugging and identification
|
|
- there are object-specific set_name's() which also set the name_prefix
|
|
on the object. This is useful for debugging purposes to give the object
|
|
a more identifiable name. Typically a parent will call _set_name_prefix
|
|
on children, taking a lock on them to do so.
|
|
|
|
|
|
Locking
|
|
-------
|
|
|
|
The GstObject contains the necessary primitives to lock the object in a
|
|
thread-safe manner. This will be used to provide general thread-safety as
|
|
needed. However, this lock is generic, i.e. it covers the whole object.
|
|
|
|
The object LOCK is a very lowlevel lock that should only be held to access
|
|
the object properties for short periods of code.
|
|
|
|
All members of the GstObject structure marked as
|
|
/*< public >*/ /* with LOCK */
|
|
are protected by this lock. These members can only be accessed for reading
|
|
or writing while the lock is held. All members should be copied or reffed
|
|
if they are used after releasing the LOCK.
|
|
|
|
Note that this does *not* mean that no other thread can modify the object at
|
|
the same time that the lock is held. It only means that any two sections of
|
|
code that obey the lock are guaranteed to not be running simultaneously. "The
|
|
lock is voluntary and cooperative".
|
|
|
|
This lock will ideally be used for parentage, flags and naming, which is
|
|
reasonable, since they are the only possible things to protect in the
|
|
GstObject.
|
|
|
|
|
|
Locking order
|
|
-------------
|
|
|
|
In parent-child situations the lock of the parent must always be taken first
|
|
before taking the lock of the child. It is NOT allowed to hold the child
|
|
lock before taking the parent lock.
|
|
|
|
This policy allows for parents to iterate their children and setting properties
|
|
on them.
|
|
|
|
Whenever a nested lock needs to be taken on objects not involved in a
|
|
parent-child relation (eg. pads), an explictic locking order has to be defined.
|
|
|
|
|
|
Path Generation
|
|
---------------
|
|
|
|
Due to the base nature of the GstObject, it becomes the only reasonable place
|
|
to put this particular function (_get_path_string). It will generate a string
|
|
describing the parent hierarchy of a given GstObject.
|
|
|
|
|
|
Flags
|
|
-----
|
|
|
|
Each object in the GStreamer object hierarchy can have flags associated with it,
|
|
which are used to describe a state or a feature of the object.
|
|
GstObject has flags to mark its lifecycle: FLOATING, DISPOSING and DESTROYED.
|
|
|
|
|
|
Class signals
|
|
-------------
|
|
|
|
It is possible to know when a new object is loaded by connecting to the
|
|
GstObjectClass signal. This feature is not very much used and might be removed
|
|
at some point.
|