mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-28 12:41:05 +00:00
79 lines
3.1 KiB
Markdown
79 lines
3.1 KiB
Markdown
# 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.
|