docs/design/part-standards.txt

   1 Ownership of dynamic objects
   2 ----------------------------
   3
   4 Any object-oriented system or language that doesn't have automatic garbage
   5 collection has many potential pitfalls as far as the pointers go. Therefore,
   6 some standards must be adhered to as far as who owns what.
   7
   8 Strings
   9 ~~~~~~~
  10
  11 Arguments passed into a function are owned by the caller, and the function
  12 will make a copy of the string for its own internal use.  The string should
  13 be const gchar *.  Strings returned from a function are always a copy of the
  14 original and should be freed after usage by the caller.
  15
  16   ex:
  17
  18      name = gst_element_get_name (element);   /* copy of name is made */
  19      .. use name ..
  20      g_free (name);                           /* free after usage */
  21
  22
  23 Objects
  24 ~~~~~~~
  25
  26 Objects passed into a function are owned by the caller, any additional
  27 reference held to the object after leaving the function should increase the
  28 refcount of that object.
  29
  30 Objects returned from a function are owned by the caller. This means that the
  31 called should _free() or _unref() the object after usage.
  32
  33   ex:
  34
  35      peer = gst_pad_get_peer (pad);          /* peer with increased refcount */
  36      if (peer) {
  37        .. use peer ..
  38        gst_object_unref (GST_OBJECT (peer)); /* unref peer after usage */
  39      }
  40
  41
  42 Iterators
  43 ~~~~~~~~~
  44
  45 When retrieving multiple objects from an object an iterator should be used.
  46 The iterator allows you to access the objects one after another while making
  47 sure that the set of objects retrieved remains consistent.
  48
  49 Each object retrieved from an iterator has its refcount increased or is a
  50 copy of the original. In any case the object should be unreffed or freed
  51 after usage.
  52
  53
  54