gstiterator.c 21.7 KB
Newer Older
1 2
/* GStreamer
 * Copyright (C) 2004 Wim Taymans <wim@fluendo.com>
3
 * Copyright (C) 2011 Sebastian Dröge <sebastian.droege@collabora.co.uk>
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
 *
 * gstiterator.h: Base class for iterating datastructures.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
22

Wim Taymans's avatar
Wim Taymans committed
23 24 25 26 27 28 29 30 31 32 33
/**
 * SECTION:gstiterator
 * @short_description: Object to retrieve multiple elements in a threadsafe
 * way.
 * @see_also: #GstElement, #GstBin
 *
 * A GstIterator is used to retrieve multiple objects from another object in
 * a threadsafe way.
 *
 * Various GStreamer objects provide access to their internal structures using
 * an iterator.
34
 *
35 36 37 38
 * In general, whenever calling a GstIterator function results in your code
 * receiving a refcounted object, the refcount for that object will have been
 * increased.  Your code is responsible for unrefing that object after use.
 *
39 40 41 42 43 44 45 46 47 48 49
 * The basic use pattern of an iterator is as follows:
 *
 * <example>
 * <title>Using an iterator</title>
 *   <programlisting>
 *    it = _get_iterator(object);
 *    done = FALSE;
 *    while (!done) {
 *      switch (gst_iterator_next (it, &amp;item)) {
 *        case GST_ITERATOR_OK:
 *          ... use/change item here...
50
 *          g_value_reset (&amp;item);
51 52 53 54 55
 *          break;
 *        case GST_ITERATOR_RESYNC:
 *          ...rollback changes to items...
 *          gst_iterator_resync (it);
 *          break;
56
 *        case GST_ITERATOR_ERROR:
57
 *          ...wrong parameters were given...
58 59
 *          done = TRUE;
 *          break;
60 61 62 63 64
 *        case GST_ITERATOR_DONE:
 *          done = TRUE;
 *          break;
 *      }
 *    }
65
 *    g_value_unset (&amp;item);
66 67 68
 *    gst_iterator_free (it);
 *   </programlisting>
 * </example>
Wim Taymans's avatar
Wim Taymans committed
69
 *
70
 * Last reviewed on 2009-06-16 (0.10.24)
Wim Taymans's avatar
Wim Taymans committed
71
 */
72 73 74 75

#include "gst_private.h"
#include <gst/gstiterator.h>

Wim Taymans's avatar
Wim Taymans committed
76 77 78 79 80 81 82 83
/**
 * gst_iterator_copy:
 * @it: a #GstIterator
 *
 * Copy the iterator and its state.
 *
 * Returns: a new copy of @it.
 */
84 85
GstIterator *
gst_iterator_copy (const GstIterator * it)
86
{
87 88 89 90 91 92 93
  GstIterator *copy;

  copy = g_slice_copy (it->size, it);
  if (it->copy)
    it->copy (it, copy);

  return copy;
94 95
}

96 97
G_DEFINE_BOXED_TYPE (GstIterator, gst_iterator,
    (GBoxedCopyFunc) gst_iterator_copy, (GBoxedFreeFunc) gst_iterator_free);
98

