GStreamer 1.0 Core Reference Manual: GstIterator

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

## Functions

void | (*GstIteratorCopyFunction) ()
GstIteratorResult | (*GstIteratorNextFunction) ()
GstIteratorItem | (*GstIteratorItemFunction) ()
void | (*GstIteratorResyncFunction) ()
void | (*GstIteratorFreeFunction) ()
void | (*GstIteratorForeachFunction) ()
gboolean | (*GstIteratorFoldFunction) ()
#define | GST_ITERATOR()
#define | GST_ITERATOR_LOCK()
#define | GST_ITERATOR_COOKIE()
#define | GST_ITERATOR_ORIG_COOKIE()
GstIterator * | gst_iterator_new ()
GstIterator * | gst_iterator_new_list ()
GstIterator * | gst_iterator_new_single ()
GstIterator * | gst_iterator_copy ()
void | gst_iterator_free ()
GstIteratorResult | gst_iterator_next ()
void | gst_iterator_resync ()
void | gst_iterator_push ()
GstIterator * | gst_iterator_filter ()
GstIteratorResult | gst_iterator_fold ()
GstIteratorResult | gst_iterator_foreach ()
gboolean | gst_iterator_find_custom ()

## Types and Values

struct | GstIterator
enum | GstIteratorItem
enum | GstIteratorResult

## Object Hierarchy

## Includes

    #include <gst/gst.h>

## 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 unreffing that object after use.

The basic use pattern of an iterator is as follows:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    GstIterator *it = _get_iterator(object);
    done = FALSE;
    while (!done) {
      switch (gst_iterator_next (it, &item)) {
        case GST_ITERATOR_OK:
          ... use/change item here...
          g_value_reset (&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;
      }
    }
    g_value_unset (&item);
    gst_iterator_free (it);

## Functions

### GstIteratorCopyFunction ()

    void
    (*GstIteratorCopyFunction) (const GstIterator *it,
                                GstIterator *copy);

This function will be called when creating a copy of `it` and should create a copy of all custom iterator fields or increase their reference counts.

#### Parameters

it | The original iterator |
copy | The copied iterator |

### GstIteratorNextFunction ()

    GstIteratorResult
    (*GstIteratorNextFunction) (GstIterator *it,
                                GValue *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.

#### Parameters

it | the iterator |
result | a pointer to hold the next item |

#### Returns

the result of the operation.

### GstIteratorItemFunction ()

    GstIteratorItem
    (*GstIteratorItemFunction) (GstIterator *it,
                                const GValue *item);

The function that will be called after the next item of the iterator has been retrieved. This function can be used to skip items or stop the iterator.

The function will be called with the iterator lock held.

#### Parameters

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.

#### Parameters

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.

#### Parameters

it | the iterator |

### GstIteratorForeachFunction ()

    void
    (*GstIteratorForeachFunction) (const GValue *item,
                                   gpointer user_data);

A function that is called by `gst_iterator_foreach()` for every element.

#### Parameters

item | The item |
user_data | User data |

### GstIteratorFoldFunction ()

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

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

#### Parameters

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.

### GST_ITERATOR()

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

Macro to cast to a GstIterator

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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,
                      GstIteratorCopyFunction copy,
                      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.

#### Parameters

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. |
copy | copy function |
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,
                           GObject *owner,
                           GstIteratorItemFunction item);

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.

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()`.

#### Parameters

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 on each item retrieved |

#### Returns

the new GstIterator for `list` .

MT safe.

### gst_iterator_new_single ()

    GstIterator *
    gst_iterator_new_single (GType type,
                             const GValue *object);

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.

#### Parameters

type | GType of the passed object |
object | object that this iterator should return |

#### Returns

the new GstIterator for `object` .

### gst_iterator_copy ()

    GstIterator *
    gst_iterator_copy (const GstIterator *it);

Copy the iterator and its state.

#### Parameters

it | a GstIterator |

#### Returns

a new copy of `it` .

### gst_iterator_free ()

    void
    gst_iterator_free (GstIterator *it);

Free the iterator.

MT safe.

#### Parameters

it | The GstIterator to free |

### gst_iterator_next ()

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

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

Only when this function returns `GST_ITERATOR_OK`, `elem` will contain a valid 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.

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.

#### Parameters

it | The GstIterator to iterate |
elem | pointer to hold next element. | [out caller-allocates]

#### Returns

The result of the iteration. Unset `elem` after usage.

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.

#### Parameters

it | The GstIterator to resync |

### 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.

#### Parameters

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

### gst_iterator_filter ()

    GstIterator *
    gst_iterator_filter (GstIterator *it,
                         GCompareFunc func,
                         const GValue *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` . 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.

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

#### Parameters

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` .

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.

#### Parameters

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,
                          GstIteratorForeachFunction func,
                          gpointer user_data);

Iterate over all element of `it` and call the given function `func` for each element.

#### Parameters

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 ()

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

Find the first element in `it` that matches the compare function `func` . `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.

The iterator will not be freed.

This function will return `FALSE` if an error happened to the iterator or if the element wasn't found.

#### Parameters

it | The GstIterator to iterate |
func | the compare function to use. | [scope call]
elem | pointer to a GValue where to store the result. | [out]
user_data | user data passed to the compare function. | [closure]

#### Returns

Returns `TRUE` if the element was found, else `FALSE`.

MT safe.

## Types and Values

### struct GstIterator

    struct GstIterator {
    };

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

#### Members

### enum GstIteratorItem

The result of a GstIteratorItemFunction.

#### Members

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

### enum GstIteratorResult

The result of `gst_iterator_next()`.

#### Members

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 |

## See Also

GstElement, GstBin