GstIterator

## GstIterator GstIterator — Object to retrieve multiple elements in a threadsafe way. |

## Synopsis

    #include <gst/gst.h>

    struct              GstIterator;
    enum                GstIteratorItem;
    enum                GstIteratorResult;
    void                (*GstIteratorDisposeFunction)       (gpointer owner);
    GstIteratorResult   (*GstIteratorNextFunction)          (GstIterator *it,
                                                             gpointer *result);
    GstIteratorItem     (*GstIteratorItemFunction)          (GstIterator *it,
                                                             gpointer item);
    void                (*GstIteratorResyncFunction)        (GstIterator *it);
    void                (*GstIteratorFreeFunction)          (GstIterator *it);
    gboolean            (*GstIteratorFoldFunction)          (gpointer item,
                                                             GValue *ret,
                                                             gpointer user_data);
    gpointer            (*GstCopyFunction)                  (gpointer object);
    #define             GST_ITERATOR                        (it)
    #define             GST_ITERATOR_LOCK                   (it)
    #define             GST_ITERATOR_COOKIE                 (it)
    #define             GST_ITERATOR_ORIG_COOKIE            (it)
    GstIterator *       gst_iterator_new                    (guint size,
                                                             GType type,
                                                             GMutex *lock,
                                                             guint32 *master_cookie,
                                                             GstIteratorNextFunction next,
                                                             GstIteratorItemFunction item,
                                                             GstIteratorResyncFunction resync,
                                                             GstIteratorFreeFunction free);
    GstIterator *       gst_iterator_new_list               (GType type,
                                                             GMutex *lock,
                                                             guint32 *master_cookie,
                                                             GList **list,
                                                             gpointer owner,
                                                             GstIteratorItemFunction item,
                                                             GstIteratorDisposeFunction free);
    GstIterator *       gst_iterator_new_single             (GType type,
                                                             gpointer object,
                                                             GstCopyFunction copy,
                                                             GFreeFunc free);
    GstIteratorResult   gst_iterator_next                   (GstIterator *it,
                                                             gpointer *elem);
    void                gst_iterator_resync                 (GstIterator *it);
    void                gst_iterator_free                   (GstIterator *it);
    void                gst_iterator_push                   (GstIterator *it,
                                                             GstIterator *other);
    GstIterator *       gst_iterator_filter                 (GstIterator *it,
                                                             GCompareFunc func,
                                                             gpointer user_data);
    GstIteratorResult   gst_iterator_fold                   (GstIterator *it,
                                                             GstIteratorFoldFunction func,
                                                             GValue *ret,
                                                             gpointer user_data);
    GstIteratorResult   gst_iterator_foreach                (GstIterator *it,
                                                             GFunc func,
                                                             gpointer user_data);
    gpointer            gst_iterator_find_custom            (GstIterator *it,
                                                             GCompareFunc func,
                                                             gpointer user_data);

## Description

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.

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.

The basic use pattern of an iterator is as follows:

Example 13. Using an iterator

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    it = _get_iterator(object);
    done = FALSE;
    while (!done) {
      switch (gst_iterator_next (it, &item)) {
        case GST_ITERATOR_OK:
          ... use/change item here...
          gst_object_unref (item);
          break;
        case GST_ITERATOR_RESYNC:
          ...rollback changes to items...
          gst_iterator_resync (it);
          break;
        case GST_ITERATOR_ERROR:
          ...wrong parameters were given...
          done = TRUE;
          break;
        case GST_ITERATOR_DONE:
          done = TRUE;
          break;
      }
    }
    gst_iterator_free (it);

Last reviewed on 2009-06-16 (0.10.24)

## Details

### struct GstIterator

    struct GstIterator {
    };

GstIterator base structure. The values of this structure are protected for subclasses, use the methods to use the GstIterator.

