Merge branch 'master' into 0.11
[platform/upstream/gstreamer.git] / gst / gstiterator.c
1 /* GStreamer
2  * Copyright (C) 2004 Wim Taymans <wim@fluendo.com>
3  * Copyright (C) 2011 Sebastian Dröge <sebastian.droege@collabora.co.uk>
4  *
5  * gstiterator.h: Base class for iterating datastructures.
6  *
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.
11  *
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.
16  *
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.
21  */
22
23 /**
24  * SECTION:gstiterator
25  * @short_description: Object to retrieve multiple elements in a threadsafe
26  * way.
27  * @see_also: #GstElement, #GstBin
28  *
29  * A GstIterator is used to retrieve multiple objects from another object in
30  * a threadsafe way.
31  *
32  * Various GStreamer objects provide access to their internal structures using
33  * an iterator.
34  *
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.
38  *
39  * The basic use pattern of an iterator is as follows:
40  *
41  * <example>
42  * <title>Using an iterator</title>
43  *   <programlisting>
44  *    it = _get_iterator(object);
45  *    done = FALSE;
46  *    while (!done) {
47  *      switch (gst_iterator_next (it, &amp;item)) {
48  *        case GST_ITERATOR_OK:
49  *          ... use/change item here...
50  *          g_value_reset (&amp;item);
51  *          break;
52  *        case GST_ITERATOR_RESYNC:
53  *          ...rollback changes to items...
54  *          gst_iterator_resync (it);
55  *          break;
56  *        case GST_ITERATOR_ERROR:
57  *          ...wrong parameters were given...
58  *          done = TRUE;
59  *          break;
60  *        case GST_ITERATOR_DONE:
61  *          done = TRUE;
62  *          break;
63  *      }
64  *    }
65  *    g_value_unset (&amp;item);
66  *    gst_iterator_free (it);
67  *   </programlisting>
68  * </example>
69  *
70  * Last reviewed on 2009-06-16 (0.10.24)
71  */
72
73 #include "gst_private.h"
74 #include <gst/gstiterator.h>
75
76 GstIterator *
77 gst_iterator_copy (const GstIterator * it)
78 {
79   GstIterator *copy;
80
81   copy = g_slice_copy (it->size, it);
82   if (it->copy)
83     it->copy (it, copy);
84
85   return copy;
86 }
87
88 GType
89 gst_iterator_get_type (void)
90 {
91   static GType type = 0;
92
93   if (G_UNLIKELY (type == 0))
94     type = g_boxed_type_register_static ("GstIterator",
95         (GBoxedCopyFunc) gst_iterator_copy, (GBoxedFreeFunc) gst_iterator_free);
96   return type;
97 }
98
99 static void
100 gst_iterator_init (GstIterator * it,
101     guint size,
102     GType type,
103     GMutex * lock,
104     guint32 * master_cookie,
105     GstIteratorCopyFunction copy,
106     GstIteratorNextFunction next,
107     GstIteratorItemFunction item,
108     GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
109 {
110   it->size = size;
111   it->type = type;
112   it->lock = lock;
113   it->master_cookie = master_cookie;
114   it->cookie = *master_cookie;
115   it->copy = copy;
116   it->next = next;
117   it->item = item;
118   it->resync = resync;
119   it->free = free;
120   it->pushed = NULL;
121 }
122
123 /**
124  * gst_iterator_new:
125  * @size: the size of the iterator structure
126  * @type: #GType of children
127  * @lock: pointer to a #GMutex.
128  * @master_cookie: pointer to a guint32 that is changed when the items in the
129  *    iterator changed.
130  * @copy: copy function
131  * @next: function to get next item
132  * @item: function to call on each item retrieved
133  * @resync: function to resync the iterator
134  * @free: function to free the iterator
135  *
136  * Create a new iterator. This function is mainly used for objects
137  * implementing the next/resync/free function to iterate a data structure.
138  *
139  * For each item retrieved, the @item function is called with the lock
140  * held. The @free function is called when the iterator is freed.
141  *
142  * Returns: the new #GstIterator.
143  *
144  * MT safe.
145  */
146 GstIterator *
147 gst_iterator_new (guint size,
148     GType type,
149     GMutex * lock,
150     guint32 * master_cookie,
151     GstIteratorCopyFunction copy,
152     GstIteratorNextFunction next,
153     GstIteratorItemFunction item,
154     GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
155 {
156   GstIterator *result;
157
158   g_return_val_if_fail (size >= sizeof (GstIterator), NULL);
159   g_return_val_if_fail (g_type_qname (type) != 0, NULL);
160   g_return_val_if_fail (master_cookie != NULL, NULL);
161   g_return_val_if_fail (next != NULL, NULL);
162   g_return_val_if_fail (resync != NULL, NULL);
163   g_return_val_if_fail (free != NULL, NULL);
164
165   result = g_slice_alloc0 (size);
166   gst_iterator_init (result, size, type, lock, master_cookie, copy, next, item,
167       resync, free);
168
169   return result;
170 }
171
172 /*
173  * list iterator
174  */
175 typedef struct _GstListIterator
176 {
177   GstIterator iterator;
178   GObject *owner;
179   GList **orig;
180   GList *list;                  /* pointer in list */
181
182   void (*set_value) (GValue * value, gpointer item);
183 } GstListIterator;
184
185 static void
186 gst_list_iterator_copy (const GstListIterator * it, GstListIterator * copy)
187 {
188   if (copy->owner)
189     g_object_ref (copy->owner);
190 }
191
192 static GstIteratorResult
193 gst_list_iterator_next (GstListIterator * it, GValue * elem)
194 {
195   gpointer data;
196
197   if (it->list == NULL)
198     return GST_ITERATOR_DONE;
199
200   data = it->list->data;
201   it->list = g_list_next (it->list);
202
203   it->set_value (elem, data);
204
205   return GST_ITERATOR_OK;
206 }
207
208 static void
209 gst_list_iterator_resync (GstListIterator * it)
210 {
211   it->list = *it->orig;
212 }
213
214 static void
215 gst_list_iterator_free (GstListIterator * it)
216 {
217   if (it->owner)
218     g_object_unref (it->owner);
219 }
220
221 /**
222  * gst_iterator_new_list:
223  * @type: #GType of elements
224  * @lock: pointer to a #GMutex protecting the list.
225  * @master_cookie: pointer to a guint32 that is incremented when the list
226  *     is changed.
227  * @list: pointer to the list
228  * @owner: object owning the list
229  * @item: function to call on each item retrieved
230  *
231  * Create a new iterator designed for iterating @list.
232  *
233  * The list you iterate is usually part of a data structure @owner and is
234  * protected with @lock. 
235  *
236  * The iterator will use @lock to retrieve the next item of the list and it
237  * will then call the @item function before releasing @lock again.
238  *
239  * When a concurrent update to the list is performed, usually by @owner while
240  * holding @lock, @master_cookie will be updated. The iterator implementation
241  * will notice the update of the cookie and will return %GST_ITERATOR_RESYNC to
242  * the user of the iterator in the next call to gst_iterator_next().
243  *
244  * Returns: the new #GstIterator for @list.
245  *
246  * MT safe.
247  */
248 GstIterator *
249 gst_iterator_new_list (GType type,
250     GMutex * lock, guint32 * master_cookie, GList ** list, GObject * owner,
251     GstIteratorItemFunction item)
252 {
253   GstListIterator *result;
254   gpointer set_value;
255
256   if (g_type_is_a (type, G_TYPE_OBJECT)) {
257     set_value = g_value_set_object;
258   } else if (g_type_is_a (type, G_TYPE_BOXED)) {
259     set_value = g_value_set_boxed;
260   } else if (g_type_is_a (type, G_TYPE_POINTER)) {
261     set_value = g_value_set_pointer;
262   } else if (g_type_is_a (type, G_TYPE_STRING)) {
263     set_value = g_value_set_string;
264   } else {
265     g_critical ("List iterators can only be created for lists containing "
266         "instances of GObject, boxed types, pointer types and strings");
267     return NULL;
268   }
269
270   /* no need to lock, nothing can change here */
271   result = (GstListIterator *) gst_iterator_new (sizeof (GstListIterator),
272       type,
273       lock,
274       master_cookie,
275       (GstIteratorCopyFunction) gst_list_iterator_copy,
276       (GstIteratorNextFunction) gst_list_iterator_next,
277       (GstIteratorItemFunction) item,
278       (GstIteratorResyncFunction) gst_list_iterator_resync,
279       (GstIteratorFreeFunction) gst_list_iterator_free);
280
281   result->owner = owner ? g_object_ref (owner) : NULL;
282   result->orig = list;
283   result->list = *list;
284   result->set_value = set_value;
285
286   return GST_ITERATOR (result);
287 }
288
289 static void
290 gst_iterator_pop (GstIterator * it)
291 {
292   if (it->pushed) {
293     gst_iterator_free (it->pushed);
294     it->pushed = NULL;
295   }
296 }
297
298 /**
299  * gst_iterator_next:
300  * @it: The #GstIterator to iterate
301  * @elem: (out caller-allocates): pointer to hold next element
302  *
303  * Get the next item from the iterator in @elem. 
304  *
305  * Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid
306  * value. @elem must have been initialized to the type of the iterator or
307  * initialized to zeroes with g_value_unset(). The caller is responsible for
308  * unsetting or resetting @elem with g_value_unset() or g_value_reset()
309  * after usage.
310  *
311  * When this function returns %GST_ITERATOR_DONE, no more elements can be
312  * retrieved from @it.
313  *
314  * A return value of %GST_ITERATOR_RESYNC indicates that the element list was
315  * concurrently updated. The user of @it should call gst_iterator_resync() to
316  * get the newly updated list. 
317  *
318  * A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error.
319  *
320  * Returns: The result of the iteration. Unset @elem after usage.
321  *
322  * MT safe.
323  */
324 GstIteratorResult
325 gst_iterator_next (GstIterator * it, GValue * elem)
326 {
327   GstIteratorResult result;
328
329   g_return_val_if_fail (it != NULL, GST_ITERATOR_ERROR);
330   g_return_val_if_fail (elem != NULL, GST_ITERATOR_ERROR);
331   g_return_val_if_fail (G_VALUE_TYPE (elem) == G_TYPE_INVALID
332       || G_VALUE_HOLDS (elem, it->type), GST_ITERATOR_ERROR);
333
334   if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
335     g_value_init (elem, it->type);
336
337 restart:
338   if (it->pushed) {
339     result = gst_iterator_next (it->pushed, elem);
340     if (result == GST_ITERATOR_DONE) {
341       /* we are done with this iterator, pop it and
342        * fallthrough iterating the main iterator again. */
343       gst_iterator_pop (it);
344     } else {
345       return result;
346     }
347   }
348
349   if (G_LIKELY (it->lock))
350     g_mutex_lock (it->lock);
351
352   if (G_UNLIKELY (*it->master_cookie != it->cookie)) {
353     result = GST_ITERATOR_RESYNC;
354     goto done;
355   }
356
357   result = it->next (it, elem);
358   if (result == GST_ITERATOR_OK && it->item) {
359     GstIteratorItem itemres;
360
361     itemres = it->item (it, elem);
362     switch (itemres) {
363       case GST_ITERATOR_ITEM_SKIP:
364         if (G_LIKELY (it->lock))
365           g_mutex_unlock (it->lock);
366         g_value_reset (elem);
367         goto restart;
368       case GST_ITERATOR_ITEM_END:
369         result = GST_ITERATOR_DONE;
370         g_value_reset (elem);
371         break;
372       case GST_ITERATOR_ITEM_PASS:
373         break;
374     }
375   }
376
377 done:
378   if (G_LIKELY (it->lock))
379     g_mutex_unlock (it->lock);
380
381   return result;
382 }
383
384 /**
385  * gst_iterator_resync:
386  * @it: The #GstIterator to resync
387  *
388  * Resync the iterator. this function is mostly called
389  * after gst_iterator_next() returned %GST_ITERATOR_RESYNC.
390  *
391  * When an iterator was pushed on @it, it will automatically be popped again
392  * with this function.
393  *
394  * MT safe.
395  */
396 void
397 gst_iterator_resync (GstIterator * it)
398 {
399   g_return_if_fail (it != NULL);
400
401   gst_iterator_pop (it);
402
403   if (G_LIKELY (it->lock))
404     g_mutex_lock (it->lock);
405   it->resync (it);
406   it->cookie = *it->master_cookie;
407   if (G_LIKELY (it->lock))
408     g_mutex_unlock (it->lock);
409 }
410
411 /**
412  * gst_iterator_free:
413  * @it: The #GstIterator to free
414  *
415  * Free the iterator.
416  *
417  * MT safe.
418  */
419 void
420 gst_iterator_free (GstIterator * it)
421 {
422   g_return_if_fail (it != NULL);
423
424   gst_iterator_pop (it);
425
426   it->free (it);
427
428   g_slice_free1 (it->size, it);
429 }
430
431 /**
432  * gst_iterator_push:
433  * @it: The #GstIterator to use
434  * @other: The #GstIterator to push
435  *
436  * Pushes @other iterator onto @it. All calls performed on @it are
437  * forwarded to @other. If @other returns %GST_ITERATOR_DONE, it is
438  * popped again and calls are handled by @it again.
439  *
440  * This function is mainly used by objects implementing the iterator
441  * next function to recurse into substructures.
442  *
443  * When gst_iterator_resync() is called on @it, @other will automatically be
444  * popped.
445  *
446  * MT safe.
447  */
448 void
449 gst_iterator_push (GstIterator * it, GstIterator * other)
450 {
451   g_return_if_fail (it != NULL);
452   g_return_if_fail (other != NULL);
453
454   it->pushed = other;
455 }
456
457 typedef struct _GstIteratorFilter
458 {
459   GstIterator iterator;
460   GstIterator *slave;
461
462   GCompareFunc func;
463   GValue user_data;
464   gboolean have_user_data;
465 } GstIteratorFilter;
466
467 static GstIteratorResult
468 filter_next (GstIteratorFilter * it, GValue * elem)
469 {
470   GstIteratorResult result = GST_ITERATOR_ERROR;
471   gboolean done = FALSE;
472   GValue item = { 0, };
473
474   while (G_LIKELY (!done)) {
475     result = gst_iterator_next (it->slave, &item);
476     switch (result) {
477       case GST_ITERATOR_OK:
478         if (G_LIKELY (GST_ITERATOR (it)->lock))
479           g_mutex_unlock (GST_ITERATOR (it)->lock);
480         if (it->func (&item, &it->user_data) == 0) {
481           g_value_copy (&item, elem);
482           done = TRUE;
483         }
484         g_value_reset (&item);
485         if (G_LIKELY (GST_ITERATOR (it)->lock))
486           g_mutex_lock (GST_ITERATOR (it)->lock);
487         break;
488       case GST_ITERATOR_RESYNC:
489       case GST_ITERATOR_DONE:
490         done = TRUE;
491         break;
492       default:
493         g_assert_not_reached ();
494         break;
495     }
496   }
497   g_value_unset (&item);
498   return result;
499 }
500
501 static void
502 filter_copy (const GstIteratorFilter * it, GstIteratorFilter * copy)
503 {
504   copy->slave = gst_iterator_copy (it->slave);
505
506   if (it->have_user_data) {
507     memset (&copy->user_data, 0, sizeof (copy->user_data));
508     g_value_init (&copy->user_data, G_VALUE_TYPE (&it->user_data));
509     g_value_copy (&it->user_data, &copy->user_data);
510   }
511 }
512
513 static void
514 filter_resync (GstIteratorFilter * it)
515 {
516   gst_iterator_resync (it->slave);
517 }
518
519 static void
520 filter_free (GstIteratorFilter * it)
521 {
522   if (it->have_user_data)
523     g_value_unset (&it->user_data);
524   gst_iterator_free (it->slave);
525 }
526
527 /**
528  * gst_iterator_filter:
529  * @it: The #GstIterator to filter
530  * @func: (scope call): the compare function to select elements
531  * @user_data: (closure): user data passed to the compare function
532  *
533  * Create a new iterator from an existing iterator. The new iterator
534  * will only return those elements that match the given compare function @func.
535  * The first parameter that is passed to @func is the #GValue of the current
536  * iterator element and the second parameter is @user_data. @func should
537  * return 0 for elements that should be included in the filtered iterator.
538  *
539  * When this iterator is freed, @it will also be freed.
540  *
541  * Returns: (transfer full): a new #GstIterator.
542  *
543  * MT safe.
544  */
545 GstIterator *
546 gst_iterator_filter (GstIterator * it, GCompareFunc func,
547     const GValue * user_data)
548 {
549   GstIteratorFilter *result;
550
551   g_return_val_if_fail (it != NULL, NULL);
552   g_return_val_if_fail (func != NULL, NULL);
553
554   result = (GstIteratorFilter *) gst_iterator_new (sizeof (GstIteratorFilter),
555       it->type, it->lock, it->master_cookie,
556       (GstIteratorCopyFunction) filter_copy,
557       (GstIteratorNextFunction) filter_next,
558       (GstIteratorItemFunction) NULL,
559       (GstIteratorResyncFunction) filter_resync,
560       (GstIteratorFreeFunction) filter_free);
561
562   it->lock = NULL;
563   result->func = func;
564   if (user_data) {
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;
568   } else {
569     result->have_user_data = FALSE;
570   }
571   result->slave = it;
572
573   return GST_ITERATOR (result);
574 }
575
576 /**
577  * gst_iterator_fold:
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
582  *
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
586  * @ret.
587  *
588  * This procedure can be used (and is used internally) to implement the
589  * gst_iterator_foreach() and gst_iterator_find_custom() operations.
590  *
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
595  * appropriate.
596  *
597  * The iterator will not be freed.
598  *
599  * Returns: A #GstIteratorResult, as described above.
600  *
601  * MT safe.
602  */
603 GstIteratorResult
604 gst_iterator_fold (GstIterator * it, GstIteratorFoldFunction func,
605     GValue * ret, gpointer user_data)
606 {
607   GValue item = { 0, };
608   GstIteratorResult result;
609
610   while (1) {
611     result = gst_iterator_next (it, &item);
612     switch (result) {
613       case GST_ITERATOR_OK:
614         if (!func (&item, ret, user_data))
615           goto fold_done;
616
617         g_value_reset (&item);
618         break;
619       case GST_ITERATOR_RESYNC:
620       case GST_ITERATOR_ERROR:
621         goto fold_done;
622       case GST_ITERATOR_DONE:
623         goto fold_done;
624     }
625   }
626
627 fold_done:
628   g_value_unset (&item);
629
630   return result;
631 }
632
633 typedef struct
634 {
635   GstIteratorForeachFunction func;
636   gpointer user_data;
637 } ForeachFoldData;
638
639 static gboolean
640 foreach_fold_func (const GValue * item, GValue * unused, ForeachFoldData * data)
641 {
642   data->func (item, data->user_data);
643   return TRUE;
644 }
645
646 /**
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
651  *
652  * Iterate over all element of @it and call the given function @func for
653  * each element.
654  *
655  * Returns: the result call to gst_iterator_fold(). The iterator will not be
656  * freed.
657  *
658  * MT safe.
659  */
660 GstIteratorResult
661 gst_iterator_foreach (GstIterator * it, GstIteratorForeachFunction func,
662     gpointer user_data)
663 {
664   ForeachFoldData data;
665
666   data.func = func;
667   data.user_data = user_data;
668
669   return gst_iterator_fold (it, (GstIteratorFoldFunction) foreach_fold_func,
670       NULL, &data);
671 }
672
673 typedef struct
674 {
675   GCompareFunc func;
676   gpointer user_data;
677   gboolean found;
678 } FindCustomFoldData;
679
680 static gboolean
681 find_custom_fold_func (const GValue * item, GValue * ret,
682     FindCustomFoldData * data)
683 {
684   if (data->func (item, data->user_data) == 0) {
685     data->found = TRUE;
686     g_value_copy (item, ret);
687     return FALSE;
688   } else {
689     return TRUE;
690   }
691 }
692
693 /**
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
699  *
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.
705  *
706  * The iterator will not be freed.
707  *
708  * This function will return FALSE if an error happened to the iterator
709  * or if the element wasn't found.
710  *
711  * Returns: Returns TRUE if the element was found, else FALSE.
712  *
713  * MT safe.
714  */
715 gboolean
716 gst_iterator_find_custom (GstIterator * it, GCompareFunc func,
717     GValue * elem, gpointer user_data)
718 {
719   GstIteratorResult res;
720   FindCustomFoldData data;
721
722   g_return_val_if_fail (G_VALUE_TYPE (elem) == G_TYPE_INVALID
723       || G_VALUE_HOLDS (elem, it->type), GST_ITERATOR_ERROR);
724
725   if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
726     g_value_init (elem, it->type);
727
728   data.func = func;
729   data.user_data = user_data;
730   data.found = FALSE;
731
732   do {
733     res =
734         gst_iterator_fold (it, (GstIteratorFoldFunction) find_custom_fold_func,
735         elem, &data);
736     if (res == GST_ITERATOR_RESYNC)
737       gst_iterator_resync (it);
738   } while (res == GST_ITERATOR_RESYNC);
739
740   if (!data.found)
741     g_value_unset (elem);
742
743   return data.found;
744 }
745
746 typedef struct
747 {
748   GstIterator parent;
749   GValue object;
750   gboolean visited;
751   gboolean empty;
752 } GstSingleObjectIterator;
753
754 static guint32 _single_object_dummy_cookie = 0;
755
756 static void
757 gst_single_object_iterator_copy (const GstSingleObjectIterator * it,
758     GstSingleObjectIterator * copy)
759 {
760   if (!it->empty) {
761     memset (&copy->object, 0, sizeof (copy->object));
762     g_value_init (&copy->object, it->parent.type);
763     g_value_copy (&it->object, &copy->object);
764   }
765 }
766
767 static GstIteratorResult
768 gst_single_object_iterator_next (GstSingleObjectIterator * it, GValue * result)
769 {
770   if (it->visited || it->empty)
771     return GST_ITERATOR_DONE;
772
773   g_value_copy (&it->object, result);
774   it->visited = TRUE;
775
776   return GST_ITERATOR_OK;
777 }
778
779 static void
780 gst_single_object_iterator_resync (GstSingleObjectIterator * it)
781 {
782   it->visited = FALSE;
783 }
784
785 static void
786 gst_single_object_iterator_free (GstSingleObjectIterator * it)
787 {
788   if (!it->empty)
789     g_value_unset (&it->object);
790 }
791
792 /**
793  * gst_iterator_new_single:
794  * @type: #GType of the passed object
795  * @object: object that this iterator should return
796  *
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.
801  *
802  * Returns: the new #GstIterator for @object.
803  *
804  * Since: 0.10.25
805  */
806 GstIterator *
807 gst_iterator_new_single (GType type, const GValue * object)
808 {
809   GstSingleObjectIterator *result;
810
811   result = (GstSingleObjectIterator *)
812       gst_iterator_new (sizeof (GstSingleObjectIterator),
813       type, NULL, &_single_object_dummy_cookie,
814       (GstIteratorCopyFunction) gst_single_object_iterator_copy,
815       (GstIteratorNextFunction) gst_single_object_iterator_next,
816       (GstIteratorItemFunction) NULL,
817       (GstIteratorResyncFunction) gst_single_object_iterator_resync,
818       (GstIteratorFreeFunction) gst_single_object_iterator_free);
819
820   if (object) {
821     g_value_init (&result->object, type);
822     g_value_copy (object, &result->object);
823     result->empty = FALSE;
824   } else {
825     result->empty = TRUE;
826   }
827   result->visited = FALSE;
828
829   return GST_ITERATOR (result);
830 }