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., 51 Franklin St, Fifth Floor,
  20  * Boston, MA 02110-1301, 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 unreffing that object after use.
  38  *
  39  * The basic use pattern of an iterator is as follows:
  40  * |[
  41  *   GstIterator *it = _get_iterator(object);
  42  *   done = FALSE;
  43  *   while (!done) {
  44  *     switch (gst_iterator_next (it, &amp;item)) {
  45  *       case GST_ITERATOR_OK:
  46  *         ... use/change item here...
  47  *         g_value_reset (&amp;item);
  48  *         break;
  49  *       case GST_ITERATOR_RESYNC:
  50  *         ...rollback changes to items...
  51  *         gst_iterator_resync (it);
  52  *         break;
  53  *       case GST_ITERATOR_ERROR:
  54  *         ...wrong parameters were given...
  55  *         done = TRUE;
  56  *         break;
  57  *       case GST_ITERATOR_DONE:
  58  *         done = TRUE;
  59  *         break;
  60  *     }
  61  *   }
  62  *   g_value_unset (&amp;item);
  63  *   gst_iterator_free (it);
  64  * ]|
  65  *
  66  * Last reviewed on 2009-06-16 (0.10.24)
  67  */
  68
  69 #include "gst_private.h"
  70 #include <gst/gstiterator.h>
  71
  72 /**
  73  * gst_iterator_copy:
  74  * @it: a #GstIterator
  75  *
  76  * Copy the iterator and its state.
  77  *
  78  * Returns: a new copy of @it.
  79  */
  80 GstIterator *
  81 gst_iterator_copy (const GstIterator * it)
  82 {
  83   GstIterator *copy;
  84
  85   copy = g_slice_copy (it->size, it);
  86   if (it->copy)
  87     it->copy (it, copy);
  88
  89   return copy;
  90 }
  91
  92 G_DEFINE_BOXED_TYPE (GstIterator, gst_iterator,
  93     (GBoxedCopyFunc) gst_iterator_copy, (GBoxedFreeFunc) gst_iterator_free);
  94
  95 static void
  96 gst_iterator_init (GstIterator * it,
  97     guint size,
  98     GType type,
  99     GMutex * lock,
 100     guint32 * master_cookie,
 101     GstIteratorCopyFunction copy,
 102     GstIteratorNextFunction next,
 103     GstIteratorItemFunction item,
 104     GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
 105 {
 106   it->size = size;
 107   it->type = type;
 108   it->lock = lock;
 109   it->master_cookie = master_cookie;
 110   it->cookie = *master_cookie;
 111   it->copy = copy;
 112   it->next = next;
 113   it->item = item;
 114   it->resync = resync;
 115   it->free = free;
 116   it->pushed = NULL;
 117 }
 118
 119 /**
 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
 125  *    iterator changed.
 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
 131  *
 132  * Create a new iterator. This function is mainly used for objects
 133  * implementing the next/resync/free function to iterate a data structure.
 134  *
 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.
 137  *
 138  * Returns: the new #GstIterator.
 139  *
 140  * MT safe.
 141  */
 142 GstIterator *
 143 gst_iterator_new (guint size,
 144     GType type,
 145     GMutex * lock,
 146     guint32 * master_cookie,
 147     GstIteratorCopyFunction copy,
 148     GstIteratorNextFunction next,
 149     GstIteratorItemFunction item,
 150     GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
 151 {
 152   GstIterator *result;
 153
 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);
 160
 161   result = g_slice_alloc0 (size);
 162   gst_iterator_init (result, size, type, lock, master_cookie, copy, next, item,
 163       resync, free);
 164
 165   return result;
 166 }
 167
 168 /*
 169  * list iterator
 170  */
 171 typedef struct _GstListIterator
 172 {
 173   GstIterator iterator;
 174   GObject *owner;
 175   GList **orig;
 176   GList *list;                  /* pointer in list */
 177
 178   void (*set_value) (GValue * value, gpointer item);
 179 } GstListIterator;
 180
 181 static void
 182 gst_list_iterator_copy (const GstListIterator * it, GstListIterator * copy)
 183 {
 184   if (copy->owner)
 185     g_object_ref (copy->owner);
 186 }
 187
 188 static GstIteratorResult
 189 gst_list_iterator_next (GstListIterator * it, GValue * elem)
 190 {
 191   gpointer data;
 192
 193   if (it->list == NULL)
 194     return GST_ITERATOR_DONE;
 195
 196   data = it->list->data;
 197   it->list = g_list_next (it->list);
 198
 199   it->set_value (elem, data);
 200
 201   return GST_ITERATOR_OK;
 202 }
 203
 204 static void
 205 gst_list_iterator_resync (GstListIterator * it)
 206 {
 207   it->list = *it->orig;
 208 }
 209
 210 static void
 211 gst_list_iterator_free (GstListIterator * it)
 212 {
 213   if (it->owner)
 214     g_object_unref (it->owner);
 215 }
 216
 217 /**
 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
 222  *     is changed.
 223  * @list: pointer to the list
 224  * @owner: object owning the list
 225  * @item: function to call on each item retrieved
 226  *
 227  * Create a new iterator designed for iterating @list.
 228  *
 229  * The list you iterate is usually part of a data structure @owner and is
 230  * protected with @lock.
 231  *
 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.
 234  *
 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().
 239  *
 240  * Returns: the new #GstIterator for @list.
 241  *
 242  * MT safe.
 243  */
 244 GstIterator *
 245 gst_iterator_new_list (GType type,
 246     GMutex * lock, guint32 * master_cookie, GList ** list, GObject * owner,
 247     GstIteratorItemFunction item)
 248 {
 249   GstListIterator *result;
 250   gpointer set_value;
 251
 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;
 260   } else {
 261     g_critical ("List iterators can only be created for lists containing "
 262         "instances of GObject, boxed types, pointer types and strings");
 263     return NULL;
 264   }
 265
 266   /* no need to lock, nothing can change here */
 267   result = (GstListIterator *) gst_iterator_new (sizeof (GstListIterator),
 268       type,
 269       lock,
 270       master_cookie,
 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);
 276
 277   result->owner = owner ? g_object_ref (owner) : NULL;
 278   result->orig = list;
 279   result->list = *list;
 280   result->set_value = set_value;
 281
 282   return GST_ITERATOR (result);
 283 }
 284
 285 static void
 286 gst_iterator_pop (GstIterator * it)
 287 {
 288   if (it->pushed) {
 289     gst_iterator_free (it->pushed);
 290     it->pushed = NULL;
 291   }
 292 }
 293
 294 /**
 295  * gst_iterator_next:
 296  * @it: The #GstIterator to iterate
 297  * @elem: (out caller-allocates): pointer to hold next element
 298  *
 299  * Get the next item from the iterator in @elem.
 300  *
 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()
 305  * after usage.
 306  *
 307  * When this function returns %GST_ITERATOR_DONE, no more elements can be
 308  * retrieved from @it.
 309  *
 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.
 313  *
 314  * A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error.
 315  *
 316  * Returns: The result of the iteration. Unset @elem after usage.
 317  *
 318  * MT safe.
 319  */
 320 GstIteratorResult
 321 gst_iterator_next (GstIterator * it, GValue * elem)
 322 {
 323   GstIteratorResult result;
 324
 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);
 329
 330   if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
 331     g_value_init (elem, it->type);
 332
 333 restart:
 334   if (it->pushed) {
 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);
 340     } else {
 341       return result;
 342     }
 343   }
 344
 345   if (G_LIKELY (it->lock))
 346     g_mutex_lock (it->lock);
 347
 348   if (G_UNLIKELY (*it->master_cookie != it->cookie)) {
 349     result = GST_ITERATOR_RESYNC;
 350     goto done;
 351   }
 352
 353   result = it->next (it, elem);
 354   if (result == GST_ITERATOR_OK && it->item) {
 355     GstIteratorItem itemres;
 356
 357     itemres = it->item (it, elem);
 358     switch (itemres) {
 359       case GST_ITERATOR_ITEM_SKIP:
 360         if (G_LIKELY (it->lock))
 361           g_mutex_unlock (it->lock);
 362         g_value_reset (elem);
 363         goto restart;
 364       case GST_ITERATOR_ITEM_END:
 365         result = GST_ITERATOR_DONE;
 366         g_value_reset (elem);
 367         break;
 368       case GST_ITERATOR_ITEM_PASS:
 369         break;
 370     }
 371   }
 372
 373 done:
 374   if (G_LIKELY (it->lock))
 375     g_mutex_unlock (it->lock);
 376
 377   return result;
 378 }
 379
 380 /**
 381  * gst_iterator_resync:
 382  * @it: The #GstIterator to resync
 383  *
 384  * Resync the iterator. this function is mostly called
 385  * after gst_iterator_next() returned %GST_ITERATOR_RESYNC.
 386  *
 387  * When an iterator was pushed on @it, it will automatically be popped again
 388  * with this function.
 389  *
 390  * MT safe.
 391  */
 392 void
 393 gst_iterator_resync (GstIterator * it)
 394 {
 395   g_return_if_fail (it != NULL);
 396
 397   gst_iterator_pop (it);
 398
 399   if (G_LIKELY (it->lock))
 400     g_mutex_lock (it->lock);
 401   it->resync (it);
 402   it->cookie = *it->master_cookie;
 403   if (G_LIKELY (it->lock))
 404     g_mutex_unlock (it->lock);
 405 }
 406
 407 /**
 408  * gst_iterator_free:
 409  * @it: The #GstIterator to free
 410  *
 411  * Free the iterator.
 412  *
 413  * MT safe.
 414  */
 415 void
 416 gst_iterator_free (GstIterator * it)
 417 {
 418   g_return_if_fail (it != NULL);
 419
 420   gst_iterator_pop (it);
 421
 422   it->free (it);
 423
 424   g_slice_free1 (it->size, it);
 425 }
 426
 427 /**
 428  * gst_iterator_push:
 429  * @it: The #GstIterator to use
 430  * @other: The #GstIterator to push
 431  *
 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.
 435  *
 436  * This function is mainly used by objects implementing the iterator
 437  * next function to recurse into substructures.
 438  *
 439  * When gst_iterator_resync() is called on @it, @other will automatically be
 440  * popped.
 441  *
 442  * MT safe.
 443  */
 444 void
 445 gst_iterator_push (GstIterator * it, GstIterator * other)
 446 {
 447   g_return_if_fail (it != NULL);
 448   g_return_if_fail (other != NULL);
 449
 450   it->pushed = other;
 451 }
 452
 453 typedef struct _GstIteratorFilter
 454 {
 455   GstIterator iterator;
 456   GstIterator *slave;
 457
 458   GMutex *master_lock;
 459   GCompareFunc func;
 460   GValue user_data;
 461   gboolean have_user_data;
 462 } GstIteratorFilter;
 463
 464 static GstIteratorResult
 465 filter_next (GstIteratorFilter * it, GValue * elem)
 466 {
 467   GstIteratorResult result = GST_ITERATOR_ERROR;
 468   gboolean done = FALSE;
 469   GValue item = { 0, };
 470
 471   while (G_LIKELY (!done)) {
 472     result = gst_iterator_next (it->slave, &item);
 473     switch (result) {
 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);
 479           done = TRUE;
 480         }
 481         g_value_reset (&item);
 482         if (G_LIKELY (it->master_lock))
 483           g_mutex_lock (it->master_lock);
 484         break;
 485       case GST_ITERATOR_RESYNC:
 486       case GST_ITERATOR_DONE:
 487         done = TRUE;
 488         break;
 489       default:
 490         g_assert_not_reached ();
 491         break;
 492     }
 493   }
 494   g_value_unset (&item);
 495   return result;
 496 }
 497
 498 static void
 499 filter_copy (const GstIteratorFilter * it, GstIteratorFilter * copy)
 500 {
 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;
 504
 505   if (it->have_user_data) {
 506     memset (&copy->user_data, 0, sizeof (copy->user_data));
 507     g_value_init (&copy->user_data, G_VALUE_TYPE (&it->user_data));
 508     g_value_copy (&it->user_data, &copy->user_data);
 509   }
 510 }
 511
 512 static void
 513 filter_resync (GstIteratorFilter * it)
 514 {
 515   gst_iterator_resync (it->slave);
 516 }
 517
 518 static void
 519 filter_free (GstIteratorFilter * it)
 520 {
 521   if (it->have_user_data)
 522     g_value_unset (&it->user_data);
 523   gst_iterator_free (it->slave);
 524 }
 525
 526 /**
 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
 531  *
 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.
 537  *
 538  * When this iterator is freed, @it will also be freed.
 539  *
 540  * Returns: (transfer full): a new #GstIterator.
 541  *
 542  * MT safe.
 543  */
 544 GstIterator *
 545 gst_iterator_filter (GstIterator * it, GCompareFunc func,
 546     const GValue * user_data)
 547 {
 548   GstIteratorFilter *result;
 549
 550   g_return_val_if_fail (it != NULL, NULL);
 551   g_return_val_if_fail (func != NULL, NULL);
 552
 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);
 560
 561   result->master_lock = it->lock;
 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 GstIterator *
 805 gst_iterator_new_single (GType type, const GValue * object)
 806 {
 807   GstSingleObjectIterator *result;
 808
 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);
 817
 818   if (object) {
 819     g_value_init (&result->object, type);
 820     g_value_copy (object, &result->object);
 821     result->empty = FALSE;
 822   } else {
 823     result->empty = TRUE;
 824   }
 825   result->visited = FALSE;
 826
 827   return GST_ITERATOR (result);
 828 }