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 }