gstreamer/docs/design/part-gstobject.txt

43 lines
2.2 KiB
Text
Raw Normal View History

GstObject
=========
The base class for the entire GStreamer hierarchy is the GstObject. It is currently a bit of a hack caused by the
fact that GStreamer is built on top of GtkObject. GObject should help, if it's designed properly. Currently the
capabilities provided by GstObject are quite underutilized, this will be fixed with a refactoring of the
object system and a code cleanup at some point in the future. If nothing else, it serves as an easy check to see if a
given object belongs to GStreamer.
Parentage
---------
A pointer is available to store the current parent of the object. This 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.
Refcounting
-----------
A reference count is kept for the object. When this is fully utilized, it will enable generic destruction of objects
by simply reducing the reference count to zero. GObject should provide these capabilities, however.
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. 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.
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
---------------
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.