2 * Copyright (C) 2004 Wim Taymans <wim@fluendo.com>
3 * Copyright (C) 2011 Sebastian Dröge <sebastian.droege@collabora.co.uk>
5 * gstiterator.h: Base class for iterating datastructures.
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
25 * @short_description: Object to retrieve multiple elements in a threadsafe
27 * @see_also: #GstElement, #GstBin
29 * A GstIterator is used to retrieve multiple objects from another object in
32 * Various GStreamer objects provide access to their internal structures using
35 * In general, whenever calling a GstIterator function results in your code
36 * receiving a refcounted object, the refcount for that object will have been
37 * increased. Your code is responsible for unrefing that object after use.
39 * The basic use pattern of an iterator is as follows:
42 * <title>Using an iterator</title>
44 * it = _get_iterator(object);
47 * switch (gst_iterator_next (it, &item)) {
48 * case GST_ITERATOR_OK:
49 * ... use/change item here...
50 * g_value_reset (&item);
52 * case GST_ITERATOR_RESYNC:
53 * ...rollback changes to items...
54 * gst_iterator_resync (it);
56 * case GST_ITERATOR_ERROR:
57 * ...wrong parameters were given...
60 * case GST_ITERATOR_DONE:
65 * g_value_unset (&item);
66 * gst_iterator_free (it);
70 * Last reviewed on 2009-06-16 (0.10.24)
73 #include "gst_private.h"
74 #include <gst/gstiterator.h>
77 gst_iterator_copy (const GstIterator * it)
81 copy = g_slice_copy (it->size, it);
88 G_DEFINE_BOXED_TYPE (GstIterator, gst_iterator,
89 (GBoxedCopyFunc) gst_iterator_copy, (GBoxedFreeFunc) gst_iterator_free);
92 gst_iterator_init (GstIterator * it,
96 guint32 * master_cookie,
97 GstIteratorCopyFunction copy,
98 GstIteratorNextFunction next,
99 GstIteratorItemFunction item,
100 GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
105 it->master_cookie = master_cookie;
106 it->cookie = *master_cookie;
116 * gst_iterator_new: (skip)
117 * @size: the size of the iterator structure
118 * @type: #GType of children
119 * @lock: pointer to a #GMutex.
120 * @master_cookie: pointer to a guint32 that is changed when the items in the
122 * @copy: copy function
123 * @next: function to get next item
124 * @item: function to call on each item retrieved
125 * @resync: function to resync the iterator
126 * @free: function to free the iterator
128 * Create a new iterator. This function is mainly used for objects
129 * implementing the next/resync/free function to iterate a data structure.
131 * For each item retrieved, the @item function is called with the lock
132 * held. The @free function is called when the iterator is freed.
134 * Returns: the new #GstIterator.
139 gst_iterator_new (guint size,
142 guint32 * master_cookie,
143 GstIteratorCopyFunction copy,
144 GstIteratorNextFunction next,
145 GstIteratorItemFunction item,
146 GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
150 g_return_val_if_fail (size >= sizeof (GstIterator), NULL);
151 g_return_val_if_fail (g_type_qname (type) != 0, NULL);
152 g_return_val_if_fail (master_cookie != NULL, NULL);
153 g_return_val_if_fail (next != NULL, NULL);
154 g_return_val_if_fail (resync != NULL, NULL);
155 g_return_val_if_fail (free != NULL, NULL);
157 result = g_slice_alloc0 (size);
158 gst_iterator_init (result, size, type, lock, master_cookie, copy, next, item,
167 typedef struct _GstListIterator
169 GstIterator iterator;
172 GList *list; /* pointer in list */
174 void (*set_value) (GValue * value, gpointer item);
178 gst_list_iterator_copy (const GstListIterator * it, GstListIterator * copy)
181 g_object_ref (copy->owner);
184 static GstIteratorResult
185 gst_list_iterator_next (GstListIterator * it, GValue * elem)
189 if (it->list == NULL)
190 return GST_ITERATOR_DONE;
192 data = it->list->data;
193 it->list = g_list_next (it->list);
195 it->set_value (elem, data);
197 return GST_ITERATOR_OK;
201 gst_list_iterator_resync (GstListIterator * it)
203 it->list = *it->orig;
207 gst_list_iterator_free (GstListIterator * it)
210 g_object_unref (it->owner);
214 * gst_iterator_new_list: (skip)
215 * @type: #GType of elements
216 * @lock: pointer to a #GMutex protecting the list.
217 * @master_cookie: pointer to a guint32 that is incremented when the list
219 * @list: pointer to the list
220 * @owner: object owning the list
221 * @item: function to call on each item retrieved
223 * Create a new iterator designed for iterating @list.
225 * The list you iterate is usually part of a data structure @owner and is
226 * protected with @lock.
228 * The iterator will use @lock to retrieve the next item of the list and it
229 * will then call the @item function before releasing @lock again.
231 * When a concurrent update to the list is performed, usually by @owner while
232 * holding @lock, @master_cookie will be updated. The iterator implementation
233 * will notice the update of the cookie and will return %GST_ITERATOR_RESYNC to
234 * the user of the iterator in the next call to gst_iterator_next().
236 * Returns: the new #GstIterator for @list.
241 gst_iterator_new_list (GType type,
242 GMutex * lock, guint32 * master_cookie, GList ** list, GObject * owner,
243 GstIteratorItemFunction item)
245 GstListIterator *result;
248 if (g_type_is_a (type, G_TYPE_OBJECT)) {
249 set_value = g_value_set_object;
250 } else if (g_type_is_a (type, G_TYPE_BOXED)) {
251 set_value = g_value_set_boxed;
252 } else if (g_type_is_a (type, G_TYPE_POINTER)) {
253 set_value = g_value_set_pointer;
254 } else if (g_type_is_a (type, G_TYPE_STRING)) {
255 set_value = g_value_set_string;
257 g_critical ("List iterators can only be created for lists containing "
258 "instances of GObject, boxed types, pointer types and strings");
262 /* no need to lock, nothing can change here */
263 result = (GstListIterator *) gst_iterator_new (sizeof (GstListIterator),
267 (GstIteratorCopyFunction) gst_list_iterator_copy,
268 (GstIteratorNextFunction) gst_list_iterator_next,
269 (GstIteratorItemFunction) item,
270 (GstIteratorResyncFunction) gst_list_iterator_resync,
271 (GstIteratorFreeFunction) gst_list_iterator_free);
273 result->owner = owner ? g_object_ref (owner) : NULL;
275 result->list = *list;
276 result->set_value = set_value;
278 return GST_ITERATOR (result);
282 gst_iterator_pop (GstIterator * it)
285 gst_iterator_free (it->pushed);
292 * @it: The #GstIterator to iterate
293 * @elem: (out caller-allocates): pointer to hold next element
295 * Get the next item from the iterator in @elem.
297 * Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid
298 * value. @elem must have been initialized to the type of the iterator or
299 * initialized to zeroes with g_value_unset(). The caller is responsible for
300 * unsetting or resetting @elem with g_value_unset() or g_value_reset()
303 * When this function returns %GST_ITERATOR_DONE, no more elements can be
304 * retrieved from @it.
306 * A return value of %GST_ITERATOR_RESYNC indicates that the element list was
307 * concurrently updated. The user of @it should call gst_iterator_resync() to
308 * get the newly updated list.
310 * A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error.
312 * Returns: The result of the iteration. Unset @elem after usage.
317 gst_iterator_next (GstIterator * it, GValue * elem)
319 GstIteratorResult result;
321 g_return_val_if_fail (it != NULL, GST_ITERATOR_ERROR);
322 g_return_val_if_fail (elem != NULL, GST_ITERATOR_ERROR);
323 g_return_val_if_fail (G_VALUE_TYPE (elem) == G_TYPE_INVALID
324 || G_VALUE_HOLDS (elem, it->type), GST_ITERATOR_ERROR);
326 if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
327 g_value_init (elem, it->type);
331 result = gst_iterator_next (it->pushed, elem);
332 if (result == GST_ITERATOR_DONE) {
333 /* we are done with this iterator, pop it and
334 * fallthrough iterating the main iterator again. */
335 gst_iterator_pop (it);
341 if (G_LIKELY (it->lock))
342 g_mutex_lock (it->lock);
344 if (G_UNLIKELY (*it->master_cookie != it->cookie)) {
345 result = GST_ITERATOR_RESYNC;
349 result = it->next (it, elem);
350 if (result == GST_ITERATOR_OK && it->item) {
351 GstIteratorItem itemres;
353 itemres = it->item (it, elem);
355 case GST_ITERATOR_ITEM_SKIP:
356 if (G_LIKELY (it->lock))
357 g_mutex_unlock (it->lock);
358 g_value_reset (elem);
360 case GST_ITERATOR_ITEM_END:
361 result = GST_ITERATOR_DONE;
362 g_value_reset (elem);
364 case GST_ITERATOR_ITEM_PASS:
370 if (G_LIKELY (it->lock))
371 g_mutex_unlock (it->lock);
377 * gst_iterator_resync:
378 * @it: The #GstIterator to resync
380 * Resync the iterator. this function is mostly called
381 * after gst_iterator_next() returned %GST_ITERATOR_RESYNC.
383 * When an iterator was pushed on @it, it will automatically be popped again
384 * with this function.
389 gst_iterator_resync (GstIterator * it)
391 g_return_if_fail (it != NULL);
393 gst_iterator_pop (it);
395 if (G_LIKELY (it->lock))
396 g_mutex_lock (it->lock);
398 it->cookie = *it->master_cookie;
399 if (G_LIKELY (it->lock))
400 g_mutex_unlock (it->lock);
405 * @it: The #GstIterator to free
412 gst_iterator_free (GstIterator * it)
414 g_return_if_fail (it != NULL);
416 gst_iterator_pop (it);
420 g_slice_free1 (it->size, it);
425 * @it: The #GstIterator to use
426 * @other: The #GstIterator to push
428 * Pushes @other iterator onto @it. All calls performed on @it are
429 * forwarded to @other. If @other returns %GST_ITERATOR_DONE, it is
430 * popped again and calls are handled by @it again.
432 * This function is mainly used by objects implementing the iterator
433 * next function to recurse into substructures.
435 * When gst_iterator_resync() is called on @it, @other will automatically be
441 gst_iterator_push (GstIterator * it, GstIterator * other)
443 g_return_if_fail (it != NULL);
444 g_return_if_fail (other != NULL);
449 typedef struct _GstIteratorFilter
451 GstIterator iterator;
456 gboolean have_user_data;
459 static GstIteratorResult
460 filter_next (GstIteratorFilter * it, GValue * elem)
462 GstIteratorResult result = GST_ITERATOR_ERROR;
463 gboolean done = FALSE;
464 GValue item = { 0, };
466 while (G_LIKELY (!done)) {
467 result = gst_iterator_next (it->slave, &item);
469 case GST_ITERATOR_OK:
470 if (G_LIKELY (GST_ITERATOR (it)->lock))
471 g_mutex_unlock (GST_ITERATOR (it)->lock);
472 if (it->func (&item, &it->user_data) == 0) {
473 g_value_copy (&item, elem);
476 g_value_reset (&item);
477 if (G_LIKELY (GST_ITERATOR (it)->lock))
478 g_mutex_lock (GST_ITERATOR (it)->lock);
480 case GST_ITERATOR_RESYNC:
481 case GST_ITERATOR_DONE:
485 g_assert_not_reached ();
489 g_value_unset (&item);
494 filter_copy (const GstIteratorFilter * it, GstIteratorFilter * copy)
496 copy->slave = gst_iterator_copy (it->slave);
498 if (it->have_user_data) {
499 memset (©->user_data, 0, sizeof (copy->user_data));
500 g_value_init (©->user_data, G_VALUE_TYPE (&it->user_data));
501 g_value_copy (&it->user_data, ©->user_data);
506 filter_resync (GstIteratorFilter * it)
508 gst_iterator_resync (it->slave);
512 filter_free (GstIteratorFilter * it)
514 if (it->have_user_data)
515 g_value_unset (&it->user_data);
516 gst_iterator_free (it->slave);
520 * gst_iterator_filter:
521 * @it: The #GstIterator to filter
522 * @func: (scope call): the compare function to select elements
523 * @user_data: (closure): user data passed to the compare function
525 * Create a new iterator from an existing iterator. The new iterator
526 * will only return those elements that match the given compare function @func.
527 * The first parameter that is passed to @func is the #GValue of the current
528 * iterator element and the second parameter is @user_data. @func should
529 * return 0 for elements that should be included in the filtered iterator.
531 * When this iterator is freed, @it will also be freed.
533 * Returns: (transfer full): a new #GstIterator.
538 gst_iterator_filter (GstIterator * it, GCompareFunc func,
539 const GValue * user_data)
541 GstIteratorFilter *result;
543 g_return_val_if_fail (it != NULL, NULL);
544 g_return_val_if_fail (func != NULL, NULL);
546 result = (GstIteratorFilter *) gst_iterator_new (sizeof (GstIteratorFilter),
547 it->type, it->lock, it->master_cookie,
548 (GstIteratorCopyFunction) filter_copy,
549 (GstIteratorNextFunction) filter_next,
550 (GstIteratorItemFunction) NULL,
551 (GstIteratorResyncFunction) filter_resync,
552 (GstIteratorFreeFunction) filter_free);
557 g_value_init (&result->user_data, G_VALUE_TYPE (user_data));
558 g_value_copy (user_data, &result->user_data);
559 result->have_user_data = TRUE;
561 result->have_user_data = FALSE;
565 return GST_ITERATOR (result);
570 * @it: The #GstIterator to fold over
571 * @func: (scope call): the fold function
572 * @ret: the seed value passed to the fold function
573 * @user_data: (closure): user data passed to the fold function
575 * Folds @func over the elements of @iter. That is to say, @func will be called
576 * as @func (object, @ret, @user_data) for each object in @it. The normal use
577 * of this procedure is to accumulate the results of operating on the objects in
580 * This procedure can be used (and is used internally) to implement the
581 * gst_iterator_foreach() and gst_iterator_find_custom() operations.
583 * The fold will proceed as long as @func returns TRUE. When the iterator has no
584 * more arguments, %GST_ITERATOR_DONE will be returned. If @func returns FALSE,
585 * the fold will stop, and %GST_ITERATOR_OK will be returned. Errors or resyncs
586 * will cause fold to return %GST_ITERATOR_ERROR or %GST_ITERATOR_RESYNC as
589 * The iterator will not be freed.
591 * Returns: A #GstIteratorResult, as described above.
596 gst_iterator_fold (GstIterator * it, GstIteratorFoldFunction func,
597 GValue * ret, gpointer user_data)
599 GValue item = { 0, };
600 GstIteratorResult result;
603 result = gst_iterator_next (it, &item);
605 case GST_ITERATOR_OK:
606 if (!func (&item, ret, user_data))
609 g_value_reset (&item);
611 case GST_ITERATOR_RESYNC:
612 case GST_ITERATOR_ERROR:
614 case GST_ITERATOR_DONE:
620 g_value_unset (&item);
627 GstIteratorForeachFunction func;
632 foreach_fold_func (const GValue * item, GValue * unused, ForeachFoldData * data)
634 data->func (item, data->user_data);
639 * gst_iterator_foreach:
640 * @it: The #GstIterator to iterate
641 * @func: (scope call): the function to call for each element.
642 * @user_data: (closure): user data passed to the function
644 * Iterate over all element of @it and call the given function @func for
647 * Returns: the result call to gst_iterator_fold(). The iterator will not be
653 gst_iterator_foreach (GstIterator * it, GstIteratorForeachFunction func,
656 ForeachFoldData data;
659 data.user_data = user_data;
661 return gst_iterator_fold (it, (GstIteratorFoldFunction) foreach_fold_func,
670 } FindCustomFoldData;
673 find_custom_fold_func (const GValue * item, GValue * ret,
674 FindCustomFoldData * data)
676 if (data->func (item, data->user_data) == 0) {
678 g_value_copy (item, ret);
686 * gst_iterator_find_custom:
687 * @it: The #GstIterator to iterate
688 * @func: (scope call): the compare function to use
689 * @elem: (out): pointer to a #GValue where to store the result
690 * @user_data: (closure): user data passed to the compare function
692 * Find the first element in @it that matches the compare function @func.
693 * @func should return 0 when the element is found. The first parameter
694 * to @func will be the current element of the iterator and the
695 * second parameter will be @user_data.
696 * The result will be stored in @elem if a result is found.
698 * The iterator will not be freed.
700 * This function will return FALSE if an error happened to the iterator
701 * or if the element wasn't found.
703 * Returns: Returns TRUE if the element was found, else FALSE.
708 gst_iterator_find_custom (GstIterator * it, GCompareFunc func,
709 GValue * elem, gpointer user_data)
711 GstIteratorResult res;
712 FindCustomFoldData data;
714 g_return_val_if_fail (G_VALUE_TYPE (elem) == G_TYPE_INVALID
715 || G_VALUE_HOLDS (elem, it->type), GST_ITERATOR_ERROR);
717 if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
718 g_value_init (elem, it->type);
721 data.user_data = user_data;
726 gst_iterator_fold (it, (GstIteratorFoldFunction) find_custom_fold_func,
728 if (res == GST_ITERATOR_RESYNC)
729 gst_iterator_resync (it);
730 } while (res == GST_ITERATOR_RESYNC);
733 g_value_unset (elem);
744 } GstSingleObjectIterator;
746 static guint32 _single_object_dummy_cookie = 0;
749 gst_single_object_iterator_copy (const GstSingleObjectIterator * it,
750 GstSingleObjectIterator * copy)
753 memset (©->object, 0, sizeof (copy->object));
754 g_value_init (©->object, it->parent.type);
755 g_value_copy (&it->object, ©->object);
759 static GstIteratorResult
760 gst_single_object_iterator_next (GstSingleObjectIterator * it, GValue * result)
762 if (it->visited || it->empty)
763 return GST_ITERATOR_DONE;
765 g_value_copy (&it->object, result);
768 return GST_ITERATOR_OK;
772 gst_single_object_iterator_resync (GstSingleObjectIterator * it)
778 gst_single_object_iterator_free (GstSingleObjectIterator * it)
781 g_value_unset (&it->object);
785 * gst_iterator_new_single:
786 * @type: #GType of the passed object
787 * @object: object that this iterator should return
789 * This #GstIterator is a convenient iterator for the common
790 * case where a #GstIterator needs to be returned but only
791 * a single object has to be considered. This happens often
792 * for the #GstPadIterIntLinkFunction.
794 * Returns: the new #GstIterator for @object.
799 gst_iterator_new_single (GType type, const GValue * object)
801 GstSingleObjectIterator *result;
803 result = (GstSingleObjectIterator *)
804 gst_iterator_new (sizeof (GstSingleObjectIterator),
805 type, NULL, &_single_object_dummy_cookie,
806 (GstIteratorCopyFunction) gst_single_object_iterator_copy,
807 (GstIteratorNextFunction) gst_single_object_iterator_next,
808 (GstIteratorItemFunction) NULL,
809 (GstIteratorResyncFunction) gst_single_object_iterator_resync,
810 (GstIteratorFreeFunction) gst_single_object_iterator_free);
813 g_value_init (&result->object, type);
814 g_value_copy (object, &result->object);
815 result->empty = FALSE;
817 result->empty = TRUE;
819 result->visited = FALSE;
821 return GST_ITERATOR (result);