GstIterator

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

Synopsis


#include <gst/gst.h>


            GstIterator;
enum        GstIteratorItem;
enum        GstIteratorResult;
void        (*GstIteratorDisposeFunction)   (gpointer owner);
GstIteratorResult (*GstIteratorNextFunction)
                                            (GstIterator *it,
                                             gpointer *result);
GstIteratorItem (*GstIteratorItemFunction)  (GstIterator *it,
                                             gpointer item);
void        (*GstIteratorResyncFunction)    (GstIterator *it);
void        (*GstIteratorFreeFunction)      (GstIterator *it);
gboolean    (*GstIteratorFoldFunction)      (gpointer item,
                                             GValue *ret,
                                             gpointer user_data);
#define     GST_ITERATOR                    (it)
#define     GST_ITERATOR_LOCK               (it)
#define     GST_ITERATOR_COOKIE             (it)
#define     GST_ITERATOR_ORIG_COOKIE        (it)
GstIterator* gst_iterator_new               (guint size,
                                             GType type,
                                             GMutex *lock,
                                             guint32 *master_cookie,
                                             GstIteratorNextFunction next,
                                             GstIteratorItemFunction item,
                                             GstIteratorResyncFunction resync,
                                             GstIteratorFreeFunction free);
GstIterator* gst_iterator_new_list          (GType type,
                                             GMutex *lock,
                                             guint32 *master_cookie,
                                             GList **list,
                                             gpointer owner,
                                             GstIteratorItemFunction item,
                                             GstIteratorDisposeFunction free);
GstIteratorResult gst_iterator_next         (GstIterator *it,
                                             gpointer *elem);
void        gst_iterator_resync             (GstIterator *it);
void        gst_iterator_free               (GstIterator *it);
void        gst_iterator_push               (GstIterator *it,
                                             GstIterator *other);
GstIterator* gst_iterator_filter            (GstIterator *it,
                                             GCompareFunc func,
                                             gpointer user_data);
GstIteratorResult gst_iterator_fold         (GstIterator *it,
                                             GstIteratorFoldFunction func,
                                             GValue *ret,
                                             gpointer user_data);
GstIteratorResult gst_iterator_foreach      (GstIterator *it,
                                             GFunc func,
                                             gpointer user_data);
gpointer    gst_iterator_find_custom        (GstIterator *it,
                                             GCompareFunc func,
                                             gpointer user_data);


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.

The basic use pattern of an iterator is as follows:

Example 10. Using an iterator

   it = _get_iterator(object);
   done = FALSE;
   while (!done) {
     switch (gst_iterator_next (it, &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 parameter were given...
         done = TRUE;
         break;
       case GST_ITERATOR_DONE:
         done = TRUE;
         break;
     }
   }
   gst_iterator_free (it);
  

Last reviewed on 2005-11-09 (0.9.4)

Details

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.

GST_ITERATOR_ITEM_SKIPGST_ITERATOR_ITEM_SKIP Skip this item Skip this item GST_ITERATOR_ITEM_PASSGST_ITERATOR_ITEM_PASS Return item Return item GST_ITERATOR_ITEM_ENDGST_ITERATOR_ITEM_END Stop after this item. Stop after this item.
GST_ITERATOR_ITEM_SKIP Skip this item
GST_ITERATOR_ITEM_PASS Return item
GST_ITERATOR_ITEM_END Stop after this item.

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

GST_ITERATOR_DONEGST_ITERATOR_DONE No more items in the iterator No more items in the iterator GST_ITERATOR_OKGST_ITERATOR_OK An item was retrieved An item was retrieved GST_ITERATOR_RESYNCGST_ITERATOR_RESYNC Datastructure changed while iterating Datastructure changed while iterating GST_ITERATOR_ERRORGST_ITERATOR_ERROR An error happened An error happened
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

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.

owner :owner the owner of the iterator the owner of the iterator
owner : the owner of the iterator

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.

it :it the iterator the iterator result :result a pointer to hold the next item a pointer to hold the next item Returns :Returns the result of the operation. the result of the operation.
it : the iterator
result : a pointer to hold the next item
Returns : the result of the operation.

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.

it :it the iterator the iterator item :item the item being retrieved. the item being retrieved. Returns :Returns the result of the operation. the result of the operation.
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.

it :it the iterator the iterator
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.

it :it the iterator the iterator
it : the iterator

GstIteratorFoldFunction ()

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

A function to be passed to gst_iterator_fold().

item :item the item to fold the item to fold ret :ret a GValue collecting the result a GValue collecting the result user_data :user_data data passed to gst_iterator_fold() data passed to gst_iterator_fold() gst_iterator_fold()gst_iterator_fold()Returns :Returns TRUE if the fold should continue, FALSE if it should stop. TRUE if the fold should continue, FALSE if it should stop.
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

it :it the GstIterator value the GstIterator value GstIteratorGstIterator
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.

it :it the GstIterator to get the lock of the GstIterator to get the lock of GstIteratorGstIterator
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.

it :it the GstIterator to get the cookie of the GstIterator to get the cookie of GstIteratorGstIterator
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.

it :it the GstIterator to get the master cookie of the GstIterator to get the master cookie of GstIteratorGstIterator
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,
                                             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.

size :size the size of the iterator structure the size of the iterator structure type :type GType of children GType of children GTypeGTypelock :lock pointer to a GMutex. pointer to a GMutex. GMutexGMutexmaster_cookie :master_cookie pointer to a guint32 to protect the iterated object. pointer to a guint32 to protect the iterated object. next :next function to get next item function to get next item item :item function to call on each item retrieved function to call on each item retrieved resync :resync function to resync the iterator function to resync the iterator free :free function to free the iterator function to free the iterator Returns :Returns the new GstIterator. MT safe. the new GstIterator. MT safe. GstIteratorGstIterator
size : the size of the iterator structure
type : GType of children
lock : pointer to a GMutex.
master_cookie : pointer to a guint32 to protect the iterated object.
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,
                                             gpointer owner,
                                             GstIteratorItemFunction item,
                                             GstIteratorDisposeFunction free);

