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., 51 Franklin St, Fifth Floor,
20 * Boston, MA 02110-1301, 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 unreffing that object after use.
39 * The basic use pattern of an iterator is as follows:
41 * GstIterator *it = _get_iterator(object);
44 * switch (gst_iterator_next (it, &item)) {
45 * case GST_ITERATOR_OK:
46 * ... use/change item here...
47 * g_value_reset (&item);
49 * case GST_ITERATOR_RESYNC:
50 * ...rollback changes to items...
51 * gst_iterator_resync (it);
53 * case GST_ITERATOR_ERROR:
54 * ...wrong parameters were given...
57 * case GST_ITERATOR_DONE:
62 * g_value_unset (&item);
63 * gst_iterator_free (it);
67 #include "gst_private.h"
68 #include <gst/gstiterator.h>
74 * Copy the iterator and its state.
76 * Returns: a new copy of @it.
79 gst_iterator_copy (const GstIterator * it)
83 copy = g_slice_copy (it->size, it);
90 G_DEFINE_BOXED_TYPE (GstIterator, gst_iterator,
91 (GBoxedCopyFunc) gst_iterator_copy, (GBoxedFreeFunc) gst_iterator_free);
94 gst_iterator_init (GstIterator * it,
98 guint32 * master_cookie,
99 GstIteratorCopyFunction copy,
100 GstIteratorNextFunction next,
101 GstIteratorItemFunction item,
102 GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
107 it->master_cookie = master_cookie;
108 it->cookie = *master_cookie;
118 * gst_iterator_new: (skip)
119 * @size: the size of the iterator structure
120 * @type: #GType of children
121 * @lock: pointer to a #GMutex.
122 * @master_cookie: pointer to a guint32 that is changed when the items in the
124 * @copy: copy function
125 * @next: function to get next item
126 * @item: function to call on each item retrieved
127 * @resync: function to resync the iterator
128 * @free: function to free the iterator
130 * Create a new iterator. This function is mainly used for objects
131 * implementing the next/resync/free function to iterate a data structure.
133 * For each item retrieved, the @item function is called with the lock
134 * held. The @free function is called when the iterator is freed.
136 * Returns: the new #GstIterator.
141 gst_iterator_new (guint size,
144 guint32 * master_cookie,
145 GstIteratorCopyFunction copy,
146 GstIteratorNextFunction next,
147 GstIteratorItemFunction item,
148 GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
152 g_return_val_if_fail (size >= sizeof (GstIterator), NULL);
153 g_return_val_if_fail (g_type_qname (type) != 0, NULL);
154 g_return_val_if_fail (master_cookie != NULL, NULL);
155 g_return_val_if_fail (next != NULL, NULL);
156 g_return_val_if_fail (resync != NULL, NULL);
157 g_return_val_if_fail (free != NULL, NULL);
159 result = g_slice_alloc0 (size);
160 gst_iterator_init (result, size, type, lock, master_cookie, copy, next, item,
169 typedef struct _GstListIterator
171 GstIterator iterator;
174 GList *list; /* pointer in list */
176 void (*set_value) (GValue * value, gpointer item);
180 gst_list_iterator_copy (const GstListIterator * it, GstListIterator * copy)
183 g_object_ref (copy->owner);
186 static GstIteratorResult
187 gst_list_iterator_next (GstListIterator * it, GValue * elem)
191 if (it->list == NULL)
192 return GST_ITERATOR_DONE;
194 data = it->list->data;
195 it->list = g_list_next (it->list);
197 it->set_value (elem, data);
199 return GST_ITERATOR_OK;
203 gst_list_iterator_resync (GstListIterator * it)
205 it->list = *it->orig;
209 gst_list_iterator_free (GstListIterator * it)
212 g_object_unref (it->owner);
216 * gst_iterator_new_list: (skip)
217 * @type: #GType of elements
218 * @lock: pointer to a #GMutex protecting the list.
219 * @master_cookie: pointer to a guint32 that is incremented when the list
221 * @list: pointer to the list
222 * @owner: object owning the list
223 * @item: function to call on each item retrieved
225 * Create a new iterator designed for iterating @list.
227 * The list you iterate is usually part of a data structure @owner and is
228 * protected with @lock.
230 * The iterator will use @lock to retrieve the next item of the list and it
231 * will then call the @item function before releasing @lock again.
233 * When a concurrent update to the list is performed, usually by @owner while
234 * holding @lock, @master_cookie will be updated. The iterator implementation
235 * will notice the update of the cookie and will return %GST_ITERATOR_RESYNC to
236 * the user of the iterator in the next call to gst_iterator_next().
238 * Returns: the new #GstIterator for @list.
243 gst_iterator_new_list (GType type,
244 GMutex * lock, guint32 * master_cookie, GList ** list, GObject * owner,
245 GstIteratorItemFunction item)
247 GstListIterator *result;
250 if (g_type_is_a (type, G_TYPE_OBJECT)) {
251 set_value = g_value_set_object;
252 } else if (g_type_is_a (type, G_TYPE_BOXED)) {
253 set_value = g_value_set_boxed;
254 } else if (g_type_is_a (type, G_TYPE_POINTER)) {
255 set_value = g_value_set_pointer;
256 } else if (g_type_is_a (type, G_TYPE_STRING)) {
257 set_value = g_value_set_string;
259 g_critical ("List iterators can only be created for lists containing "
260 "instances of GObject, boxed types, pointer types and strings");
264 /* no need to lock, nothing can change here */
265 result = (GstListIterator *) gst_iterator_new (sizeof (GstListIterator),
269 (GstIteratorCopyFunction) gst_list_iterator_copy,
270 (GstIteratorNextFunction) gst_list_iterator_next,
271 (GstIteratorItemFunction) item,
272 (GstIteratorResyncFunction) gst_list_iterator_resync,
273 (GstIteratorFreeFunction) gst_list_iterator_free);
275 result->owner = owner ? g_object_ref (owner) : NULL;
277 result->list = *list;
278 result->set_value = set_value;
280 return GST_ITERATOR (result);
284 gst_iterator_pop (GstIterator * it)
287 gst_iterator_free (it->pushed);
294 * @it: The #GstIterator to iterate
295 * @elem: (out caller-allocates): pointer to hold next element
297 * Get the next item from the iterator in @elem.
299 * Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid
300 * value. @elem must have been initialized to the type of the iterator or
301 * initialized to zeroes with g_value_unset(). The caller is responsible for
302 * unsetting or resetting @elem with g_value_unset() or g_value_reset()
305 * When this function returns %GST_ITERATOR_DONE, no more elements can be
306 * retrieved from @it.
308 * A return value of %GST_ITERATOR_RESYNC indicates that the element list was
309 * concurrently updated. The user of @it should call gst_iterator_resync() to
310 * get the newly updated list.
312 * A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error.
314 * Returns: The result of the iteration. Unset @elem after usage.
319 gst_iterator_next (GstIterator * it, GValue * elem)
321 GstIteratorResult result;
323 g_return_val_if_fail (it != NULL, GST_ITERATOR_ERROR);
324 g_return_val_if_fail (elem != NULL, GST_ITERATOR_ERROR);
325 g_return_val_if_fail (G_VALUE_TYPE (elem) == G_TYPE_INVALID
326 || G_VALUE_HOLDS (elem, it->type), GST_ITERATOR_ERROR);
328 if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
329 g_value_init (elem, it->type);
333 result = gst_iterator_next (it->pushed, elem);
334 if (result == GST_ITERATOR_DONE) {
335 /* we are done with this iterator, pop it and
336 * fallthrough iterating the main iterator again. */
337 gst_iterator_pop (it);
343 if (G_LIKELY (it->lock))
344 g_mutex_lock (it->lock);
346 if (G_UNLIKELY (*it->master_cookie != it->cookie)) {
347 result = GST_ITERATOR_RESYNC;
351 result = it->next (it, elem);
352 if (result == GST_ITERATOR_OK && it->item) {
353 GstIteratorItem itemres;
355 itemres = it->item (it, elem);
357 case GST_ITERATOR_ITEM_SKIP:
358 if (G_LIKELY (it->lock))
359 g_mutex_unlock (it->lock);
360 g_value_reset (elem);
362 case GST_ITERATOR_ITEM_END:
363 result = GST_ITERATOR_DONE;
364 g_value_reset (elem);
366 case GST_ITERATOR_ITEM_PASS:
372 if (G_LIKELY (it->lock))
373 g_mutex_unlock (it->lock);
379 * gst_iterator_resync:
380 * @it: The #GstIterator to resync
382 * Resync the iterator. this function is mostly called
383 * after gst_iterator_next() returned %GST_ITERATOR_RESYNC.
385 * When an iterator was pushed on @it, it will automatically be popped again
386 * with this function.
391 gst_iterator_resync (GstIterator * it)
393 g_return_if_fail (it != NULL);
395 gst_iterator_pop (it);
397 if (G_LIKELY (it->lock))
398 g_mutex_lock (it->lock);
400 it->cookie = *it->master_cookie;
401 if (G_LIKELY (it->lock))
402 g_mutex_unlock (it->lock);
407 * @it: The #GstIterator to free
414 gst_iterator_free (GstIterator * it)
416 g_return_if_fail (it != NULL);
418 gst_iterator_pop (it);
422 g_slice_free1 (it->size, it);
427 * @it: The #GstIterator to use
428 * @other: The #GstIterator to push
430 * Pushes @other iterator onto @it. All calls performed on @it are
431 * forwarded to @other. If @other returns %GST_ITERATOR_DONE, it is
432 * popped again and calls are handled by @it again.
434 * This function is mainly used by objects implementing the iterator
435 * next function to recurse into substructures.
437 * When gst_iterator_resync() is called on @it, @other will automatically be
443 gst_iterator_push (GstIterator * it, GstIterator * other)
445 g_return_if_fail (it != NULL);
446 g_return_if_fail (other != NULL);
451 typedef struct _GstIteratorFilter
453 GstIterator iterator;
459 gboolean have_user_data;
462 static GstIteratorResult
463 filter_next (GstIteratorFilter * it, GValue * elem)
465 GstIteratorResult result = GST_ITERATOR_ERROR;
466 gboolean done = FALSE;
467 GValue item = { 0, };
469 while (G_LIKELY (!done)) {
470 result = gst_iterator_next (it->slave, &item);
472 case GST_ITERATOR_OK:
473 if (G_LIKELY (it->master_lock))
474 g_mutex_unlock (it->master_lock);
475 if (it->func (&item, &it->user_data) == 0) {
476 g_value_copy (&item, elem);
479 g_value_reset (&item);
480 if (G_LIKELY (it->master_lock))
481 g_mutex_lock (it->master_lock);
483 case GST_ITERATOR_RESYNC:
484 case GST_ITERATOR_DONE:
488 g_assert_not_reached ();
492 g_value_unset (&item);
497 filter_copy (const GstIteratorFilter * it, GstIteratorFilter * copy)
499 copy->slave = gst_iterator_copy (it->slave);
500 copy->master_lock = copy->slave->lock ? copy->slave->lock : it->master_lock;
501 copy->slave->lock = NULL;
503 if (it->have_user_data) {
504 memset (©->user_data, 0, sizeof (copy->user_data));
505 g_value_init (©->user_data, G_VALUE_TYPE (&it->user_data));
506 g_value_copy (&it->user_data, ©->user_data);
511 filter_resync (GstIteratorFilter * it)
513 gst_iterator_resync (it->slave);
517 filter_free (GstIteratorFilter * it)
519 if (it->have_user_data)
520 g_value_unset (&it->user_data);
521 gst_iterator_free (it->slave);
525 * gst_iterator_filter:
526 * @it: The #GstIterator to filter
527 * @func: (scope call): the compare function to select elements
528 * @user_data: (closure): user data passed to the compare function
530 * Create a new iterator from an existing iterator. The new iterator
531 * will only return those elements that match the given compare function @func.
532 * The first parameter that is passed to @func is the #GValue of the current
533 * iterator element and the second parameter is @user_data. @func should
534 * return 0 for elements that should be included in the filtered iterator.
536 * When this iterator is freed, @it will also be freed.
538 * Returns: (transfer full): a new #GstIterator.
543 gst_iterator_filter (GstIterator * it, GCompareFunc func,
544 const GValue * user_data)
546 GstIteratorFilter *result;
548 g_return_val_if_fail (it != NULL, NULL);
549 g_return_val_if_fail (func != NULL, NULL);
551 result = (GstIteratorFilter *) gst_iterator_new (sizeof (GstIteratorFilter),
552 it->type, it->lock, it->master_cookie,
553 (GstIteratorCopyFunction) filter_copy,
554 (GstIteratorNextFunction) filter_next,
555 (GstIteratorItemFunction) NULL,
556 (GstIteratorResyncFunction) filter_resync,
557 (GstIteratorFreeFunction) filter_free);
559 result->master_lock = it->lock;
563 g_value_init (&result->user_data, G_VALUE_TYPE (user_data));
564 g_value_copy (user_data, &result->user_data);
565 result->have_user_data = TRUE;
567 result->have_user_data = FALSE;
571 return GST_ITERATOR (result);
576 * @it: The #GstIterator to fold over
577 * @func: (scope call): the fold function
578 * @ret: the seed value passed to the fold function
579 * @user_data: (closure): user data passed to the fold function
581 * Folds @func over the elements of @iter. That is to say, @func will be called
582 * as @func (object, @ret, @user_data) for each object in @it. The normal use
583 * of this procedure is to accumulate the results of operating on the objects in
586 * This procedure can be used (and is used internally) to implement the
587 * gst_iterator_foreach() and gst_iterator_find_custom() operations.
589 * The fold will proceed as long as @func returns TRUE. When the iterator has no
590 * more arguments, %GST_ITERATOR_DONE will be returned. If @func returns FALSE,
591 * the fold will stop, and %GST_ITERATOR_OK will be returned. Errors or resyncs
592 * will cause fold to return %GST_ITERATOR_ERROR or %GST_ITERATOR_RESYNC as
595 * The iterator will not be freed.
597 * Returns: A #GstIteratorResult, as described above.
602 gst_iterator_fold (GstIterator * it, GstIteratorFoldFunction func,
603 GValue * ret, gpointer user_data)
605 GValue item = { 0, };
606 GstIteratorResult result;
609 result = gst_iterator_next (it, &item);
611 case GST_ITERATOR_OK:
612 if (!func (&item, ret, user_data))
615 g_value_reset (&item);
617 case GST_ITERATOR_RESYNC:
618 case GST_ITERATOR_ERROR:
620 case GST_ITERATOR_DONE:
626 g_value_unset (&item);
633 GstIteratorForeachFunction func;
638 foreach_fold_func (const GValue * item, GValue * unused, ForeachFoldData * data)
640 data->func (item, data->user_data);
645 * gst_iterator_foreach:
646 * @it: The #GstIterator to iterate
647 * @func: (scope call): the function to call for each element.
648 * @user_data: (closure): user data passed to the function
650 * Iterate over all element of @it and call the given function @func for
653 * Returns: the result call to gst_iterator_fold(). The iterator will not be
659 gst_iterator_foreach (GstIterator * it, GstIteratorForeachFunction func,
662 ForeachFoldData data;
665 data.user_data = user_data;
667 return gst_iterator_fold (it, (GstIteratorFoldFunction) foreach_fold_func,
676 } FindCustomFoldData;
679 find_custom_fold_func (const GValue * item, GValue * ret,
680 FindCustomFoldData * data)
682 if (data->func (item, data->user_data) == 0) {
684 g_value_copy (item, ret);
692 * gst_iterator_find_custom:
693 * @it: The #GstIterator to iterate
694 * @func: (scope call): the compare function to use
695 * @elem: (out): pointer to a #GValue where to store the result
696 * @user_data: (closure): user data passed to the compare function
698 * Find the first element in @it that matches the compare function @func.
699 * @func should return 0 when the element is found. The first parameter
700 * to @func will be the current element of the iterator and the
701 * second parameter will be @user_data.
702 * The result will be stored in @elem if a result is found.
704 * The iterator will not be freed.
706 * This function will return FALSE if an error happened to the iterator
707 * or if the element wasn't found.
709 * Returns: Returns TRUE if the element was found, else FALSE.
714 gst_iterator_find_custom (GstIterator * it, GCompareFunc func,
715 GValue * elem, gpointer user_data)
717 GstIteratorResult res;
718 FindCustomFoldData data;
720 g_return_val_if_fail (G_VALUE_TYPE (elem) == G_TYPE_INVALID
721 || G_VALUE_HOLDS (elem, it->type), GST_ITERATOR_ERROR);
723 if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
724 g_value_init (elem, it->type);
727 data.user_data = user_data;
732 gst_iterator_fold (it, (GstIteratorFoldFunction) find_custom_fold_func,
734 if (res == GST_ITERATOR_RESYNC)
735 gst_iterator_resync (it);
736 } while (res == GST_ITERATOR_RESYNC);
739 g_value_unset (elem);
750 } GstSingleObjectIterator;
752 static guint32 _single_object_dummy_cookie = 0;
755 gst_single_object_iterator_copy (const GstSingleObjectIterator * it,
756 GstSingleObjectIterator * copy)
759 memset (©->object, 0, sizeof (copy->object));
760 g_value_init (©->object, it->parent.type);
761 g_value_copy (&it->object, ©->object);
765 static GstIteratorResult
766 gst_single_object_iterator_next (GstSingleObjectIterator * it, GValue * result)
768 if (it->visited || it->empty)
769 return GST_ITERATOR_DONE;
771 g_value_copy (&it->object, result);
774 return GST_ITERATOR_OK;
778 gst_single_object_iterator_resync (GstSingleObjectIterator * it)
784 gst_single_object_iterator_free (GstSingleObjectIterator * it)
787 g_value_unset (&it->object);
791 * gst_iterator_new_single:
792 * @type: #GType of the passed object
793 * @object: object that this iterator should return
795 * This #GstIterator is a convenient iterator for the common
796 * case where a #GstIterator needs to be returned but only
797 * a single object has to be considered. This happens often
798 * for the #GstPadIterIntLinkFunction.
800 * Returns: the new #GstIterator for @object.
803 gst_iterator_new_single (GType type, const GValue * object)
805 GstSingleObjectIterator *result;
807 result = (GstSingleObjectIterator *)
808 gst_iterator_new (sizeof (GstSingleObjectIterator),
809 type, NULL, &_single_object_dummy_cookie,
810 (GstIteratorCopyFunction) gst_single_object_iterator_copy,
811 (GstIteratorNextFunction) gst_single_object_iterator_next,
812 (GstIteratorItemFunction) NULL,
813 (GstIteratorResyncFunction) gst_single_object_iterator_resync,
814 (GstIteratorFreeFunction) gst_single_object_iterator_free);
817 g_value_init (&result->object, type);
818 g_value_copy (object, &result->object);
819 result->empty = FALSE;
821 result->empty = TRUE;
823 result->visited = FALSE;
825 return GST_ITERATOR (result);