gstreamer/docs/design/part-gstobject.txt
Thomas Vander Stichele 5d24ac1be7 make names only settable when unparented, so we can guarantee uniqueness inside a parent together with the _add checks
Original commit message from CVS:
make names only settable when unparented, so we can guarantee
uniqueness inside a parent together with the _add checks

2
2004-12-13 19:23:04 +00:00

52 lines
2.2 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 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()
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.