/* 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 * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ #ifndef __GST_ITERATOR_H__ #define __GST_ITERATOR_H__ #include <glib-object.h> /* for GValue in the fold */ #include <gst/gstconfig.h> 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, 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, GST_ITERATOR_ITEM_PASS = 1, GST_ITERATOR_ITEM_END = 2 } GstIteratorItem; /** * 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); /** * 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); /** * 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; GstIteratorFreeFunction free; GstIterator *pushed; /* pushed iterator */ GType type; GMutex *lock; 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, GstIteratorResyncFunction resync, GstIteratorFreeFunction free) G_GNUC_MALLOC; GstIterator* gst_iterator_new_list (GType type, GMutex *lock, guint32 *master_cookie, GList **list, GObject * owner, GstIteratorItemFunction item) G_GNUC_MALLOC; GstIterator* gst_iterator_new_single (GType type, const GValue * object) G_GNUC_MALLOC; GstIterator* gst_iterator_copy (const GstIterator *it) G_GNUC_MALLOC; /* using iterators */ GstIteratorResult gst_iterator_next (GstIterator *it, GValue * elem); void gst_iterator_resync (GstIterator *it); void gst_iterator_free (GstIterator *it); void gst_iterator_push (GstIterator *it, GstIterator *other); /* higher-order functions that operate on iterators */ GstIterator* gst_iterator_filter (GstIterator *it, GCompareFunc func, const GValue * user_data) G_GNUC_MALLOC; GstIteratorResult gst_iterator_fold (GstIterator *it, GstIteratorFoldFunction func, GValue *ret, 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 #endif /* __GST_ITERATOR_H__ */