docs/design/part-gstobject.txt

   1 GstObject
   2 ---------
   3
   4 The base class for the entire GStreamer hierarchy is the GstObject.
   5
   6 Parentage
   7 ~~~~~~~~~
   8
   9 A pointer is available to store the current parent of the object.  This is one
  10 of the two fundamental requirements for a hierarchical system such as GStreamer
  11 (for the other, read up on GstBin).  Three functions are provided:
  12 _set_parent(), _get_parent(), and _unparent().  The third is required because
  13 there is an explicit check in _set_parent(): an object must not already have a
  14 parent if you wish to set one.  You must unparent the object first.  This
  15 allows for new additions later.
  16
  17 - GstObject's that can be parented:
  18   GstElement (inside a bin)
  19   GstPad (inside an element)
  20
  21
  22 Naming
  23 ~~~~~~
  24
  25 - names of objects cannot be changed when they are parented
  26 - names of objects should be unique across parent
  27 - set_name() can fail because of this
  28 - as can gst_element_add_pad()/gst_bin_add_element()
  29 - gst_object_set_name() only changes the object's name
  30
  31 - objects also have a name_prefix that is used to prefix the object name
  32   during debugging and identification
  33 - there are object-specific set_name's() which also set the name_prefix
  34   on the object.  This is useful for debugging purposes to give the object
  35   a more identifiable name.  Typically a parent will call _set_name_prefix
  36   on children, taking a lock on them to do so.
  37
  38
  39 Locking
  40 ~~~~~~~
  41
  42 The GstObject contains the necessary primitives to lock the object in a
  43 thread-safe manner.  This will be used to provide general thread-safety as
  44 needed.  However, this lock is generic, i.e. it covers the whole object.
  45
  46 The object LOCK is a very lowlevel lock that should only be held to access
  47 the object properties for short periods of code.
  48
  49 All members of the GstObject structure marked as
  50 /*< public >*/ /* with LOCK */
  51 are protected by this lock.  These members can only be accessed for reading
  52 or writing while the lock is held. All members should be copied or reffed
  53 if they are used after releasing the LOCK.
  54
  55 Note that this does *not* mean that no other thread can modify the object at
  56 the same time that the lock is held.  It only means that any two sections of
  57 code that obey the lock are guaranteed to not be running simultaneously.  "The
  58 lock is voluntary and cooperative".
  59
  60 This lock will ideally be used for parentage, flags and naming, which is
  61 reasonable, since they are the only possible things to protect in the
  62 GstObject.
  63
  64
  65 Locking order
  66 ~~~~~~~~~~~~~
  67
  68 In parent-child situations the lock of the parent must always be taken first
  69 before taking the lock of the child. It is NOT allowed to hold the child
  70 lock before taking the parent lock.
  71
  72 This policy allows for parents to iterate their children and setting properties
  73 on them.
  74
  75 Whenever a nested lock needs to be taken on objects not involved in a
  76 parent-child relation (eg. pads), an explictic locking order has to be defined.
  77
  78
  79 Path Generation
  80 ~~~~~~~~~~~~~~~
  81
  82 Due to the base nature of the GstObject, it becomes the only reasonable place
  83 to put this particular function (_get_path_string).  It will generate a string
  84 describing the parent hierarchy of a given GstObject.
  85
  86
  87 Flags
  88 ~~~~~
  89
  90 Each object in the GStreamer object hierarchy can have flags associated with it,
  91 which are used to describe a state or a feature of the object.