Create a new iterator designed for iterating list.

type :type GType of elements GType of elements GTypeGTypelock :lock pointer to a GMutex protecting the list. pointer to a GMutex protecting the list. GMutexGMutexmaster_cookie :master_cookie pointer to a guint32 to protect the list. pointer to a guint32 to protect the list. list :list pointer to the list pointer to the list owner :owner object owning the list object owning the list item :item function to call for each item function to call for each item free :free function to call when the iterator is freed function to call when the iterator is freed Returns :Returns the new GstIterator for list. MT safe. the new GstIterator for list. MT safe. GstIteratorGstIteratorlist
type : GType of elements
lock : pointer to a GMutex protecting the list.
master_cookie : pointer to a guint32 to protect the list.
list : pointer to the list
owner : object owning the list
item : function to call for each item
free : function to call when the iterator is freed
Returns : the new GstIterator for list. MT safe.

gst_iterator_next ()

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

Get the next item from the iterator. For iterators that return refcounted objects, the returned object will have its refcount increased and should therefore be unreffed after usage.

it :it The GstIterator to iterate The GstIterator to iterate GstIteratorGstIteratorelem :elem pointer to hold next element pointer to hold next element Returns :Returns The result of the iteration. Unref after usage if this is a refcounted object. MT safe. The result of the iteration. Unref after usage if this is a refcounted object. MT safe.
it : The GstIterator to iterate
elem : pointer to hold next element
Returns : The result of the iteration. Unref after usage if this is a refcounted object. 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.

MT safe.

it :it The GstIterator to resync The GstIterator to resync GstIteratorGstIterator
it : The GstIterator to resync

gst_iterator_free ()

void        gst_iterator_free               (GstIterator *it);

Free the iterator.

MT safe.

it :it The GstIterator to free The GstIterator to free GstIteratorGstIterator
it : The GstIterator to free

gst_iterator_push ()

void        gst_iterator_push               (GstIterator *it,
                                             GstIterator *other);

Pushes other iterator onto it. All calls performed on it are forwarded tot 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.

MT safe.

it :it The GstIterator to use The GstIterator to use GstIteratorGstIteratorother :other The GstIterator to push The GstIterator to push GstIteratorGstIterator
it : The GstIterator to use
other : The GstIterator to push

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.

it :it The GstIterator to filter The GstIterator to filter GstIteratorGstIteratorfunc :func the compare function to select elements the compare function to select elements user_data :user_data user data passed to the compare function user data passed to the compare function Returns :Returns a new GstIterator. MT safe. a new GstIterator. MT safe. GstIteratorGstIterator
it : The GstIterator to filter
func : the compare function to select elements
user_data : user data passed to the compare function
Returns : a new GstIterator. MT safe.

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, proc will be called as proc (object, ret, user_data) for each object in iter. 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 foreach and 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.

it :it The GstIterator to fold over The GstIterator to fold over GstIteratorGstIteratorfunc :func the fold function the fold function ret :ret the seed value passed to the fold function the seed value passed to the fold function user_data :user_data user data passed to the fold function user data passed to the fold function Returns :Returns A GstIteratorResult, as described above. MT safe. A GstIteratorResult, as described above. MT safe. GstIteratorResultGstIteratorResult
it : The GstIterator to fold over
func : the fold function
ret : the seed value passed to the fold function
user_data : user data passed to the fold function
Returns : A GstIteratorResult, as described above. MT safe.

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.

it :it The GstIterator to iterate The GstIterator to iterate GstIteratorGstIteratorfunc :func the function to call for each element. the function to call for each element. user_data :user_data user data passed to the function user data passed to the function Returns :Returns the result call to gst_iterator_fold(). The iterator will not be freed. MT safe. the result call to gst_iterator_fold(). The iterator will not be freed. MT safe. gst_iterator_fold()gst_iterator_fold()
it : The GstIterator to iterate
func : the function to call for each element.
user_data : user data passed to the function
Returns : the result call to gst_iterator_fold(). The iterator will not be freed. MT safe.

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.

The iterator will not be freed.

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

it :it The GstIterator to iterate The GstIterator to iterate GstIteratorGstIteratorfunc :func the compare function to use the compare function to use user_data :user_data user data passed to the compare function user data passed to the compare function Returns :Returns The element in the iterator that matches the compare function or NULL when no element matched. MT safe. The element in the iterator that matches the compare function or NULL when no element matched. MT safe.
it : The GstIterator to iterate
func : the compare function to use
user_data : user data passed to the compare function
Returns : The element in the iterator that matches the compare function or NULL when no element matched. MT safe.

See Also

GstElement, GstBin