From e6da27eb3bfa5ca13ad45c7cc0c74269eb3aa807 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Fri, 29 Aug 2008 17:58:25 +0000 Subject: [PATCH] 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. --- ChangeLog | 7 ++++++ gst/gstiterator.c | 60 ++++++++++++++++++++++++++++++++++++++--------- gst/gstiterator.h | 10 ++++---- 3 files changed, 61 insertions(+), 16 deletions(-) diff --git a/ChangeLog b/ChangeLog index 0c78d2dde4..48e2bc2979 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2008-08-29 Wim Taymans + + * 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 * gst/gstpad.c: (gst_pad_get_internal_links_default): diff --git a/gst/gstiterator.c b/gst/gstiterator.c index 32c09708ad..ee442a6ebc 100644 --- a/gst/gstiterator.c +++ b/gst/gstiterator.c @@ -61,7 +61,7 @@ * * * - * 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 @@ gst_iterator_init (GstIterator * it, * @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_list_iterator_free (GstListIterator * it) * 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 @@ gst_list_iterator_free (GstListIterator * it) * * 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 @@ gst_iterator_pop (GstIterator * it) * @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 @@ done: * 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 @@ gst_iterator_free (GstIterator * it) * @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 @@ gst_iterator_filter (GstIterator * it, GCompareFunc func, gpointer user_data) * @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 33f69fa305..6376be186c 100644 --- a/gst/gstiterator.h +++ b/gst/gstiterator.h @@ -51,7 +51,7 @@ typedef struct _GstIterator GstIterator; * @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 @@ typedef enum { * 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 @@ typedef void (*GstIteratorFreeFunction) (GstIterator *it); /** * 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 @@ typedef gboolean (*GstIteratorFoldFunction) (gpointer item, GValue *ret, gp * 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 {