Iterator

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:

Last reviewed on 2009-06-16 (0.10.24)

Constructors

this
this(GstIterator* gstIterator)

Sets our main struct and passes it to the parent class

this
this(uint size, GType type, Mutex lock, uint masterCookie, 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.

this
this(GType type, Mutex lock, uint* masterCookie, ListG list, ObjectG 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().

this
this(GType type, Value 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.

Members

Functions

copy
Iterator copy()

Copy the iterator and its state.

filter
Iterator filter(GCompareFunc func, Value userData)

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.

findCustom
int findCustom(GCompareFunc func, Value elem, void* userData)

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.

fold
GstIteratorResult fold(GstIteratorFoldFunction func, Value ret, void* userData)

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.

foreac
GstIteratorResult foreac(GstIteratorForeachFunction func, void* userData)

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

free
void free()

Free the iterator. MT safe.

getIteratorStruct
GstIterator* getIteratorStruct()

Get the main Gtk struct

getStruct
void* getStruct()

the main Gtk struct as a void*

next
GstIteratorResult next(Value 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.

push
void push(Iterator 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.

resync
void resync()

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.

Variables

gstIterator
GstIterator* gstIterator;

the main Gtk struct

Meta