/* 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];

};

GST_API

GType                   gst_iterator_get_type           (void);

/* creating iterators */

GST_API

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;

GST_API

GstIterator*            gst_iterator_new_list           (GType type,

                                                         GMutex *lock,

                                                         guint32 *master_cookie,

                                                         GList **list,

                                                         GObject * owner,

                                                         GstIteratorItemFunction item) G_GNUC_MALLOC;

GST_API

GstIterator*            gst_iterator_new_single         (GType type,

                                                         const GValue * object) G_GNUC_MALLOC;

GST_API

GstIterator*            gst_iterator_copy               (const GstIterator *it) G_GNUC_MALLOC;

/* using iterators */

GST_API

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

GST_API

void                    gst_iterator_resync             (GstIterator *it);

GST_API

void                    gst_iterator_free               (GstIterator *it);

GST_API

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

/* higher-order functions that operate on iterators */

GST_API

GstIterator*            gst_iterator_filter             (GstIterator *it, GCompareFunc func,

                                                         const GValue * user_data) G_GNUC_MALLOC;

GST_API

GstIteratorResult       gst_iterator_fold               (GstIterator *it,

                                                         GstIteratorFoldFunction func,

                                                         GValue *ret, gpointer user_data);

GST_API

GstIteratorResult       gst_iterator_foreach            (GstIterator *it,

                                                         GstIteratorForeachFunction func, gpointer user_data);

GST_API

gboolean                gst_iterator_find_custom        (GstIterator *it, GCompareFunc func,

                                                         GValue *elem, gpointer user_data);

#ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC

G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstIterator, gst_iterator_free)

#endif

G_END_DECLS

#endif /* __GST_ITERATOR_H__ */