### enum GstIteratorItem

    typedef enum {
      GST_ITERATOR_ITEM_SKIP = 0,
      GST_ITERATOR_ITEM_PASS = 1,
      GST_ITERATOR_ITEM_END		= 2
    } GstIteratorItem;

The result of a GstIteratorItemFunction.

`GST_ITERATOR_ITEM_SKIP` | Skip this item
`GST_ITERATOR_ITEM_PASS` | Return item
`GST_ITERATOR_ITEM_END` | Stop after this item.

### enum GstIteratorResult

    typedef enum {
      GST_ITERATOR_DONE = 0,
      GST_ITERATOR_OK = 1,
      GST_ITERATOR_RESYNC = 2,
      GST_ITERATOR_ERROR = 3
    } GstIteratorResult;

The result of `gst_iterator_next()`.

`GST_ITERATOR_DONE` | No more items in the iterator
`GST_ITERATOR_OK` | An item was retrieved
`GST_ITERATOR_RESYNC` | Datastructure changed while iterating
`GST_ITERATOR_ERROR` | An error happened

### GstIteratorDisposeFunction ()

    void                (*GstIteratorDisposeFunction)       (gpointer owner);

The function that will be called when a GList iterator is freed. The owner of the GList iterator can then clean up its resources.

`owner` : | the owner of the iterator

### GstIteratorNextFunction ()

    GstIteratorResult   (*GstIteratorNextFunction)          (GstIterator *it,
                                                             gpointer *result);

The function that will be called when the next element of the iterator should be retrieved.

Implementors of a GstIterator should implement this function and pass it to the constructor of the custom iterator. The function will be called with the iterator lock held.

`it` : | the iterator
`result` : | a pointer to hold the next item
Returns : | the result of the operation.

### GstIteratorItemFunction ()

    GstIteratorItem     (*GstIteratorItemFunction)          (GstIterator *it,
                                                             gpointer item);

The function that will be called after the next item of the iterator has been retrieved. This function will typically increase the refcount of the item or make a copy.

Implementors of a GstIterator should implement this function and pass it to the constructor of the custom iterator. The function will be called with the iterator lock held.

`it` : | the iterator
`item` : | the item being retrieved.
Returns : | the result of the operation.

### GstIteratorResyncFunction ()

    void                (*GstIteratorResyncFunction)        (GstIterator *it);

This function will be called whenever a concurrent update happened to the iterated datastructure. The implementor of the iterator should restart the iterator from the beginning and clean up any state it might have.

Implementors of a GstIterator should implement this function and pass it to the constructor of the custom iterator. The function will be called with the iterator lock held.

`it` : | the iterator

### GstIteratorFreeFunction ()

    void                (*GstIteratorFreeFunction)          (GstIterator *it);

This function will be called when the iterator is freed.

Implementors of a GstIterator should implement this function and pass it to the constructor of the custom iterator. The function will be called with the iterator lock held.

`it` : | the iterator

### GstIteratorFoldFunction ()

    gboolean            (*GstIteratorFoldFunction)          (gpointer item,
                                                             GValue *ret,
                                                             gpointer user_data);

A function to be passed to `gst_iterator_fold()`.

`item` : | the item to fold
`ret` : | a GValue collecting the result
`user_data` : | data passed to `gst_iterator_fold()`
Returns : | TRUE if the fold should continue, FALSE if it should stop.

### GstCopyFunction ()

    gpointer            (*GstCopyFunction)                  (gpointer object);

A function to create a copy of some object or increase its reference count.

`object` : | The object to copy
Returns : | a copy of the object or the same object with increased reference count

Since 0.10.25

### GST_ITERATOR()

    #define GST_ITERATOR(it)		((GstIterator*)(it))

Macro to cast to a GstIterator

`it` : | the GstIterator value

### GST_ITERATOR_LOCK()

    #define GST_ITERATOR_LOCK(it)		(GST_ITERATOR(it)->lock)

Macro to get the lock protecting the datastructure being iterated.

