GstIterator

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

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

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.

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.

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.

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.

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.

GstIteratorFoldFunction ()

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

A function to be passed to gst_iterator_fold().

GstCopyFunction ()

gpointer            (*GstCopyFunction)                  (gpointer object);

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

Since 0.10.25

GST_ITERATOR()

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

Macro to cast to a GstIterator

GST_ITERATOR_LOCK()

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

Macro to get the lock protecting the datastructure being iterated.

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.

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.

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.

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.

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 the be considered. This happens often for the GstPadIterIntLinkFunction.

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.

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.

gst_iterator_free ()

void                gst_iterator_free                   (GstIterator *it);

Free the iterator.

MT safe.

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.

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.

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.

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.

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.

The iterator will not be freed.

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