GstIterator

GstIterator —

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,
                                             GMutex *lock,
                                             guint32 *master_cookie,
                                             GstIteratorNextFunction next,
                                             GstIteratorItemFunction item,
                                             GstIteratorResyncFunction resync,
                                             GstIteratorFreeFunction free);
GstIterator* gst_iterator_new_list          (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 *iter,
                                             GstIteratorFoldFunction func,
                                             GValue *ret,
                                             gpointer user_data);
GstIteratorResult gst_iterator_foreach      (GstIterator *iter,
                                             GFunc func,
                                             gpointer user_data);
gpointer    gst_iterator_find_custom        (GstIterator *it,
                                             GCompareFunc func,
                                             gpointer user_data);


Description

Details

GstIterator

typedef struct {
  GstIteratorNextFunction next;
  GstIteratorItemFunction item;
  GstIteratorResyncFunction resync;
  GstIteratorFreeFunction free;

  GstIterator *pushed;		/* pushed iterator */

  GMutex   *lock;
  guint32   cookie;		/* cookie of the iterator */
  guint32  *master_cookie;	/* pointer to guint32 holding the cookie when this
				   iterator was created */
} GstIterator;


enum GstIteratorItem

typedef enum {
  GST_ITERATOR_ITEM_SKIP	= 0, /* skip item */
  GST_ITERATOR_ITEM_PASS	= 1, /* return item */
  GST_ITERATOR_ITEM_END		= 2, /* stop after this item */
} GstIteratorItem;


enum GstIteratorResult

typedef enum {
  GST_ITERATOR_DONE	= 0, /* no more items in the iterator */
  GST_ITERATOR_OK	= 1, /* item retrieved */
  GST_ITERATOR_RESYNC	= 2, /* datastructures changed while iterating */
  GST_ITERATOR_ERROR	= 3, /* some error happened */
} GstIteratorResult;


GstIteratorDisposeFunction ()

void        (*GstIteratorDisposeFunction)   (gpointer owner);

owner :

GstIteratorNextFunction ()

GstIteratorResult (*GstIteratorNextFunction)
                                            (GstIterator *it,
                                             gpointer *result);

it :
result :
Returns :

GstIteratorItemFunction ()

GstIteratorItem (*GstIteratorItemFunction)  (GstIterator *it,
                                             gpointer item);

it :
item :
Returns :

GstIteratorResyncFunction ()

void        (*GstIteratorResyncFunction)    (GstIterator *it);

it :

GstIteratorFreeFunction ()

void        (*GstIteratorFreeFunction)      (GstIterator *it);

it :

GstIteratorFoldFunction ()

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

item :
ret :
user_data :
Returns :

GST_ITERATOR()

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

it :

GST_ITERATOR_LOCK()

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

it :

GST_ITERATOR_COOKIE()

#define GST_ITERATOR_COOKIE(it)		(GST_ITERATOR(it)->cookie)

it :

GST_ITERATOR_ORIG_COOKIE()

#define GST_ITERATOR_ORIG_COOKIE(it)	(GST_ITERATOR(it)->master_cookie)

it :

gst_iterator_new ()

GstIterator* gst_iterator_new               (guint size,
                                             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 : the size of the iterator structure
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          (GMutex *lock,
                                             guint32 *master_cookie,
                                             GList **list,
                                             gpointer owner,
                                             GstIteratorItemFunction item,
                                             GstIteratorDisposeFunction free);

Create a new iterator designed for iterating list.

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.

it : The GstIterator to iterate
elem : pointer to hold next element
Returns : The result of the iteration. 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 : The GstIterator to resync

gst_iterator_free ()

void        gst_iterator_free               (GstIterator *it);

Free the iterator.

MT safe.

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 : 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. The GCompareFunc should return 0 for elements that should be included in the iterator.

When this iterator is freed, it will also be freed.

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 *iter,
                                             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.

iter : 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 *iter,
                                             GFunc func,
                                             gpointer user_data);

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

iter : 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. The compare function should return 0 when the element is found.

The iterator will not be freed.

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.