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