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 * Note that if calling a GstIterator function results in your code receiving
36 * a refcounted object (with, say, g_value_get_object()), the refcount for that
37 * object will not be increased. Your code is responsible for taking a reference
38 * if it wants to continue using it later.
40 * The basic use pattern of an iterator is as follows:
42 * GstIterator *it = _get_iterator(object);
43 * GValue item = G_VALUE_INIT;
46 * switch (gst_iterator_next (it, &item)) {
47 * case GST_ITERATOR_OK:
48 * ...get/use/change item here...
49 * g_value_reset (&item);
51 * case GST_ITERATOR_RESYNC:
52 * ...rollback changes to items...
53 * gst_iterator_resync (it);
55 * case GST_ITERATOR_ERROR:
56 * ...wrong parameters were given...
59 * case GST_ITERATOR_DONE:
64 * g_value_unset (&item);
65 * gst_iterator_free (it);
69 #include "gst_private.h"
70 #include <gst/gstiterator.h>
76 * Copy the iterator and its state.
78 * Returns: a new copy of @it.
81 gst_iterator_copy (const GstIterator * it)
85 copy = g_slice_copy (it->size, it);
92 G_DEFINE_BOXED_TYPE (GstIterator, gst_iterator,
93 (GBoxedCopyFunc) gst_iterator_copy, (GBoxedFreeFunc) gst_iterator_free);
96 gst_iterator_init (GstIterator * it,
100 guint32 * master_cookie,
101 GstIteratorCopyFunction copy,
102 GstIteratorNextFunction next,
103 GstIteratorItemFunction item,
104 GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
109 it->master_cookie = master_cookie;
110 it->cookie = *master_cookie;
120 * gst_iterator_new: (skip)
121 * @size: the size of the iterator structure
122 * @type: #GType of children
123 * @lock: pointer to a #GMutex.
124 * @master_cookie: pointer to a guint32 that is changed when the items in the
126 * @copy: copy function
127 * @next: function to get next item
128 * @item: function to call on each item retrieved
129 * @resync: function to resync the iterator
130 * @free: function to free the iterator
132 * Create a new iterator. This function is mainly used for objects
133 * implementing the next/resync/free function to iterate a data structure.
135 * For each item retrieved, the @item function is called with the lock
136 * held. The @free function is called when the iterator is freed.
138 * Returns: the new #GstIterator.
143 gst_iterator_new (guint size,
146 guint32 * master_cookie,
147 GstIteratorCopyFunction copy,
148 GstIteratorNextFunction next,
149 GstIteratorItemFunction item,
150 GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
154 g_return_val_if_fail (size >= sizeof (GstIterator), NULL);
155 g_return_val_if_fail (g_type_qname (type) != 0, NULL);
156 g_return_val_if_fail (master_cookie != NULL, NULL);
157 g_return_val_if_fail (next != NULL, NULL);
158 g_return_val_if_fail (resync != NULL, NULL);
159 g_return_val_if_fail (free != NULL, NULL);
161 result = g_slice_alloc0 (size);
162 gst_iterator_init (result, size, type, lock, master_cookie, copy, next, item,
171 typedef struct _GstListIterator
173 GstIterator iterator;
176 GList *list; /* pointer in list */
178 void (*set_value) (GValue * value, gpointer item);
182 gst_list_iterator_copy (const GstListIterator * it, GstListIterator * copy)
185 g_object_ref (copy->owner);
188 static GstIteratorResult
189 gst_list_iterator_next (GstListIterator * it, GValue * elem)
193 if (it->list == NULL)
194 return GST_ITERATOR_DONE;
196 data = it->list->data;
197 it->list = g_list_next (it->list);
199 it->set_value (elem, data);
201 return GST_ITERATOR_OK;
205 gst_list_iterator_resync (GstListIterator * it)
207 it->list = *it->orig;
211 gst_list_iterator_free (GstListIterator * it)
214 g_object_unref (it->owner);
218 * gst_iterator_new_list: (skip)
219 * @type: #GType of elements
220 * @lock: pointer to a #GMutex protecting the list.
221 * @master_cookie: pointer to a guint32 that is incremented when the list
223 * @list: pointer to the list
224 * @owner: object owning the list
225 * @item: function to call on each item retrieved
227 * Create a new iterator designed for iterating @list.
229 * The list you iterate is usually part of a data structure @owner and is
230 * protected with @lock.
232 * The iterator will use @lock to retrieve the next item of the list and it
233 * will then call the @item function before releasing @lock again.
235 * When a concurrent update to the list is performed, usually by @owner while
236 * holding @lock, @master_cookie will be updated. The iterator implementation
237 * will notice the update of the cookie and will return %GST_ITERATOR_RESYNC to
238 * the user of the iterator in the next call to gst_iterator_next().
240 * Returns: the new #GstIterator for @list.
245 gst_iterator_new_list (GType type,
246 GMutex * lock, guint32 * master_cookie, GList ** list, GObject * owner,
247 GstIteratorItemFunction item)
249 GstListIterator *result;
252 if (g_type_is_a (type, G_TYPE_OBJECT)) {
253 set_value = g_value_set_object;
254 } else if (g_type_is_a (type, G_TYPE_BOXED)) {
255 set_value = g_value_set_boxed;
256 } else if (g_type_is_a (type, G_TYPE_POINTER)) {
257 set_value = g_value_set_pointer;
258 } else if (g_type_is_a (type, G_TYPE_STRING)) {
259 set_value = g_value_set_string;
261 g_critical ("List iterators can only be created for lists containing "
262 "instances of GObject, boxed types, pointer types and strings");
266 /* no need to lock, nothing can change here */
267 result = (GstListIterator *) gst_iterator_new (sizeof (GstListIterator),
271 (GstIteratorCopyFunction) gst_list_iterator_copy,
272 (GstIteratorNextFunction) gst_list_iterator_next,
273 (GstIteratorItemFunction) item,
274 (GstIteratorResyncFunction) gst_list_iterator_resync,
275 (GstIteratorFreeFunction) gst_list_iterator_free);
277 result->owner = owner ? g_object_ref (owner) : NULL;
279 result->list = *list;
280 result->set_value = set_value;
282 return GST_ITERATOR (result);
286 gst_iterator_pop (GstIterator * it)
289 gst_iterator_free (it->pushed);
296 * @it: The #GstIterator to iterate
297 * @elem: (out caller-allocates): pointer to hold next element
299 * Get the next item from the iterator in @elem.
301 * Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid
302 * value. @elem must have been initialized to the type of the iterator or
303 * initialized to zeroes with g_value_unset(). The caller is responsible for
304 * unsetting or resetting @elem with g_value_unset() or g_value_reset()
307 * When this function returns %GST_ITERATOR_DONE, no more elements can be
308 * retrieved from @it.
310 * A return value of %GST_ITERATOR_RESYNC indicates that the element list was
311 * concurrently updated. The user of @it should call gst_iterator_resync() to
312 * get the newly updated list.
314 * A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error.
316 * Returns: The result of the iteration. Unset @elem after usage.
321 gst_iterator_next (GstIterator * it, GValue * elem)
323 GstIteratorResult result;
325 g_return_val_if_fail (it != NULL, GST_ITERATOR_ERROR);
326 g_return_val_if_fail (elem != NULL, GST_ITERATOR_ERROR);
327 g_return_val_if_fail (G_VALUE_TYPE (elem) == G_TYPE_INVALID
328 || G_VALUE_HOLDS (elem, it->type), GST_ITERATOR_ERROR);
330 if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
331 g_value_init (elem, it->type);
335 result = gst_iterator_next (it->pushed, elem);
336 if (result == GST_ITERATOR_DONE) {
337 /* we are done with this iterator, pop it and
338 * fallthrough iterating the main iterator again. */
339 gst_iterator_pop (it);
345 if (G_LIKELY (it->lock))
346 g_mutex_lock (it->lock);
348 if (G_UNLIKELY (*it->master_cookie != it->cookie)) {
349 result = GST_ITERATOR_RESYNC;
353 result = it->next (it, elem);
354 if (result == GST_ITERATOR_OK && it->item) {
355 GstIteratorItem itemres;
357 itemres = it->item (it, elem);
359 case GST_ITERATOR_ITEM_SKIP:
360 if (G_LIKELY (it->lock))
361 g_mutex_unlock (it->lock);
362 g_value_reset (elem);
364 case GST_ITERATOR_ITEM_END:
365 result = GST_ITERATOR_DONE;
366 g_value_reset (elem);
368 case GST_ITERATOR_ITEM_PASS:
374 if (G_LIKELY (it->lock))
375 g_mutex_unlock (it->lock);
381 * gst_iterator_resync:
382 * @it: The #GstIterator to resync
384 * Resync the iterator. this function is mostly called
385 * after gst_iterator_next() returned %GST_ITERATOR_RESYNC.
387 * When an iterator was pushed on @it, it will automatically be popped again
388 * with this function.
393 gst_iterator_resync (GstIterator * it)
395 g_return_if_fail (it != NULL);
397 gst_iterator_pop (it);
399 if (G_LIKELY (it->lock))
400 g_mutex_lock (it->lock);
402 it->cookie = *it->master_cookie;
403 if (G_LIKELY (it->lock))
404 g_mutex_unlock (it->lock);
409 * @it: The #GstIterator to free
416 gst_iterator_free (GstIterator * it)
418 g_return_if_fail (it != NULL);
420 gst_iterator_pop (it);
424 g_slice_free1 (it->size, it);
429 * @it: The #GstIterator to use
430 * @other: The #GstIterator to push
432 * Pushes @other iterator onto @it. All calls performed on @it are
433 * forwarded to @other. If @other returns %GST_ITERATOR_DONE, it is
434 * popped again and calls are handled by @it again.
436 * This function is mainly used by objects implementing the iterator
437 * next function to recurse into substructures.
439 * When gst_iterator_resync() is called on @it, @other will automatically be
445 gst_iterator_push (GstIterator * it, GstIterator * other)
447 g_return_if_fail (it != NULL);
448 g_return_if_fail (other != NULL);
453 typedef struct _GstIteratorFilter
455 GstIterator iterator;
461 gboolean have_user_data;
464 static GstIteratorResult
465 filter_next (GstIteratorFilter * it, GValue * elem)
467 GstIteratorResult result = GST_ITERATOR_ERROR;
468 gboolean done = FALSE;
469 GValue item = { 0, };
471 while (G_LIKELY (!done)) {
472 result = gst_iterator_next (it->slave, &item);
474 case GST_ITERATOR_OK:
475 if (G_LIKELY (it->master_lock))
476 g_mutex_unlock (it->master_lock);
477 if (it->func (&item, &it->user_data) == 0) {
478 g_value_copy (&item, elem);
481 g_value_reset (&item);
482 if (G_LIKELY (it->master_lock))
483 g_mutex_lock (it->master_lock);
485 case GST_ITERATOR_RESYNC:
486 case GST_ITERATOR_DONE:
490 g_assert_not_reached ();
494 g_value_unset (&item);
499 filter_copy (const GstIteratorFilter * it, GstIteratorFilter * copy)
501 copy->slave = gst_iterator_copy (it->slave);
502 copy->master_lock = copy->slave->lock ? copy->slave->lock : it->master_lock;
503 copy->slave->lock = NULL;
505 if (it->have_user_data) {
506 memset (©->user_data, 0, sizeof (copy->user_data));
507 g_value_init (©->user_data, G_VALUE_TYPE (&it->user_data));
508 g_value_copy (&it->user_data, ©->user_data);
513 filter_resync (GstIteratorFilter * it)
515 gst_iterator_resync (it->slave);
519 filter_free (GstIteratorFilter * it)
521 if (it->have_user_data)
522 g_value_unset (&it->user_data);
523 gst_iterator_free (it->slave);
527 * gst_iterator_filter:
528 * @it: The #GstIterator to filter
529 * @func: (scope call): the compare function to select elements
530 * @user_data: (closure): user data passed to the compare function
532 * Create a new iterator from an existing iterator. The new iterator
533 * will only return those elements that match the given compare function @func.
534 * The first parameter that is passed to @func is the #GValue of the current
535 * iterator element and the second parameter is @user_data. @func should
536 * return 0 for elements that should be included in the filtered iterator.
538 * When this iterator is freed, @it will also be freed.
540 * Returns: (transfer full): a new #GstIterator.
545 gst_iterator_filter (GstIterator * it, GCompareFunc func,
546 const GValue * user_data)
548 GstIteratorFilter *result;
550 g_return_val_if_fail (it != NULL, NULL);
551 g_return_val_if_fail (func != NULL, NULL);
553 result = (GstIteratorFilter *) gst_iterator_new (sizeof (GstIteratorFilter),
554 it->type, it->lock, it->master_cookie,
555 (GstIteratorCopyFunction) filter_copy,
556 (GstIteratorNextFunction) filter_next,
557 (GstIteratorItemFunction) NULL,
558 (GstIteratorResyncFunction) filter_resync,
559 (GstIteratorFreeFunction) filter_free);
561 result->master_lock = it->lock;
565 g_value_init (&result->user_data, G_VALUE_TYPE (user_data));
566 g_value_copy (user_data, &result->user_data);
567 result->have_user_data = TRUE;
569 result->have_user_data = FALSE;
573 return GST_ITERATOR (result);
578 * @it: The #GstIterator to fold over
579 * @func: (scope call): the fold function
580 * @ret: the seed value passed to the fold function
581 * @user_data: (closure): user data passed to the fold function
583 * Folds @func over the elements of @iter. That is to say, @func will be called
584 * as @func (object, @ret, @user_data) for each object in @it. The normal use
585 * of this procedure is to accumulate the results of operating on the objects in
588 * This procedure can be used (and is used internally) to implement the
589 * gst_iterator_foreach() and gst_iterator_find_custom() operations.
591 * The fold will proceed as long as @func returns %TRUE. When the iterator has no
592 * more arguments, %GST_ITERATOR_DONE will be returned. If @func returns %FALSE,
593 * the fold will stop, and %GST_ITERATOR_OK will be returned. Errors or resyncs
594 * will cause fold to return %GST_ITERATOR_ERROR or %GST_ITERATOR_RESYNC as
597 * The iterator will not be freed.
599 * Returns: A #GstIteratorResult, as described above.
604 gst_iterator_fold (GstIterator * it, GstIteratorFoldFunction func,
605 GValue * ret, gpointer user_data)
607 GValue item = { 0, };
608 GstIteratorResult result;
611 result = gst_iterator_next (it, &item);
613 case GST_ITERATOR_OK:
614 if (!func (&item, ret, user_data))
617 g_value_reset (&item);
619 case GST_ITERATOR_RESYNC:
620 case GST_ITERATOR_ERROR:
622 case GST_ITERATOR_DONE:
628 g_value_unset (&item);
635 GstIteratorForeachFunction func;
640 foreach_fold_func (const GValue * item, GValue * unused, ForeachFoldData * data)
642 data->func (item, data->user_data);
647 * gst_iterator_foreach:
648 * @it: The #GstIterator to iterate
649 * @func: (scope call): the function to call for each element.
650 * @user_data: (closure): user data passed to the function
652 * Iterate over all element of @it and call the given function @func for
655 * Returns: the result call to gst_iterator_fold(). The iterator will not be
661 gst_iterator_foreach (GstIterator * it, GstIteratorForeachFunction func,
664 ForeachFoldData data;
667 data.user_data = user_data;
669 return gst_iterator_fold (it, (GstIteratorFoldFunction) foreach_fold_func,
678 } FindCustomFoldData;
681 find_custom_fold_func (const GValue * item, GValue * ret,
682 FindCustomFoldData * data)
684 if (data->func (item, data->user_data) == 0) {
686 g_value_copy (item, ret);
694 * gst_iterator_find_custom:
695 * @it: The #GstIterator to iterate
696 * @func: (scope call): the compare function to use
697 * @elem: (out): pointer to a #GValue where to store the result
698 * @user_data: (closure): user data passed to the compare function
700 * Find the first element in @it that matches the compare function @func.
701 * @func should return 0 when the element is found. The first parameter
702 * to @func will be the current element of the iterator and the
703 * second parameter will be @user_data.
704 * The result will be stored in @elem if a result is found.
706 * The iterator will not be freed.
708 * This function will return %FALSE if an error happened to the iterator
709 * or if the element wasn't found.
711 * Returns: Returns %TRUE if the element was found, else %FALSE.
716 gst_iterator_find_custom (GstIterator * it, GCompareFunc func,
717 GValue * elem, gpointer user_data)
719 GstIteratorResult res;
720 FindCustomFoldData data;
722 g_return_val_if_fail (G_VALUE_TYPE (elem) == G_TYPE_INVALID
723 || G_VALUE_HOLDS (elem, it->type), GST_ITERATOR_ERROR);
725 if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
726 g_value_init (elem, it->type);
729 data.user_data = user_data;
734 gst_iterator_fold (it, (GstIteratorFoldFunction) find_custom_fold_func,
736 if (res == GST_ITERATOR_RESYNC)
737 gst_iterator_resync (it);
738 } while (res == GST_ITERATOR_RESYNC);
741 g_value_unset (elem);
752 } GstSingleObjectIterator;
754 static guint32 _single_object_dummy_cookie = 0;
757 gst_single_object_iterator_copy (const GstSingleObjectIterator * it,
758 GstSingleObjectIterator * copy)
761 memset (©->object, 0, sizeof (copy->object));
762 g_value_init (©->object, it->parent.type);
763 g_value_copy (&it->object, ©->object);
767 static GstIteratorResult
768 gst_single_object_iterator_next (GstSingleObjectIterator * it, GValue * result)
770 if (it->visited || it->empty)
771 return GST_ITERATOR_DONE;
773 g_value_copy (&it->object, result);
776 return GST_ITERATOR_OK;
780 gst_single_object_iterator_resync (GstSingleObjectIterator * it)
786 gst_single_object_iterator_free (GstSingleObjectIterator * it)
789 g_value_unset (&it->object);
793 * gst_iterator_new_single:
794 * @type: #GType of the passed object
795 * @object: object that this iterator should return
797 * This #GstIterator is a convenient iterator for the common
798 * case where a #GstIterator needs to be returned but only
799 * a single object has to be considered. This happens often
800 * for the #GstPadIterIntLinkFunction.
802 * Returns: the new #GstIterator for @object.
805 gst_iterator_new_single (GType type, const GValue * object)
807 GstSingleObjectIterator *result;
809 result = (GstSingleObjectIterator *)
810 gst_iterator_new (sizeof (GstSingleObjectIterator),
811 type, NULL, &_single_object_dummy_cookie,
812 (GstIteratorCopyFunction) gst_single_object_iterator_copy,
813 (GstIteratorNextFunction) gst_single_object_iterator_next,
814 (GstIteratorItemFunction) NULL,
815 (GstIteratorResyncFunction) gst_single_object_iterator_resync,
816 (GstIteratorFreeFunction) gst_single_object_iterator_free);
819 g_value_init (&result->object, type);
820 g_value_copy (object, &result->object);
821 result->empty = FALSE;
823 result->empty = TRUE;
825 result->visited = FALSE;
827 return GST_ITERATOR (result);