* </programlisting>
* </example>
*
- * Last reviewed on 2005-11-09 (0.9.4)
+ * Last reviewed on 2008-08-29 (0.10.21)
*/
#include "gst_private.h"
* @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
* 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
*
* 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.
* @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.
+ *
+ * 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.
*
- * Returns: The result of the iteration. Unref after usage if this is
- * a refcounted object.
+ * 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.
*/
* 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
* @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
* @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.
*
* @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,
* 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);
/**
* 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().
* 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 {
projects / platform / upstream / gstreamer.git / commitdiff