mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-25 09:40:37 +00:00
91 lines
3.2 KiB
Text
91 lines
3.2 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 requirements 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)
|
|
|
|
|
|
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.
|