gst/gstiterator.*: After 3 years it's about time to revise the documentation of the iterator objects.
Original commit message from CVS:
* gst/gstiterator.c:
* gst/gstiterator.h:
After 3 years it's about time to revise the documentation of the
iterator objects.
diff --git a/ChangeLog b/ChangeLog
index 0c78d2d..48e2bc2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
2008-08-29 Wim Taymans <wim.taymans@collabora.co.uk>
+ * gst/gstiterator.c:
+ * gst/gstiterator.h:
+ After 3 years it's about time to revise the documentation of the
+ iterator objects.
+
+2008-08-29 Wim Taymans <wim.taymans@collabora.co.uk>
+
* gst/gstpad.c: (gst_pad_get_internal_links_default):
Make the internal links function less thread-unsafe and add some
comments, dunno why.
diff --git a/gst/gstiterator.c b/gst/gstiterator.c
index 32c0970..ee442a6 100644
--- a/gst/gstiterator.c
+++ b/gst/gstiterator.c
@@ -61,7 +61,7 @@
* </programlisting>
* </example>
*
- * Last reviewed on 2005-11-09 (0.9.4)
+ * Last reviewed on 2008-08-29 (0.10.21)
*/
#include "gst_private.h"
@@ -92,7 +92,8 @@
* @size: the size of the iterator structure
* @type: #GType of children
* @lock: pointer to a #GMutex.
- * @master_cookie: pointer to a guint32 to protect the iterated object.
+ * @master_cookie: pointer to a guint32 that is changed when the items in the
+ * iterator changed.
* @next: function to get next item
* @item: function to call on each item retrieved
* @resync: function to resync the iterator
@@ -176,7 +177,8 @@
* gst_iterator_new_list:
* @type: #GType of elements
* @lock: pointer to a #GMutex protecting the list.
- * @master_cookie: pointer to a guint32 to protect the list.
+ * @master_cookie: pointer to a guint32 that is incremented when the list
+ * is changed.
* @list: pointer to the list
* @owner: object owning the list
* @item: function to call for each item
@@ -184,6 +186,24 @@
*
* Create a new iterator designed for iterating @list.
*
+ * The list you iterate is usually part of a data structure @owner and is
+ * protected with @lock.
+ *
+ * The iterator will use @lock to retrieve the next item of the list and it
+ * will then call the @item function before releasing @lock again.
+ *
+ * The @item function usualy makes sure that the item remains alive while
+ * @lock is released and the application is using the item. The application is
+ * responsible for freeing/unreffing the item after usage as explained in
+ * gst_iterator_next().
+ *
+ * When a concurrent update to the list is performed, usually by @owner while
+ * holding @lock, @master_cookie will be updated. The iterator implementation
+ * will notice the update of the cookie and will return #GST_ITERATOR_RESYNC to
+ * the user of the iterator in the next call to gst_iterator_next().
+ *
+ * @owner will be passed to the @free function when the iterator is freed.
+ *
* Returns: the new #GstIterator for @list.
*
* MT safe.
@@ -230,12 +250,24 @@
* @it: The #GstIterator to iterate
* @elem: pointer to hold next element
*
- * Get the next item from the iterator. For iterators that return
- * refcounted objects, the returned object will have its refcount
- * increased and should therefore be unreffed after usage.
+ * Get the next item from the iterator in @elem.
*
- * Returns: The result of the iteration. Unref after usage if this is
- * a refcounted object.
+ * Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid
+ * value. For iterators that return refcounted objects, the returned object
+ * will have its refcount increased and should therefore be unreffed after
+ * usage.
+ *
+ * When this function returns %GST_ITERATOR_DONE, no more elements can be
+ * retrieved from @it.
+ *
+ * A return value of %GST_ITERATOR_RESYNC indicates that the element list was
+ * concurrently updated. The user of @it should call gst_iterator_resync() to
+ * get the newly updated list.
+ *
+ * A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error.
+ *
+ * Returns: The result of the iteration. Unref @elem after usage if this
+ * is a refcounted object.
*
* MT safe.
*/
@@ -299,6 +331,9 @@
* Resync the iterator. this function is mostly called
* after gst_iterator_next() returned %GST_ITERATOR_RESYNC.
*
+ * When an iterator was pushed on @it, it will automatically be popped again
+ * with this function.
+ *
* MT safe.
*/
void
@@ -340,12 +375,15 @@
* @other: The #GstIterator to push
*
* Pushes @other iterator onto @it. All calls performed on @it are
- * forwarded tot @other. If @other returns #GST_ITERATOR_DONE, it is
+ * forwarded to @other. If @other returns #GST_ITERATOR_DONE, it is
* popped again and calls are handled by @it again.
*
* This function is mainly used by objects implementing the iterator
* next function to recurse into substructures.
*
+ * When gst_iterator_resync() is called on @it, @other will automatically be
+ * popped.
+ *
* MT safe.
*/
void
@@ -467,8 +505,8 @@
* @ret: the seed value passed to the fold function
* @user_data: user data passed to the fold function
*
- * Folds @func over the elements of @iter. That is to say, @proc will be called
- * as @proc (object, @ret, @user_data) for each object in @iter. The normal use
+ * Folds @func over the elements of @iter. That is to say, @func will be called
+ * as @func (object, @ret, @user_data) for each object in @it. The normal use
* of this procedure is to accumulate the results of operating on the objects in
* @ret.
*
diff --git a/gst/gstiterator.h b/gst/gstiterator.h
index 33f69fa..6376be1 100644
--- a/gst/gstiterator.h
+++ b/gst/gstiterator.h
@@ -51,7 +51,7 @@
* @GST_ITERATOR_ITEM_PASS: Return item
* @GST_ITERATOR_ITEM_END: Stop after this item.
*
- * The result of a GstIteratorItemFunction.
+ * The result of a #GstIteratorItemFunction.
*/
typedef enum {
GST_ITERATOR_ITEM_SKIP = 0,
@@ -63,8 +63,8 @@
* GstIteratorDisposeFunction:
* @owner: the owner of the iterator
*
- * The function that will be called when a GList iterator is freed. The
- * owner of the GList iterator can then clean up its resources.
+ * The function that will be called when a #GList iterator is freed. The
+ * owner of the #GList iterator can then clean up its resources.
*/
typedef void (*GstIteratorDisposeFunction) (gpointer owner);
@@ -128,7 +128,7 @@
/**
* GstIteratorFoldFunction:
* @item: the item to fold
- * @ret: a GValue collecting the result
+ * @ret: a #GValue collecting the result
* @user_data: data passed to gst_iterator_fold()
*
* A function to be passed to gst_iterator_fold().
@@ -186,7 +186,7 @@
* created.
* @master_cookie: A pointer to the master cookie.
*
- * GstIterator base structure. The values of this structure are
+ * #GstIterator base structure. The values of this structure are
* protected for subclasses, use the methods to use the #GstIterator.
*/
struct _GstIterator {
