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 G_DEFINE_BOXED_TYPE (GstIterator, gst_iterator,
  89     (GBoxedCopyFunc) gst_iterator_copy, (GBoxedFreeFunc) gst_iterator_free);
  90
  91 static void
  92 gst_iterator_init (GstIterator * it,
  93     guint size,
  94     GType type,
  95     GMutex * lock,
  96     guint32 * master_cookie,
  97     GstIteratorCopyFunction copy,
  98     GstIteratorNextFunction next,
  99     GstIteratorItemFunction item,
 100     GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
 101 {
 102   it->size = size;
 103   it->type = type;
 104   it->lock = lock;
 105   it->master_cookie = master_cookie;
 106   it->cookie = *master_cookie;
 107   it->copy = copy;
 108   it->next = next;
 109   it->item = item;
 110   it->resync = resync;
 111   it->free = free;
 112   it->pushed = NULL;
 113 }
 114
 115 /**
 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
 121  *    iterator changed.
 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
 127  *
 128  * Create a new iterator. This function is mainly used for objects
 129  * implementing the next/resync/free function to iterate a data structure.
 130  *
 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.
 133  *
 134  * Returns: the new #GstIterator.
 135  *
 136  * MT safe.
 137  */
 138 GstIterator *
 139 gst_iterator_new (guint size,
 140     GType type,
 141     GMutex * lock,
 142     guint32 * master_cookie,
 143     GstIteratorCopyFunction copy,
 144     GstIteratorNextFunction next,
 145     GstIteratorItemFunction item,
 146     GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
 147 {
 148   GstIterator *result;
 149
 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);
 156
 157   result = g_slice_alloc0 (size);
 158   gst_iterator_init (result, size, type, lock, master_cookie, copy, next, item,
 159       resync, free);
 160
 161   return result;
 162 }
 163
 164 /*
 165  * list iterator
 166  */
 167 typedef struct _GstListIterator
 168 {
 169   GstIterator iterator;
 170   GObject *owner;
 171   GList **orig;
 172   GList *list;                  /* pointer in list */
 173
 174   void (*set_value) (GValue * value, gpointer item);
 175 } GstListIterator;
 176
 177 static void
 178 gst_list_iterator_copy (const GstListIterator * it, GstListIterator * copy)
 179 {
 180   if (copy->owner)
 181     g_object_ref (copy->owner);
 182 }
 183
 184 static GstIteratorResult
 185 gst_list_iterator_next (GstListIterator * it, GValue * elem)
 186 {
 187   gpointer data;
 188
 189   if (it->list == NULL)
 190     return GST_ITERATOR_DONE;
 191
 192   data = it->list->data;
 193   it->list = g_list_next (it->list);
 194
 195   it->set_value (elem, data);
 196
 197   return GST_ITERATOR_OK;
 198 }
 199
 200 static void
 201 gst_list_iterator_resync (GstListIterator * it)
 202 {
 203   it->list = *it->orig;
 204 }
 205
 206 static void
 207 gst_list_iterator_free (GstListIterator * it)
 208 {
 209   if (it->owner)
 210     g_object_unref (it->owner);
 211 }
 212
 213 /**
 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
 218  *     is changed.
 219  * @list: pointer to the list
 220  * @owner: object owning the list
 221  * @item: function to call on each item retrieved
 222  *
 223  * Create a new iterator designed for iterating @list.
 224  *
 225  * The list you iterate is usually part of a data structure @owner and is
 226  * protected with @lock.
 227  *
 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.
 230  *
 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().
 235  *
 236  * Returns: the new #GstIterator for @list.
 237  *
 238  * MT safe.
 239  */
 240 GstIterator *
 241 gst_iterator_new_list (GType type,
 242     GMutex * lock, guint32 * master_cookie, GList ** list, GObject * owner,
 243     GstIteratorItemFunction item)
 244 {
 245   GstListIterator *result;
 246   gpointer set_value;
 247
 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;
 256   } else {
 257     g_critical ("List iterators can only be created for lists containing "
 258         "instances of GObject, boxed types, pointer types and strings");
 259     return NULL;
 260   }
 261
 262   /* no need to lock, nothing can change here */
 263   result = (GstListIterator *) gst_iterator_new (sizeof (GstListIterator),
 264       type,
 265       lock,
 266       master_cookie,
 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);
 272
 273   result->owner = owner ? g_object_ref (owner) : NULL;
 274   result->orig = list;
 275   result->list = *list;
 276   result->set_value = set_value;
 277
 278   return GST_ITERATOR (result);
 279 }
 280
 281 static void
 282 gst_iterator_pop (GstIterator * it)
 283 {
 284   if (it->pushed) {
 285     gst_iterator_free (it->pushed);
 286     it->pushed = NULL;
 287   }
 288 }
 289
 290 /**
 291  * gst_iterator_next:
 292  * @it: The #GstIterator to iterate
 293  * @elem: (out caller-allocates): pointer to hold next element
 294  *
 295  * Get the next item from the iterator in @elem.
 296  *
 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()
 301  * after usage.
 302  *
 303  * When this function returns %GST_ITERATOR_DONE, no more elements can be
 304  * retrieved from @it.
 305  *
 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.
 309  *
 310  * A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error.
 311  *
 312  * Returns: The result of the iteration. Unset @elem after usage.
 313  *
 314  * MT safe.
 315  */
 316 GstIteratorResult
 317 gst_iterator_next (GstIterator * it, GValue * elem)
 318 {
 319   GstIteratorResult result;
 320
 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);
 325
 326   if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
 327     g_value_init (elem, it->type);
 328
 329 restart:
 330   if (it->pushed) {
 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);
 336     } else {
 337       return result;
 338     }
 339   }
 340
 341   if (G_LIKELY (it->lock))
 342     g_mutex_lock (it->lock);
 343
 344   if (G_UNLIKELY (*it->master_cookie != it->cookie)) {
 345     result = GST_ITERATOR_RESYNC;
 346     goto done;
 347   }
 348
 349   result = it->next (it, elem);
 350   if (result == GST_ITERATOR_OK && it->item) {
 351     GstIteratorItem itemres;
 352
 353     itemres = it->item (it, elem);
 354     switch (itemres) {
 355       case GST_ITERATOR_ITEM_SKIP:
 356         if (G_LIKELY (it->lock))
 357           g_mutex_unlock (it->lock);
 358         g_value_reset (elem);
 359         goto restart;
 360       case GST_ITERATOR_ITEM_END:
 361         result = GST_ITERATOR_DONE;
 362         g_value_reset (elem);
 363         break;
 364       case GST_ITERATOR_ITEM_PASS:
 365         break;
 366     }
 367   }
 368
 369 done:
 370   if (G_LIKELY (it->lock))
 371     g_mutex_unlock (it->lock);
 372
 373   return result;
 374 }
 375
 376 /**
 377  * gst_iterator_resync:
 378  * @it: The #GstIterator to resync
 379  *
 380  * Resync the iterator. this function is mostly called
 381  * after gst_iterator_next() returned %GST_ITERATOR_RESYNC.
 382  *
 383  * When an iterator was pushed on @it, it will automatically be popped again
 384  * with this function.
 385  *
 386  * MT safe.
 387  */
 388 void
 389 gst_iterator_resync (GstIterator * it)
 390 {
 391   g_return_if_fail (it != NULL);
 392
 393   gst_iterator_pop (it);
 394
 395   if (G_LIKELY (it->lock))
 396     g_mutex_lock (it->lock);
 397   it->resync (it);
 398   it->cookie = *it->master_cookie;
 399   if (G_LIKELY (it->lock))
 400     g_mutex_unlock (it->lock);
 401 }
 402
 403 /**
 404  * gst_iterator_free:
 405  * @it: The #GstIterator to free
 406  *
 407  * Free the iterator.
 408  *
 409  * MT safe.
 410  */
 411 void
 412 gst_iterator_free (GstIterator * it)
 413 {
 414   g_return_if_fail (it != NULL);
 415
 416   gst_iterator_pop (it);
 417
 418   it->free (it);
 419
 420   g_slice_free1 (it->size, it);
 421 }
 422
 423 /**
 424  * gst_iterator_push:
 425  * @it: The #GstIterator to use
 426  * @other: The #GstIterator to push
 427  *
 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.
 431  *
 432  * This function is mainly used by objects implementing the iterator
 433  * next function to recurse into substructures.
 434  *
 435  * When gst_iterator_resync() is called on @it, @other will automatically be
 436  * popped.
 437  *
 438  * MT safe.
 439  */
 440 void
 441 gst_iterator_push (GstIterator * it, GstIterator * other)
 442 {
 443   g_return_if_fail (it != NULL);
 444   g_return_if_fail (other != NULL);
 445
 446   it->pushed = other;
 447 }
 448
 449 typedef struct _GstIteratorFilter
 450 {
 451   GstIterator iterator;
 452   GstIterator *slave;
 453
 454   GCompareFunc func;
 455   GValue user_data;
 456   gboolean have_user_data;
 457 } GstIteratorFilter;
 458
 459 static GstIteratorResult
 460 filter_next (GstIteratorFilter * it, GValue * elem)
 461 {
 462   GstIteratorResult result = GST_ITERATOR_ERROR;
 463   gboolean done = FALSE;
 464   GValue item = { 0, };
 465
 466   while (G_LIKELY (!done)) {
 467     result = gst_iterator_next (it->slave, &item);
 468     switch (result) {
 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);
 474           done = TRUE;
 475         }
 476         g_value_reset (&item);
 477         if (G_LIKELY (GST_ITERATOR (it)->lock))
 478           g_mutex_lock (GST_ITERATOR (it)->lock);
 479         break;
 480       case GST_ITERATOR_RESYNC:
 481       case GST_ITERATOR_DONE:
 482         done = TRUE;
 483         break;
 484       default:
 485         g_assert_not_reached ();
 486         break;
 487     }
 488   }
 489   g_value_unset (&item);
 490   return result;
 491 }
 492
 493 static void
 494 filter_copy (const GstIteratorFilter * it, GstIteratorFilter * copy)
 495 {
 496   copy->slave = gst_iterator_copy (it->slave);
 497
 498   if (it->have_user_data) {
 499     memset (&copy->user_data, 0, sizeof (copy->user_data));
 500     g_value_init (&copy->user_data, G_VALUE_TYPE (&it->user_data));
 501     g_value_copy (&it->user_data, &copy->user_data);
 502   }
 503 }
 504
 505 static void
 506 filter_resync (GstIteratorFilter * it)
 507 {
 508   gst_iterator_resync (it->slave);
 509 }
 510
 511 static void
 512 filter_free (GstIteratorFilter * it)
 513 {
 514   if (it->have_user_data)
 515     g_value_unset (&it->user_data);
 516   gst_iterator_free (it->slave);
 517 }
 518
 519 /**
 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
 524  *
 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.
 530  *
 531  * When this iterator is freed, @it will also be freed.
 532  *
 533  * Returns: (transfer full): a new #GstIterator.
 534  *
 535  * MT safe.
 536  */
 537 GstIterator *
 538 gst_iterator_filter (GstIterator * it, GCompareFunc func,
 539     const GValue * user_data)
 540 {
 541   GstIteratorFilter *result;
 542
 543   g_return_val_if_fail (it != NULL, NULL);
 544   g_return_val_if_fail (func != NULL, NULL);
 545
 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);
 553
 554   it->lock = NULL;
 555   result->func = func;
 556   if (user_data) {
 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;
 560   } else {
 561     result->have_user_data = FALSE;
 562   }
 563   result->slave = it;
 564
 565   return GST_ITERATOR (result);
 566 }
 567
 568 /**
 569  * gst_iterator_fold:
 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
 574  *
 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
 578  * @ret.
 579  *
 580  * This procedure can be used (and is used internally) to implement the
 581  * gst_iterator_foreach() and gst_iterator_find_custom() operations.
 582  *
 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
 587  * appropriate.
 588  *
 589  * The iterator will not be freed.
 590  *
 591  * Returns: A #GstIteratorResult, as described above.
 592  *
 593  * MT safe.
 594  */
 595 GstIteratorResult
 596 gst_iterator_fold (GstIterator * it, GstIteratorFoldFunction func,
 597     GValue * ret, gpointer user_data)
 598 {
 599   GValue item = { 0, };
 600   GstIteratorResult result;
 601
 602   while (1) {
 603     result = gst_iterator_next (it, &item);
 604     switch (result) {
 605       case GST_ITERATOR_OK:
 606         if (!func (&item, ret, user_data))
 607           goto fold_done;
 608
 609         g_value_reset (&item);
 610         break;
 611       case GST_ITERATOR_RESYNC:
 612       case GST_ITERATOR_ERROR:
 613         goto fold_done;
 614       case GST_ITERATOR_DONE:
 615         goto fold_done;
 616     }
 617   }
 618
 619 fold_done:
 620   g_value_unset (&item);
 621
 622   return result;
 623 }
 624
 625 typedef struct
 626 {
 627   GstIteratorForeachFunction func;
 628   gpointer user_data;
 629 } ForeachFoldData;
 630
 631 static gboolean
 632 foreach_fold_func (const GValue * item, GValue * unused, ForeachFoldData * data)
 633 {
 634   data->func (item, data->user_data);
 635   return TRUE;
 636 }
 637
 638 /**
 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
 643  *
 644  * Iterate over all element of @it and call the given function @func for
 645  * each element.
 646  *
 647  * Returns: the result call to gst_iterator_fold(). The iterator will not be
 648  * freed.
 649  *
 650  * MT safe.
 651  */
 652 GstIteratorResult
 653 gst_iterator_foreach (GstIterator * it, GstIteratorForeachFunction func,
 654     gpointer user_data)
 655 {
 656   ForeachFoldData data;
 657
 658   data.func = func;
 659   data.user_data = user_data;
 660
 661   return gst_iterator_fold (it, (GstIteratorFoldFunction) foreach_fold_func,
 662       NULL, &data);
 663 }
 664
 665 typedef struct
 666 {
 667   GCompareFunc func;
 668   gpointer user_data;
 669   gboolean found;
 670 } FindCustomFoldData;
 671
 672 static gboolean
 673 find_custom_fold_func (const GValue * item, GValue * ret,
 674     FindCustomFoldData * data)
 675 {
 676   if (data->func (item, data->user_data) == 0) {
 677     data->found = TRUE;
 678     g_value_copy (item, ret);
 679     return FALSE;
 680   } else {
 681     return TRUE;
 682   }
 683 }
 684
 685 /**
 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
 691  *
 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.
 697  *
 698  * The iterator will not be freed.
 699  *
 700  * This function will return FALSE if an error happened to the iterator
 701  * or if the element wasn't found.
 702  *
 703  * Returns: Returns TRUE if the element was found, else FALSE.
 704  *
 705  * MT safe.
 706  */
 707 gboolean
 708 gst_iterator_find_custom (GstIterator * it, GCompareFunc func,
 709     GValue * elem, gpointer user_data)
 710 {
 711   GstIteratorResult res;
 712   FindCustomFoldData data;
 713
 714   g_return_val_if_fail (G_VALUE_TYPE (elem) == G_TYPE_INVALID
 715       || G_VALUE_HOLDS (elem, it->type), GST_ITERATOR_ERROR);
 716
 717   if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
 718     g_value_init (elem, it->type);
 719
 720   data.func = func;
 721   data.user_data = user_data;
 722   data.found = FALSE;
 723
 724   do {
 725     res =
 726         gst_iterator_fold (it, (GstIteratorFoldFunction) find_custom_fold_func,
 727         elem, &data);
 728     if (res == GST_ITERATOR_RESYNC)
 729       gst_iterator_resync (it);
 730   } while (res == GST_ITERATOR_RESYNC);
 731
 732   if (!data.found)
 733     g_value_unset (elem);
 734
 735   return data.found;
 736 }
 737
 738 typedef struct
 739 {
 740   GstIterator parent;
 741   GValue object;
 742   gboolean visited;
 743   gboolean empty;
 744 } GstSingleObjectIterator;
 745
 746 static guint32 _single_object_dummy_cookie = 0;
 747
 748 static void
 749 gst_single_object_iterator_copy (const GstSingleObjectIterator * it,
 750     GstSingleObjectIterator * copy)
 751 {
 752   if (!it->empty) {
 753     memset (&copy->object, 0, sizeof (copy->object));
 754     g_value_init (&copy->object, it->parent.type);
 755     g_value_copy (&it->object, &copy->object);
 756   }
 757 }
 758
 759 static GstIteratorResult
 760 gst_single_object_iterator_next (GstSingleObjectIterator * it, GValue * result)
 761 {
 762   if (it->visited || it->empty)
 763     return GST_ITERATOR_DONE;
 764
 765   g_value_copy (&it->object, result);
 766   it->visited = TRUE;
 767
 768   return GST_ITERATOR_OK;
 769 }
 770
 771 static void
 772 gst_single_object_iterator_resync (GstSingleObjectIterator * it)
 773 {
 774   it->visited = FALSE;
 775 }
 776
 777 static void
 778 gst_single_object_iterator_free (GstSingleObjectIterator * it)
 779 {
 780   if (!it->empty)
 781     g_value_unset (&it->object);
 782 }
 783
 784 /**
 785  * gst_iterator_new_single:
 786  * @type: #GType of the passed object
 787  * @object: object that this iterator should return
 788  *
 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.
 793  *
 794  * Returns: the new #GstIterator for @object.
 795  *
 796  * Since: 0.10.25
 797  */
 798 GstIterator *
 799 gst_iterator_new_single (GType type, const GValue * object)
 800 {
 801   GstSingleObjectIterator *result;
 802
 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);
 811
 812   if (object) {
 813     g_value_init (&result->object, type);
 814     g_value_copy (object, &result->object);
 815     result->empty = FALSE;
 816   } else {
 817     result->empty = TRUE;
 818   }
 819   result->visited = FALSE;
 820
 821   return GST_ITERATOR (result);
 822 }