GstIterator

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

Functions

Types and Values

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

The basic use pattern of an iterator is as follows:

Example 9. 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
23
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);

Last reviewed on 2009-06-16 (0.10.24)

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