99 100
static void
gst_iterator_init (GstIterator * it,
101
    guint size,
102
    GType type,
103 104
    GMutex * lock,
    guint32 * master_cookie,
105
    GstIteratorCopyFunction copy,
106 107 108 109
    GstIteratorNextFunction next,
    GstIteratorItemFunction item,
    GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
{
110
  it->size = size;
111
  it->type = type;
112 113 114
  it->lock = lock;
  it->master_cookie = master_cookie;
  it->cookie = *master_cookie;
115
  it->copy = copy;
116 117 118 119 120 121 122 123
  it->next = next;
  it->item = item;
  it->resync = resync;
  it->free = free;
  it->pushed = NULL;
}

/**
124
 * gst_iterator_new: (skip)
125
 * @size: the size of the iterator structure
126
 * @type: #GType of children
127
 * @lock: pointer to a #GMutex.
128 129
 * @master_cookie: pointer to a guint32 that is changed when the items in the
 *    iterator changed.
130
 * @copy: copy function
131 132 133 134 135 136 137
 * @next: function to get next item
 * @item: function to call on each item retrieved
 * @resync: function to resync the iterator
 * @free: function to free the iterator
 *
 * Create a new iterator. This function is mainly used for objects
 * implementing the next/resync/free function to iterate a data structure.
138 139 140
 *
 * For each item retrieved, the @item function is called with the lock
 * held. The @free function is called when the iterator is freed.
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
141
 *
142 143 144 145 146 147
 * Returns: the new #GstIterator.
 *
 * MT safe.
 */
GstIterator *
gst_iterator_new (guint size,
148
    GType type,
149 150
    GMutex * lock,
    guint32 * master_cookie,
151
    GstIteratorCopyFunction copy,
152 153 154 155 156 157 158
    GstIteratorNextFunction next,
    GstIteratorItemFunction item,
    GstIteratorResyncFunction resync, GstIteratorFreeFunction free)
{
  GstIterator *result;

  g_return_val_if_fail (size >= sizeof (GstIterator), NULL);
159
  g_return_val_if_fail (g_type_qname (type) != 0, NULL);
160 161 162 163 164
  g_return_val_if_fail (master_cookie != NULL, NULL);
  g_return_val_if_fail (next != NULL, NULL);
  g_return_val_if_fail (resync != NULL, NULL);
  g_return_val_if_fail (free != NULL, NULL);

165 166
  result = g_slice_alloc0 (size);
  gst_iterator_init (result, size, type, lock, master_cookie, copy, next, item,
167
      resync, free);
168 169 170 171 172 173 174 175 176 177

  return result;
}

/*
 * list iterator
 */
typedef struct _GstListIterator
{
  GstIterator iterator;
178
  GObject *owner;
179 180
  GList **orig;
  GList *list;                  /* pointer in list */
181 182

  void (*set_value) (GValue * value, gpointer item);
183 184
} GstListIterator;

185 186 187 188 189 190 191
static void
gst_list_iterator_copy (const GstListIterator * it, GstListIterator * copy)
{
  if (copy->owner)
    g_object_ref (copy->owner);
}

192
static GstIteratorResult
193
gst_list_iterator_next (GstListIterator * it, GValue * elem)
194
{
195 196
  gpointer data;

197 198 199
  if (it->list == NULL)
    return GST_ITERATOR_DONE;

200
  data = it->list->data;
201 202
  it->list = g_list_next (it->list);

203 204
  it->set_value (elem, data);

205 206 207 208 209 210 211 212 213 214 215 216
  return GST_ITERATOR_OK;
}

static void
gst_list_iterator_resync (GstListIterator * it)
{
  it->list = *it->orig;
}

static void
gst_list_iterator_free (GstListIterator * it)
{
217 218
  if (it->owner)
    g_object_unref (it->owner);
219 220 221
}

/**
222
 * gst_iterator_new_list: (skip)
223
 * @type: #GType of elements
224
 * @lock: pointer to a #GMutex protecting the list.
225 226
 * @master_cookie: pointer to a guint32 that is incremented when the list
 *     is changed.
227 228
 * @list: pointer to the list
 * @owner: object owning the list
229
 * @item: function to call on each item retrieved
230
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
231 232
 * Create a new iterator designed for iterating @list.
 *
233 234 235 236 237 238 239 240
 * The list you iterate is usually part of a data structure @owner and is
 * protected with @lock. 
 *
 * The iterator will use @lock to retrieve the next item of the list and it
 * will then call the @item function before releasing @lock again.
 *
 * When a concurrent update to the list is performed, usually by @owner while
 * 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 243
 * the user of the iterator in the next call to gst_iterator_next().
 *
244 245 246 247 248
 * Returns: the new #GstIterator for @list.
 *
 * MT safe.
 */
GstIterator *
249
gst_iterator_new_list (GType type,
250 251
    GMutex * lock, guint32 * master_cookie, GList ** list, GObject * owner,
    GstIteratorItemFunction item)
252 253
{
  GstListIterator *result;
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268
  gpointer set_value;

  if (g_type_is_a (type, G_TYPE_OBJECT)) {
    set_value = g_value_set_object;
  } else if (g_type_is_a (type, G_TYPE_BOXED)) {
    set_value = g_value_set_boxed;
  } else if (g_type_is_a (type, G_TYPE_POINTER)) {
    set_value = g_value_set_pointer;
  } else if (g_type_is_a (type, G_TYPE_STRING)) {
    set_value = g_value_set_string;
  } else {
    g_critical ("List iterators can only be created for lists containing "
        "instances of GObject, boxed types, pointer types and strings");
    return NULL;
  }
269 270 271

  /* no need to lock, nothing can change here */
  result = (GstListIterator *) gst_iterator_new (sizeof (GstListIterator),
272
      type,
273 274
      lock,
      master_cookie,
275
      (GstIteratorCopyFunction) gst_list_iterator_copy,
276 277 278 279 280
      (GstIteratorNextFunction) gst_list_iterator_next,
      (GstIteratorItemFunction) item,
      (GstIteratorResyncFunction) gst_list_iterator_resync,
      (GstIteratorFreeFunction) gst_list_iterator_free);

281
  result->owner = owner ? g_object_ref (owner) : NULL;
282 283
  result->orig = list;
  result->list = *list;
284
  result->set_value = set_value;
285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300

  return GST_ITERATOR (result);
}

static void
gst_iterator_pop (GstIterator * it)
{
  if (it->pushed) {
    gst_iterator_free (it->pushed);
    it->pushed = NULL;
  }
}

/**
 * gst_iterator_next:
 * @it: The #GstIterator to iterate
301
 * @elem: (out caller-allocates): pointer to hold next element
302
 *
303 304 305
 * Get the next item from the iterator in @elem. 
 *
 * Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid
306 307 308 309
 * value. @elem must have been initialized to the type of the iterator or
 * initialized to zeroes with g_value_unset(). The caller is responsible for
 * unsetting or resetting @elem with g_value_unset() or g_value_reset()
 * after usage.
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
310
 *
311 312 313 314 315 316 317 318 319
 * When this function returns %GST_ITERATOR_DONE, no more elements can be
 * retrieved from @it.
 *
 * A return value of %GST_ITERATOR_RESYNC indicates that the element list was
 * concurrently updated. The user of @it should call gst_iterator_resync() to
 * get the newly updated list. 
 *
 * A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error.
 *
320
 * Returns: The result of the iteration. Unset @elem after usage.
321 322 323 324
 *
 * MT safe.
 */
GstIteratorResult
325
gst_iterator_next (GstIterator * it, GValue * elem)
326 327 328 329 330
{
  GstIteratorResult result;

  g_return_val_if_fail (it != NULL, GST_ITERATOR_ERROR);
  g_return_val_if_fail (elem != NULL, GST_ITERATOR_ERROR);
331 332 333 334 335
  g_return_val_if_fail (G_VALUE_TYPE (elem) == G_TYPE_INVALID
      || G_VALUE_HOLDS (elem, it->type), GST_ITERATOR_ERROR);

  if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
    g_value_init (elem, it->type);
336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360

restart:
  if (it->pushed) {
    result = gst_iterator_next (it->pushed, elem);
    if (result == GST_ITERATOR_DONE) {
      /* we are done with this iterator, pop it and
       * fallthrough iterating the main iterator again. */
      gst_iterator_pop (it);
    } else {
      return result;
    }
  }

  if (G_LIKELY (it->lock))
    g_mutex_lock (it->lock);

  if (G_UNLIKELY (*it->master_cookie != it->cookie)) {
    result = GST_ITERATOR_RESYNC;
    goto done;
  }

  result = it->next (it, elem);
  if (result == GST_ITERATOR_OK && it->item) {
    GstIteratorItem itemres;

361
    itemres = it->item (it, elem);
362 363 364 365
    switch (itemres) {
      case GST_ITERATOR_ITEM_SKIP:
        if (G_LIKELY (it->lock))
          g_mutex_unlock (it->lock);
366
        g_value_reset (elem);
367 368 369
        goto restart;
      case GST_ITERATOR_ITEM_END:
        result = GST_ITERATOR_DONE;
370
        g_value_reset (elem);
371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388
        break;
      case GST_ITERATOR_ITEM_PASS:
        break;
    }
  }

done:
  if (G_LIKELY (it->lock))
    g_mutex_unlock (it->lock);

  return result;
}

/**
 * gst_iterator_resync:
 * @it: The #GstIterator to resync
 *
 * Resync the iterator. this function is mostly called
389
 * after gst_iterator_next() returned %GST_ITERATOR_RESYNC.
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
390
 *
391 392 393
 * When an iterator was pushed on @it, it will automatically be popped again
 * with this function.
 *
394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414
 * MT safe.
 */
void
gst_iterator_resync (GstIterator * it)
{
  g_return_if_fail (it != NULL);

  gst_iterator_pop (it);

  if (G_LIKELY (it->lock))
    g_mutex_lock (it->lock);
  it->resync (it);
  it->cookie = *it->master_cookie;
  if (G_LIKELY (it->lock))
    g_mutex_unlock (it->lock);
}

/**
 * gst_iterator_free:
 * @it: The #GstIterator to free
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
415 416
 * Free the iterator.
 *
417 418 419 420 421 422 423 424 425 426
 * MT safe.
 */
void
gst_iterator_free (GstIterator * it)
{
  g_return_if_fail (it != NULL);

  gst_iterator_pop (it);

  it->free (it);
427

Johan Dahlin's avatar
Johan Dahlin committed
428
  g_slice_free1 (it->size, it);
429 430 431 432 433 434 435 436
}

/**
 * gst_iterator_push:
 * @it: The #GstIterator to use
 * @other: The #GstIterator to push
 *
 * Pushes @other iterator onto @it. All calls performed on @it are
437
 * forwarded to @other. If @other returns %GST_ITERATOR_DONE, it is
438 439 440 441
 * popped again and calls are handled by @it again.
 *
 * This function is mainly used by objects implementing the iterator
 * next function to recurse into substructures.
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
442
 *
443 444 445
 * When gst_iterator_resync() is called on @it, @other will automatically be
 * popped.
 *
446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462
 * MT safe.
 */
void
gst_iterator_push (GstIterator * it, GstIterator * other)
{
  g_return_if_fail (it != NULL);
  g_return_if_fail (other != NULL);

  it->pushed = other;
}

typedef struct _GstIteratorFilter
{
  GstIterator iterator;
  GstIterator *slave;

  GCompareFunc func;
463 464
  GValue user_data;
  gboolean have_user_data;
465 466 467
} GstIteratorFilter;

static GstIteratorResult
468
filter_next (GstIteratorFilter * it, GValue * elem)
469 470 471
{
  GstIteratorResult result = GST_ITERATOR_ERROR;
  gboolean done = FALSE;
472
  GValue item = { 0, };
473 474 475 476 477 478 479

  while (G_LIKELY (!done)) {
    result = gst_iterator_next (it->slave, &item);
    switch (result) {
      case GST_ITERATOR_OK:
        if (G_LIKELY (GST_ITERATOR (it)->lock))
          g_mutex_unlock (GST_ITERATOR (it)->lock);
480 481
        if (it->func (&item, &it->user_data) == 0) {
          g_value_copy (&item, elem);
482 483
          done = TRUE;
        }
484
        g_value_reset (&item);
485 486 487 488 489 490 491 492 493 494 495 496
        if (G_LIKELY (GST_ITERATOR (it)->lock))
          g_mutex_lock (GST_ITERATOR (it)->lock);
        break;
      case GST_ITERATOR_RESYNC:
      case GST_ITERATOR_DONE:
        done = TRUE;
        break;
      default:
        g_assert_not_reached ();
        break;
    }
  }
497
  g_value_unset (&item);
498 499 500 501
  return result;
}

static void
502
filter_copy (const GstIteratorFilter * it, GstIteratorFilter * copy)
503
{
504 505 506 507 508 509 510
  copy->slave = gst_iterator_copy (it->slave);

  if (it->have_user_data) {
    memset (&copy->user_data, 0, sizeof (copy->user_data));
    g_value_init (&copy->user_data, G_VALUE_TYPE (&it->user_data));
    g_value_copy (&it->user_data, &copy->user_data);
  }
511 512 513
}

static void
514
filter_resync (GstIteratorFilter * it)
515
{
516
  gst_iterator_resync (it->slave);
517 518 519 520 521
}

static void
filter_free (GstIteratorFilter * it)
{
522 523
  if (it->have_user_data)
    g_value_unset (&it->user_data);
524 525 526 527 528 529
  gst_iterator_free (it->slave);
}

/**
 * gst_iterator_filter:
 * @it: The #GstIterator to filter
530 531
 * @func: (scope call): the compare function to select elements
 * @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 536 537
 * The first parameter that is passed to @func is the #GValue of the current
 * iterator element and the second parameter is @user_data. @func should
 * return 0 for elements that should be included in the filtered iterator.
538 539 540
 *
 * When this iterator is freed, @it will also be freed.
 *
541
 * Returns: (transfer full): a new #GstIterator.
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
542
 *
543 544 545
 * MT safe.
 */
GstIterator *
546 547
gst_iterator_filter (GstIterator * it, GCompareFunc func,
    const GValue * user_data)
548 549 550 551 552 553 554
{
  GstIteratorFilter *result;

  g_return_val_if_fail (it != NULL, NULL);
  g_return_val_if_fail (func != NULL, NULL);

  result = (GstIteratorFilter *) gst_iterator_new (sizeof (GstIteratorFilter),
555
      it->type, it->lock, it->master_cookie,
556
      (GstIteratorCopyFunction) filter_copy,
557 558 559 560
      (GstIteratorNextFunction) filter_next,
      (GstIteratorItemFunction) NULL,
      (GstIteratorResyncFunction) filter_resync,
      (GstIteratorFreeFunction) filter_free);
561

562 563
  it->lock = NULL;
  result->func = func;
564 565 566 567 568 569 570
  if (user_data) {
    g_value_init (&result->user_data, G_VALUE_TYPE (user_data));
    g_value_copy (user_data, &result->user_data);
    result->have_user_data = TRUE;
  } else {
    result->have_user_data = FALSE;
  }
571 572 573 574 575 576 577
  result->slave = it;

  return GST_ITERATOR (result);
}

/**
 * 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 584
 * Folds @func over the elements of @iter. That is to say, @func will be called
 * 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 589
 * This procedure can be used (and is used internally) to implement the
 * 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 593 594
 * more arguments, %GST_ITERATOR_DONE will be returned. If @func returns FALSE,
 * the fold will stop, and %GST_ITERATOR_OK will be returned. Errors or resyncs
 * will cause fold to return %GST_ITERATOR_ERROR or %GST_ITERATOR_RESYNC as
595 596 597 598 599
 * appropriate.
 *
 * The iterator will not be freed.
 *
 * Returns: A #GstIteratorResult, as described above.
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
600
 *
601 602 603
 * MT safe.
 */
GstIteratorResult
604
gst_iterator_fold (GstIterator * it, GstIteratorFoldFunction func,
605 606
    GValue * ret, gpointer user_data)
{
607
  GValue item = { 0, };
608 609 610
  GstIteratorResult result;

  while (1) {
611
    result = gst_iterator_next (it, &item);
612 613
    switch (result) {
      case GST_ITERATOR_OK:
614
        if (!func (&item, ret, user_data))
615
          goto fold_done;
616 617 618

        g_value_reset (&item);
        break;
619 620 621 622 623 624 625 626 627
      case GST_ITERATOR_RESYNC:
      case GST_ITERATOR_ERROR:
        goto fold_done;
      case GST_ITERATOR_DONE:
        goto fold_done;
    }
  }

fold_done:
628 629
  g_value_unset (&item);

630 631 632 633 634
  return result;
}

typedef struct
{
635
  GstIteratorForeachFunction func;
636 637 638 639
  gpointer user_data;
} ForeachFoldData;

static gboolean
640
foreach_fold_func (const GValue * item, GValue * unused, ForeachFoldData * data)
641 642 643 644 645 646 647
{
  data->func (item, data->user_data);
  return TRUE;
}

/**
 * gst_iterator_foreach:
648
 * @it: The #GstIterator to iterate
649 650
 * @func: (scope call): the function to call for each element.
 * @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 656 657 658 659 660
 *
 * Returns: the result call to gst_iterator_fold(). The iterator will not be
 * freed.
 *
 * MT safe.
 */
GstIteratorResult
661 662
gst_iterator_foreach (GstIterator * it, GstIteratorForeachFunction func,
    gpointer user_data)
663 664 665 666 667 668
{
  ForeachFoldData data;

  data.func = func;
  data.user_data = user_data;

669
  return gst_iterator_fold (it, (GstIteratorFoldFunction) foreach_fold_func,
670 671 672 673 674 675 676
      NULL, &data);
}

typedef struct
{
  GCompareFunc func;
  gpointer user_data;
677
  gboolean found;
678 679 680
} FindCustomFoldData;

static gboolean
681 682
find_custom_fold_func (const GValue * item, GValue * ret,
    FindCustomFoldData * data)
683
{
Wim Taymans's avatar
Wim Taymans committed
684
  if (data->func (item, data->user_data) == 0) {
685 686
    data->found = TRUE;
    g_value_copy (item, ret);
687 688 689 690 691 692 693 694 695
    return FALSE;
  } else {
    return TRUE;
  }
}

/**
 * gst_iterator_find_custom:
 * @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 702 703 704
 * @func should return 0 when the element is found. The first parameter
 * to @func will be the current element of the iterator and the
 * second parameter will be @user_data.
 * The result will be stored in @elem if a result is found.
705 706 707
 *
 * The iterator will not be freed.
 *
708 709
 * This function will return FALSE if an error happened to the iterator
 * or if the element wasn't found.
710
 *
711
 * Returns: Returns TRUE if the element was found, else FALSE.
712 713 714
 *
 * MT safe.
 */
715
gboolean
716
gst_iterator_find_custom (GstIterator * it, GCompareFunc func,
717
    GValue * elem, gpointer user_data)
718 719 720 721
{
  GstIteratorResult res;
  FindCustomFoldData data;

722 723 724 725 726 727
  g_return_val_if_fail (G_VALUE_TYPE (elem) == G_TYPE_INVALID
      || G_VALUE_HOLDS (elem, it->type), GST_ITERATOR_ERROR);

  if (G_VALUE_TYPE (elem) == G_TYPE_INVALID)
    g_value_init (elem, it->type);

728 729
  data.func = func;
  data.user_data = user_data;
730
  data.found = FALSE;
731

732 733 734
  do {
    res =
        gst_iterator_fold (it, (GstIteratorFoldFunction) find_custom_fold_func,
735
        elem, &data);
736 737
    if (res == GST_ITERATOR_RESYNC)
      gst_iterator_resync (it);
738
  } while (res == GST_ITERATOR_RESYNC);
739

740 741 742 743
  if (!data.found)
    g_value_unset (elem);

  return data.found;
744
}
745 746 747 748

typedef struct
{
  GstIterator parent;
749
  GValue object;
750
  gboolean visited;
751
  gboolean empty;
752 753 754 755
} GstSingleObjectIterator;

static guint32 _single_object_dummy_cookie = 0;

756 757 758 759 760 761 762 763 764 765 766
static void
gst_single_object_iterator_copy (const GstSingleObjectIterator * it,
    GstSingleObjectIterator * copy)
{
  if (!it->empty) {
    memset (&copy->object, 0, sizeof (copy->object));
    g_value_init (&copy->object, it->parent.type);
    g_value_copy (&it->object, &copy->object);
  }
}

767
static GstIteratorResult
768
gst_single_object_iterator_next (GstSingleObjectIterator * it, GValue * result)
769
{
770
  if (it->visited || it->empty)
771 772
    return GST_ITERATOR_DONE;

773
  g_value_copy (&it->object, result);
774
  it->visited = TRUE;
775

776 777 778 779 780 781 782 783 784 785 786 787
  return GST_ITERATOR_OK;
}

static void
gst_single_object_iterator_resync (GstSingleObjectIterator * it)
{
  it->visited = FALSE;
}

static void
gst_single_object_iterator_free (GstSingleObjectIterator * it)
{
788 789
  if (!it->empty)
    g_value_unset (&it->object);
790 791 792
}

/**
793
 * gst_iterator_new_single:
794 795 796 797 798
 * @type: #GType of the passed object
 * @object: object that this iterator should return
 *
 * This #GstIterator is a convenient iterator for the common
 * case where a #GstIterator needs to be returned but only
799
 * a single object has to be considered. This happens often
800 801
 * for the #GstPadIterIntLinkFunction.
 *
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 810 811 812
{
  GstSingleObjectIterator *result;

  result = (GstSingleObjectIterator *)
      gst_iterator_new (sizeof (GstSingleObjectIterator),
813
      type, NULL, &_single_object_dummy_cookie,
814 815 816
      (GstIteratorCopyFunction) gst_single_object_iterator_copy,
      (GstIteratorNextFunction) gst_single_object_iterator_next,
      (GstIteratorItemFunction) NULL,
817 818 819
      (GstIteratorResyncFunction) gst_single_object_iterator_resync,
      (GstIteratorFreeFunction) gst_single_object_iterator_free);

820 821 822 823 824 825 826
  if (object) {
    g_value_init (&result->object, type);
    g_value_copy (object, &result->object);
    result->empty = FALSE;
  } else {
    result->empty = TRUE;
  }
827 828
  result->visited = FALSE;

829
  return GST_ITERATOR (result);
830
}