FCL/sf/mw/gstreamer: comparison gstreamer

equal deleted inserted replaced

-:567bb019e3e3
+:7e817e7e631c
 * A GstIterator is used to retrieve multiple objects from another object in
 * a threadsafe way.
 *
 * Various GStreamer objects provide access to their internal structures using
 * an iterator.
-*
-* In general, whenever calling a GstIterator function results in your code
-* receiving a refcounted object, the refcount for that object will have been
-* increased.  Your code is responsible for unrefing that object after use.
 *
 * The basic use pattern of an iterator is as follows:
 *
 * <example>
 * <title>Using an iterator</title>
 *        case GST_ITERATOR_RESYNC:
 *          ...rollback changes to items...
 *          gst_iterator_resync (it);
 *          break;
 *        case GST_ITERATOR_ERROR:
-*          ...wrong parameters were given...
+*          ...wrong parameter were given...
 *          done = TRUE;
 *          break;
 *        case GST_ITERATOR_DONE:
 *          done = TRUE;
 *          break;
 *    }
 *    gst_iterator_free (it);
 *   </programlisting>
 * </example>
 *
-* Last reviewed on 2009-06-16 (0.10.24)
+* Last reviewed on 2005-11-09 (0.9.4)
 */
 #include "gst_private.h"
 #include <gst/gstiterator.h>
 /**
 * gst_iterator_new:
 * @size: the size of the iterator structure
 * @type: #GType of children
 * @lock: pointer to a #GMutex.
-* @master_cookie: pointer to a guint32 that is changed when the items in the
+* @master_cookie: pointer to a guint32 to protect the iterated object.
-*    iterator changed.
 * @next: function to get next item
 * @item: function to call on each item retrieved
 * @resync: function to resync the iterator
 * @free: function to free the iterator
 *
 {
 GstIterator iterator;
 gpointer owner;
 GList **orig;
 GList *list;                  /* pointer in list */
+GType *type;
 GstIteratorDisposeFunction freefunc;
 } GstListIterator;
 static GstIteratorResult
 gst_list_iterator_next (GstListIterator * it, gpointer * elem)
 /**
 * gst_iterator_new_list:
 * @type: #GType of elements
 * @lock: pointer to a #GMutex protecting the list.
-* @master_cookie: pointer to a guint32 that is incremented when the list
+* @master_cookie: pointer to a guint32 to protect the list.
-*     is changed.
 * @list: pointer to the list
 * @owner: object owning the list
 * @item: function to call for each item
 * @free: function to call when the iterator is freed
 *
 * 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/
-#ifdef __SYMBIAN32__
-EXPORT_C
-#endif
-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.
 */
 /**
 * gst_iterator_next:
 * @it: The #GstIterator to iterate
 * @elem: pointer to hold next element
 *
-* Get the next item from the iterator in @elem.
+* Get the next item from the iterator. For iterators that return
-*
+* refcounted objects, the returned object will have its refcount
-* Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid
+* increased and should therefore be unreffed after usage.
-* value. For iterators that return refcounted objects, the returned object
+*
-* will have its refcount increased and should therefore be unreffed after
+* Returns: The result of the iteration. Unref after usage if this is
-* usage.
+* 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.
 */
 #ifdef __SYMBIAN32__
 EXPORT_C
 * @it: The #GstIterator to resync
 *
 * 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.
 */
 #ifdef __SYMBIAN32__
 EXPORT_C
 #endif
 * gst_iterator_push:
 * @it: The #GstIterator to use
 * @other: The #GstIterator to push
 *
 * Pushes @other iterator onto @it. All calls performed on @it are
-* forwarded to @other. If @other returns %GST_ITERATOR_DONE, it is
+* forwarded tot @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.
 */
 #ifdef __SYMBIAN32__
 EXPORT_C
 * @it: The #GstIterator to fold over
 * @func: the fold function
 * @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, @func will be called
+* Folds @func over the elements of @iter. That is to say, @proc will be called
-* as @func (object, @ret, @user_data) for each object in @it. The normal use
+* as @proc (object, @ret, @user_data) for each object in @iter. The normal use
 * of this procedure is to accumulate the results of operating on the objects in
-* @ret.  If object is a refcounted object its refcount will be increased
+* @ret.
-* before @func is called, and it should be unrefed after use in @func.
+*
-*
+* This procedure can be used (and is used internally) to implement the foreach
-* This procedure can be used (and is used internally) to implement the
+* and find_custom operations.
-* gst_iterator_foreach() and gst_iterator_find_custom() operations.
 *
 * The fold will proceed as long as @func returns TRUE. When the iterator has no
-* more arguments, %GST_ITERATOR_DONE will be returned. If @func returns FALSE,
+* more arguments, #GST_ITERATOR_DONE will be returned. If @func returns FALSE,
-* the fold will stop, and %GST_ITERATOR_OK will be returned. Errors or resyncs
+* the fold will stop, and #GST_ITERATOR_OK will be returned. Errors or resyncs
-* will cause fold to return %GST_ITERATOR_ERROR or %GST_ITERATOR_RESYNC as
+* will cause fold to return #GST_ITERATOR_ERROR or #GST_ITERATOR_RESYNC as
 * appropriate.
 *
 * The iterator will not be freed.
 *
 * Returns: A #GstIteratorResult, as described above.
 * @it: The #GstIterator to iterate
 * @func: the function to call for each element.
 * @user_data: user data passed to the function
 *
 * Iterate over all element of @it and call the given function @func for
-* each element.  As in gst_iterator_fold(), the refcount of a refcounted
+* each element.
-* object will be increased before @func is called, and should be unrefed
-* after use.
 *
 * Returns: the result call to gst_iterator_fold(). The iterator will not be
 * freed.
 *
 * MT safe.
 * @it: The #GstIterator to iterate
 * @func: the compare function to use
 * @user_data: user data passed to the compare function
 *
 * Find the first element in @it that matches the compare function @func.
-* @func should return 0 when the element is found.  As in gst_iterator_fold(),
+* @func should return 0 when the element is found.
-* the refcount of a refcounted object will be increased before @func is
-* called, and should be unrefed after use.
 *
 * The iterator will not be freed.
 *
 * This function will return NULL if an error or resync happened to
 * the iterator.

branch	RCL_3
changeset 30	7e817e7e631c
parent 29	567bb019e3e3