mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-07-05 14:16:06 +00:00
29177515ff
Original commit message from CVS: * check/gst/gstobject.c: * docs/design/part-gstelement.txt: * docs/design/part-gstobject.txt: * gst/gstobject.c: * gst/gstobject.h: add _get/_set_name_prefix() for debugging. Update docs. Finish unique name unit test
73 lines
2.8 KiB
Plaintext
73 lines
2.8 KiB
Plaintext
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.
|
|
GStreamer 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.
|
|
|
|
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.
|
|
|
|
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 and refcounting, which is
|
|
reasonable, since they are the only possible things to protect in the
|
|
GstObject.
|
|
|
|
Path Generation
|
|
---------------
|
|
FIXME: rethink this ?
|
|
|
|
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. Currently it is forced
|
|
to use several child-class-specific functions, because we do not properly use
|
|
the base capabilities (parentage, etc.) of GstObject properly.
|