docs/design/part-miniobject.txt

   1 GstMiniObject
   2 -------------
   3
   4 This document describes the design of the miniobject base class.
   5
   6 The miniobject abstract base class is used to construct lightweight refcounted
   7 and boxed types that are frequently created and destroyed.
   8
   9 Requirements
  10 ~~~~~~~~~~~~
  11
  12  - Be lightweight
  13  - Refcounted
  14  - I must be possible to control access to the object, ie. when the object is
  15    readable and writable.
  16  - Subclasses must be able to use their own allocator for the memory.
  17
  18
  19 Usage
  20 ~~~~~
  21
  22 Users of the GstMiniObject infrastructure will need to define a structure that
  23 includes the GstMiniObject structure as the first field.
  24
  25  struct {
  26    GstMiniObject mini_object;
  27
  28    /* my fields */
  29    ...
  30  } MyObject
  31
  32 The subclass should then implement a constructor method where it allocates the
  33 memory for its structure and initializes the miniobject structure with
  34 gst_mini_object_init(). Copy and Free functions are provided to the
  35 gst_mini_object_init() function.
  36
  37   MyObject *
  38   my_object_new()
  39   {
  40     MyObject *res = g_slice_new (MyObject);
  41
  42     gst_mini_object_init (GST_MINI_OBJECT_CAST (res), 0,
  43         MY_TYPE_OBJECT,
  44         (GstMiniObjectCopyFunction) _my_object_copy,
  45         (GstMiniObjectDisposeFunction) NULL,
  46         (GstMiniObjectFreeFunction) _my_object_free);
  47
  48     /* other init */
  49     .....
  50
  51     return res;
  52   }
  53
  54 The Free function is responsible for freeing the allocated memory for
  55 the structure.
  56
  57   static void
  58   _my_object_free (MyObject *obj)
  59   {
  60     /* other cleanup */
  61     ...
  62
  63     g_slice_free (MyObject, obj);
  64   }
  65
  66
  67 Lifecycle
  68 ~~~~~~~~~
  69
  70 GstMiniObject is refcounted. When a GstMiniObject is first created,
  71 it has a refcount of 1.
  72
  73 Each variable holding a reference to a GstMiniObject is responsible for
  74 updating the refcount. This includes incrementing the refcount with
  75 gst_mini_object_ref() when a reference is kept to a miniobject or
  76 gst_mini_object_unref() when a reference is released.
  77
  78 When the refcount reaches 0, and thus no objects hold a reference to the
  79 miniobject anymore, we can free the miniobject.
  80
  81 When freeing the miniobject, first the GstMiniObjectDisposeFunction is called.
  82 This function is allowed to revive the object again by incrementing the
  83 refcount, in which case it should return FALSE from the dispose function. The
  84 dispose function is used by GstBuffer to revive the buffer back into the
  85 GstBufferPool when needed.
  86
  87 When the dispose function returns TRUE, the GstMiniObjectFreeFunction will be
  88 called and the miniobject will be freed.
  89
  90
  91 Copy
  92 ~~~~
  93
  94 A miniobject can be copied with gst_mini_object_copy(). This function will
  95 call the custom copy function that was provided when registering the new
  96 GstMiniObject subclass.
  97
  98 The copy function should try to preserve as much info from the original object
  99 as possible.
 100
 101 The new copy should be writable.
 102
 103
 104 Access management
 105 ~~~~~~~~~~~~~~~~~
 106
 107 GstMiniObject can be shared between multiple threads. It is important that when
 108 a thread writes to a GstMiniObject that the other threads don't not see the
 109 changes.
 110
 111 To avoid exposing changes from one thread to another thread, the miniobjects
 112 are managed in a Copy-On-Write way. A copy is only made when it is known that
 113 the object is shared between multiple objects or threads.
 114
 115 There are 2 methods implemented for controlling access to the miniobject.
 116
 117  - A first method relies on the refcount of the object to control writability.
 118    Objects using this method have the LOCKABLE flag unset.
 119
 120  - A second method relies on a separate counter for controlling
 121    the access to the object. Objects using this method have the LOCKABLE flag
 122    set.
 123
 124  You can check if an object is writable with gst_mini_object_is_writable() and
 125  you can make any miniobject writable with gst_mini_object_make_writable().
 126  This will create a writable copy when the object was not writable.
 127
 128
 129  non-LOCKABLE GstMiniObjects
 130  ---------------------------
 131
 132  These GstMiniObjects have the LOCKABLE flag unset. They use the refcount value
 133  to control writability of the object.
 134
 135  When the refcount of the miniobject is > 1, the objects it referenced by at
 136  least 2 objects and is thus considered unwritable. A copy must be made before a
 137  modification to the object can be done.
 138
 139  Using the refcount to control writability is problematic for many language
 140  bindings that can keep additional references to the objects. This method is
 141  mainly for historical reasons until all users of the miniobjects are
 142  converted to use the LOCAKBLE flag.
 143
 144
 145  LOCKABLE GstMiniObjects
 146  -----------------------
 147
 148  These GstMiniObjects have the LOCKABLE flag set. They use a separate counter
 149  for controlling writability and access to the object.
 150
 151  It consists of 2 components:
 152
 153  * exclusive counter
 154
 155   Each object that wants to keep a reference to a GstMiniObject and doesn't want to
 156   see the changes from other owners of the same GstMiniObject needs to lock the
 157   GstMiniObject in EXCLUSIVE mode, which will increase the exclusive counter.
 158
 159   The exclusive counter counts the amount of objects that share this
 160   GstMiniObject. The counter is initially 0, meaning that the object is not shared with
 161   any object.
 162
 163   When a reference to a GstMiniObject release, both the ref count and the
 164   exclusive counter will be decreased with gst_mini_object_unref() and
 165   gst_mini_object_unlock () respectively.
 166
 167  * locking
 168
 169   All read and write access must be performed between a gst_mini_object_lock() and
 170   gst_mini_object_unlock() pair with the requested access method.
 171
 172   A gst_mini_object_lock() can fail when a WRITE lock is requested and the exclusive
 173   counter is > 1. Indeed a GstMiniObject object with an exclusive counter > 1 is
 174   locked EXCLUSIVELY by at least 2 objects and is therefore not writable.
 175
 176   Once the GstMiniObject is locked with a certain access mode, it can be recursively
 177   locked with the same or narrower access mode. For example, first locking the
 178   GstMiniObject in READWRITE mode allows you to recusively lock the
 179   GstMiniObject in
 180   READWRITE, READ and WRITE mode. Memory locked in READ mode cannot be locked
 181   recursively in WRITE or READWRITE mode.
 182
 183   Note that multiple threads can READ lock the GstMiniObject concurrently but cannot
 184   lock the object in WRITE mode because the exclusive counter must be > 1.
 185
 186   All calls to gst_mini_object_lock() need to be paired with one
 187   gst_mini_object_unlock() call with the same access mode. When the last refcount
 188   of the object is removed, there should be no more outstanding locks.
 189
 190  Note that a shared counter of both 0 and 1 leaves the GstMiniObject writable. The
 191  reason is to make it easy to create and pass ownership of the GstMiniObject to
 192  another object while keeping it writable. When the GstMiniObject is
 193  created with a shared count of 0, it is writable. When the GstMiniObject is then
 194  added to another object, the shared count is incremented to 1 and the
 195  GstMiniObject remains writable. The 0 share counter has a similar purpose as the floating
 196  reference in GObject.
 197
 198
 199 Weak references
 200 ~~~~~~~~~~~~~~~
 201
 202 GstMiniObject has support for weak references. A callback will be called when
 203 the object is freed for all registered weak references.
 204
 205
 206 QData
 207 ~~~~~
 208
 209 Extra data can be associated with a GstMiniObject by using the QData API.