`it` : | the GstIterator to get the lock of

### GST_ITERATOR_COOKIE()

    #define GST_ITERATOR_COOKIE(it)		(GST_ITERATOR(it)->cookie)

Macro to get the cookie of a GstIterator. The cookie of the iterator is the value of the master cookie when the iterator was created. Whenever the iterator is iterated, the value is compared to the value of the master cookie. If they are different, a concurrent modification happened to the iterator and a resync is needed.

`it` : | the GstIterator to get the cookie of

### GST_ITERATOR_ORIG_COOKIE()

    #define GST_ITERATOR_ORIG_COOKIE(it) (GST_ITERATOR(it)->master_cookie)

Macro to get a pointer to where the master cookie is stored. The master cookie protects the structure being iterated and gets updated whenever the datastructure changes.

`it` : | the GstIterator to get the master cookie of

### gst_iterator_new ()

    GstIterator *       gst_iterator_new                    (guint size,
                                                             GType type,
                                                             GMutex *lock,
                                                             guint32 *master_cookie,
                                                             GstIteratorNextFunction next,
                                                             GstIteratorItemFunction item,
                                                             GstIteratorResyncFunction resync,
                                                             GstIteratorFreeFunction free);

Create a new iterator. This function is mainly used for objects implementing the next/resync/free function to iterate a data structure.

For each item retrieved, the `item` function is called with the lock held. The `free` function is called when the iterator is freed.

