/* GStreamer
* Copyright (C) 2004 Wim Taymans <wim@fluendo.com>
+ * Copyright (C) 2011 Sebastian Dröge <sebastian.droege@collabora.co.uk>
*
* gstiterator.h: Header for GstIterator
*
G_BEGIN_DECLS
+#define GST_TYPE_ITERATOR (gst_iterator_get_type ())
+
+/**
+ * GstIteratorResult:
+ * @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
+ *
+ * The result of gst_iterator_next().
+ */
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 */
+ GST_ITERATOR_DONE = 0,
+ GST_ITERATOR_OK = 1,
+ GST_ITERATOR_RESYNC = 2,
+ GST_ITERATOR_ERROR = 3
} GstIteratorResult;
typedef struct _GstIterator GstIterator;
+/**
+ * GstIteratorItem:
+ * @GST_ITERATOR_ITEM_SKIP: Skip this item
+ * @GST_ITERATOR_ITEM_PASS: Return item
+ * @GST_ITERATOR_ITEM_END: Stop after this item.
+ *
+ * The result of a #GstIteratorItemFunction.
+ */
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 */
+ GST_ITERATOR_ITEM_SKIP = 0,
+ GST_ITERATOR_ITEM_PASS = 1,
+ GST_ITERATOR_ITEM_END = 2
} GstIteratorItem;
-typedef void (*GstIteratorDisposeFunction) (gpointer owner);
+/**
+ * GstIteratorCopyFunction:
+ * @it: The original iterator
+ * @copy: The copied iterator
+ *
+ * This function will be called when creating a copy of @it and should
+ * create a copy of all custom iterator fields or increase their
+ * reference counts.
+ */
+typedef void (*GstIteratorCopyFunction) (const GstIterator *it, GstIterator *copy);
-typedef GstIteratorResult (*GstIteratorNextFunction) (GstIterator *it, gpointer *result);
-typedef GstIteratorItem (*GstIteratorItemFunction) (GstIterator *it, gpointer item);
+/**
+ * GstIteratorItemFunction:
+ * @it: the iterator
+ * @item: the item being retrieved.
+ *
+ * The function that will be called after the next item of the iterator
+ * has been retrieved. This function can be used to skip items or stop
+ * the iterator.
+ *
+ * The function will be called with the iterator lock held.
+ *
+ * Returns: the result of the operation.
+ */
+typedef GstIteratorItem (*GstIteratorItemFunction) (GstIterator *it, const GValue * item);
+
+/**
+ * GstIteratorNextFunction:
+ * @it: the iterator
+ * @result: a pointer to hold the next item
+ *
+ * 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.
+ *
+ * Returns: the result of the operation.
+ */
+typedef GstIteratorResult (*GstIteratorNextFunction) (GstIterator *it, GValue *result);
+/**
+ * GstIteratorResyncFunction:
+ * @it: the iterator
+ *
+ * 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.
+ */
typedef void (*GstIteratorResyncFunction) (GstIterator *it);
+/**
+ * GstIteratorFreeFunction:
+ * @it: the iterator
+ *
+ * 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.
+ */
typedef void (*GstIteratorFreeFunction) (GstIterator *it);
-typedef gboolean (*GstIteratorFoldFunction) (gpointer item, GValue *ret, gpointer user_data);
+/**
+ * GstIteratorForeachFunction:
+ * @item: The item
+ * @user_data: User data
+ *
+ * A function that is called by gst_iterator_foreach() for every element.
+ */
+typedef void (*GstIteratorForeachFunction) (const GValue * item, gpointer user_data);
+
+/**
+ * GstIteratorFoldFunction:
+ * @item: the item to fold
+ * @ret: a #GValue collecting the result
+ * @user_data: data passed to gst_iterator_fold()
+ *
+ * A function to be passed to gst_iterator_fold().
+ *
+ * Returns: TRUE if the fold should continue, FALSE if it should stop.
+ */
+typedef gboolean (*GstIteratorFoldFunction) (const GValue * item, GValue * ret, gpointer user_data);
+/**
+ * GST_ITERATOR:
+ * @it: the #GstIterator value
+ *
+ * Macro to cast to a #GstIterator
+ */
#define GST_ITERATOR(it) ((GstIterator*)(it))
+/**
+ * GST_ITERATOR_LOCK:
+ * @it: the #GstIterator to get the lock of
+ *
+ * Macro to get the lock protecting the datastructure being iterated.
+ */
#define GST_ITERATOR_LOCK(it) (GST_ITERATOR(it)->lock)
+/**
+ * GST_ITERATOR_COOKIE:
+ * @it: the #GstIterator to get the cookie of
+ *
+ * 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.
+ */
#define GST_ITERATOR_COOKIE(it) (GST_ITERATOR(it)->cookie)
+/**
+ * GST_ITERATOR_ORIG_COOKIE:
+ * @it: the #GstIterator to get the master cookie of
+ *
+ * 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.
+ */
#define GST_ITERATOR_ORIG_COOKIE(it) (GST_ITERATOR(it)->master_cookie)
+/**
+ * GstIterator:
+ * @copy: The function to copy the iterator
+ * @next: The function to get the next item in the iterator
+ * @item: The function to be called for each item retrieved
+ * @resync: The function to call when a resync is needed.
+ * @free: The function to call when the iterator is freed
+ * @pushed: The iterator that is currently pushed with gst_iterator_push()
+ * @type: The type of the object that this iterator will return
+ * @lock: The lock protecting the data structure and the cookie.
+ * @cookie: The cookie; the value of the master_cookie when this iterator was
+ * created.
+ * @master_cookie: A pointer to the master cookie.
+ * @size: the size of the iterator
+ *
+ * #GstIterator base structure. The values of this structure are
+ * protected for subclasses, use the methods to use the #GstIterator.
+ */
struct _GstIterator {
+ /*< protected >*/
+ GstIteratorCopyFunction copy;
GstIteratorNextFunction next;
GstIteratorItemFunction item;
GstIteratorResyncFunction resync;
guint32 cookie; /* cookie of the iterator */
guint32 *master_cookie; /* pointer to guint32 holding the cookie when this
iterator was created */
+ guint size;
/*< private >*/
gpointer _gst_reserved[GST_PADDING];
};
+GType gst_iterator_get_type (void);
+
/* creating iterators */
GstIterator* gst_iterator_new (guint size,
GType type,
GMutex *lock,
guint32 *master_cookie,
+ GstIteratorCopyFunction copy,
GstIteratorNextFunction next,
- GstIteratorItemFunction item,
+ GstIteratorItemFunction item,
GstIteratorResyncFunction resync,
GstIteratorFreeFunction free);
-GstIterator* gst_iterator_new_list (GType type,
+GstIterator* gst_iterator_new_list (GType type,
GMutex *lock,
guint32 *master_cookie,
GList **list,
- gpointer owner,
- GstIteratorItemFunction item,
- GstIteratorDisposeFunction free);
+ GObject * owner,
+ GstIteratorItemFunction item);
+
+GstIterator* gst_iterator_new_single (GType type,
+ const GValue * object);
+
+GstIterator* gst_iterator_copy (const GstIterator *it);
/* using iterators */
-GstIteratorResult gst_iterator_next (GstIterator *it, gpointer *elem);
+GstIteratorResult gst_iterator_next (GstIterator *it, GValue * elem);
void gst_iterator_resync (GstIterator *it);
void gst_iterator_free (GstIterator *it);
/* higher-order functions that operate on iterators */
GstIterator* gst_iterator_filter (GstIterator *it, GCompareFunc func,
- gpointer user_data);
-GstIteratorResult gst_iterator_fold (GstIterator *iter,
+ const GValue * user_data);
+GstIteratorResult gst_iterator_fold (GstIterator *it,
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);
+GstIteratorResult gst_iterator_foreach (GstIterator *it,
+ GstIteratorForeachFunction func, gpointer user_data);
+gboolean gst_iterator_find_custom (GstIterator *it, GCompareFunc func,
+ GValue *elem, gpointer user_data);
G_END_DECLS
projects / platform / upstream / gstreamer.git / blobdiff