Iterator

Object Hierarchy:

Description:

public class Iterator<T>

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:

Using an iterator:


it = _get_iterator(object);
done = FALSE;
while (!done) {
switch (gst_iterator_next (it, &amp;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)

Namespace: Gst

Package: gstreamer-0.10

Content:

Creation methods:

public Iterator (uint size, Type type, Mutex lock, ref uint32 master_cookie, IteratorNextFunction<T> next, IteratorItemFunction<T> item, IteratorResyncFunction resync, IteratorFreeFunction 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. MT safe.
public Iterator.list (Type type, Mutex lock, ref uint32 master_cookie, List<T> list, void* owner, IteratorItemFunction<T> item, IteratorDisposeFunction 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 responsible for freeing/unreffing the item after usage as explained in 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 RESYNC to the user of the iterator in the next call to next. MT safe.
public Iterator.single (Type type, T object, CopyFunction copy, FreeFunc free)
This Iterator is a convenient iterator for the common case where a Iterator needs to be returned but only a single object has to be considered. This happens often for the PadIterIntLinkFunction.

Methods:

public T find_custom (CompareFunc func, T user_data)
Find the first element in it that matches the compare function func. 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. function or NULL when no element matched. MT safe.
public IteratorResult fold (IteratorFoldFunction<T> func, out Value ret)
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 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 foreach and find_custom operations. The fold will proceed as long as func returns TRUE. When the iterator has no more arguments, DONE will be returned. If func returns FALSE, the fold will stop, and OK will be returned. Errors or resyncs will cause fold to return ERROR or RESYNC as appropriate. The iterator will not be freed. MT safe.
public IteratorResult foreach (Func func)
Iterate over all element of it and call the given function func for each element. As in fold, the refcount of a refcounted object will be increased before func is called, and should be unrefed after use. freed. MT safe.
public IteratorResult next (out T elem)
Get the next item from the iterator in elem. Only when this function returns 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 DONE, no more elements can be retrieved from it. A return value of RESYNC indicates that the element list was concurrently updated. The user of it should call resync to get the newly updated list. A return value of ERROR indicates an unrecoverable fatal error. is a refcounted object. MT safe.
public void push (Iterator other)
Pushes other iterator onto it. All calls performed on it are forwarded to other. If other returns 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 resync is called on it , other will automatically be popped. MT safe.
public void resync ()
Resync the iterator. this function is mostly called after next returned RESYNC . When an iterator was pushed on it, it will automatically be popped again with this function. MT safe.

Fields:

public uint32 cookie
public unowned Mutex lock
public void* master_cookie
public unowned Iterator pushed
public Type type