`size` : | the size of the iterator structure
`type` : | GType of children
`lock` : | pointer to a GMutex.
`master_cookie` : | pointer to a guint32 that is changed when the items in the iterator changed.
`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
Returns : | the new GstIterator. MT safe.

### gst_iterator_new_list ()

    GstIterator *       gst_iterator_new_list               (GType type,
                                                             GMutex *lock,
                                                             guint32 *master_cookie,
                                                             GList **list,
                                                             gpointer owner,
                                                             GstIteratorItemFunction item,
                                                             GstIteratorDisposeFunction free);

Create a new iterator designed for iterating `list`.

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.

The `item` function usualy makes sure that the item remains alive while `lock` is released and the application is using the item. The application is responsible for freeing/unreffing the item after usage as explained in `gst_iterator_next()`.

When a concurrent update to the list is performed, usually by `owner` while holding `lock`, `master_cookie` will be updated. The iterator implementation will notice the update of the cookie and will return `GST_ITERATOR_RESYNC` to the user of the iterator in the next call to `gst_iterator_next()`.

`owner` will be passed to the `free` function when the iterator is freed.

`type` : | GType of elements
`lock` : | pointer to a GMutex protecting the list.
`master_cookie` : | pointer to a guint32 that is incremented when the list is changed.
`list` : | pointer to the list
`owner` : | object owning the list
`item` : | function to call for each item
`free` : | function to call when the iterator is freed
Returns : | the new GstIterator for `list`. MT safe.

### gst_iterator_new_single ()

    GstIterator *       gst_iterator_new_single             (GType type,
                                                             gpointer object,
                                                             GstCopyFunction copy,
                                                             GFreeFunc free);

This GstIterator is a convenient iterator for the common case where a GstIterator needs to be returned but only a single object has to be considered. This happens often for the GstPadIterIntLinkFunction.

`type` : | GType of the passed object
`object` : | object that this iterator should return
`copy` : | Function that returns a copy of `object` or increases its refcount
`free` : | Function to be called for freeing `object`
Returns : | the new GstIterator for `object`.

Since 0.10.25

### gst_iterator_next ()

    GstIteratorResult   gst_iterator_next                   (GstIterator *it,
                                                             gpointer *elem);

Get the next item from the iterator in `elem`.

Only when this function returns `GST_ITERATOR_OK`, `elem` will contain a valid value. For iterators that return refcounted objects, the returned object will have its refcount increased and should therefore be unreffed after usage.

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.

`it` : | The GstIterator to iterate
`elem` : | pointer to hold next element
Returns : | The result of the iteration. Unref `elem` after usage if this is a refcounted object. MT safe.

### gst_iterator_resync ()

    void                gst_iterator_resync                 (GstIterator *it);

Resync the iterator. this function is mostly called after `gst_iterator_next()` returned `GST_ITERATOR_RESYNC`.

When an iterator was pushed on `it`, it will automatically be popped again with this function.

MT safe.

`it` : | The GstIterator to resync

### gst_iterator_free ()

    void                gst_iterator_free                   (GstIterator *it);

Free the iterator.

MT safe.

`it` : | The GstIterator to free

### gst_iterator_push ()

    void                gst_iterator_push                   (GstIterator *it,
                                                             GstIterator *other);

Pushes `other` iterator onto `it`. All calls performed on `it` are forwarded to `other`. If `other` returns `GST_ITERATOR_DONE`, it is 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.

When `gst_iterator_resync()` is called on `it`, `other` will automatically be popped.

MT safe.

`it` : | The GstIterator to use
`other` : | The GstIterator to push

### gst_iterator_filter ()

    GstIterator *       gst_iterator_filter                 (GstIterator *it,
                                                             GCompareFunc func,
                                                             gpointer user_data);

Create a new iterator from an existing iterator. The new iterator will only return those elements that match the given compare function `func`. `func` should return 0 for elements that should be included in the iterator.

When this iterator is freed, `it` will also be freed.

`it` : | The GstIterator to filter
`func` : | the compare function to select elements. [scope call]
`user_data` : | user data passed to the compare function. [closure]
Returns : | a new GstIterator. MT safe. [transfer full]

### gst_iterator_fold ()

    GstIteratorResult   gst_iterator_fold                   (GstIterator *it,
                                                             GstIteratorFoldFunction func,
                                                             GValue *ret,
                                                             gpointer user_data);

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 of this procedure is to accumulate the results of operating on the objects in `ret`. If object is a refcounted object its refcount will be increased before `func` is called, and it should be unrefed after use in `func`.

This procedure can be used (and is used internally) to implement the `gst_iterator_foreach()` and `gst_iterator_find_custom()` operations.

The fold will proceed as long as `func` returns TRUE. When the iterator has no 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 appropriate.

The iterator will not be freed.

`it` : | The GstIterator to fold over
`func` : | the fold function. [scope call]
`ret` : | the seed value passed to the fold function
`user_data` : | user data passed to the fold function. [closure]
Returns : | A GstIteratorResult, as described above. MT safe.

### gst_iterator_foreach ()

    GstIteratorResult   gst_iterator_foreach                (GstIterator *it,
                                                             GFunc func,
                                                             gpointer user_data);

Iterate over all element of `it` and call the given function `func` for each element. As in `gst_iterator_fold()`, the refcount of a refcounted object will be increased before `func` is called, and should be unrefed after use.

`it` : | The GstIterator to iterate
`func` : | the function to call for each element. [scope call]
`user_data` : | user data passed to the function. [closure]
Returns : | the result call to `gst_iterator_fold()`. The iterator will not be freed. MT safe.

### gst_iterator_find_custom ()

    gpointer            gst_iterator_find_custom            (GstIterator *it,
                                                             GCompareFunc func,
                                                             gpointer user_data);

Find the first element in `it` that matches the compare function `func`. `func` should return 0 when the element is found. As in `gst_iterator_fold()`, the refcount of a refcounted object will be increased before `func` is called, and should be unrefed after use in `func` unless it is the matching element.

The iterator will not be freed.

This function will return NULL if an error happened to the iterator.

`it` : | The GstIterator to iterate
`func` : | the compare function to use. [scope call]
`user_data` : | user data passed to the compare function. [closure]
Returns : | The element in the iterator that matches the compare function or NULL when no element matched. MT safe. [transfer full]

## See Also

GstElement, GstBin