gst/gstiterator.h

   1 /* GStreamer
   2  * Copyright (C) 2004 Wim Taymans <wim@fluendo.com>
   3  *
   4  * gstiterator.h: Header for GstIterator
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22 #ifndef __GST_ITERATOR_H__
  23 #define __GST_ITERATOR_H__
  24
  25 #include <glib-object.h> /* for GValue in the fold */
  26 #include <gst/gstconfig.h>
  27
  28 G_BEGIN_DECLS
  29
  30 typedef enum {
  31   GST_ITERATOR_DONE     = 0, /* no more items in the iterator */
  32   GST_ITERATOR_OK       = 1, /* item retrieved */
  33   GST_ITERATOR_RESYNC   = 2, /* datastructures changed while iterating */
  34   GST_ITERATOR_ERROR    = 3, /* some error happened */
  35 } GstIteratorResult;
  36
  37 typedef struct _GstIterator GstIterator;
  38
  39 typedef enum {
  40   GST_ITERATOR_ITEM_SKIP        = 0, /* skip item */
  41   GST_ITERATOR_ITEM_PASS        = 1, /* return item */
  42   GST_ITERATOR_ITEM_END         = 2, /* stop after this item */
  43 } GstIteratorItem;
  44
  45 typedef void              (*GstIteratorDisposeFunction) (gpointer owner);
  46
  47 typedef GstIteratorResult (*GstIteratorNextFunction)    (GstIterator *it, gpointer *result);
  48 typedef GstIteratorItem   (*GstIteratorItemFunction)    (GstIterator *it, gpointer item);
  49 typedef void              (*GstIteratorResyncFunction)  (GstIterator *it);
  50 typedef void              (*GstIteratorFreeFunction)    (GstIterator *it);
  51
  52 typedef gboolean          (*GstIteratorFoldFunction)    (gpointer item, GValue *ret, gpointer user_data);
  53
  54 #define GST_ITERATOR(it)                ((GstIterator*)(it))
  55 #define GST_ITERATOR_LOCK(it)           (GST_ITERATOR(it)->lock)
  56 #define GST_ITERATOR_COOKIE(it)         (GST_ITERATOR(it)->cookie)
  57 #define GST_ITERATOR_ORIG_COOKIE(it)    (GST_ITERATOR(it)->master_cookie)
  58
  59 struct _GstIterator {
  60   GstIteratorNextFunction next;
  61   GstIteratorItemFunction item;
  62   GstIteratorResyncFunction resync;
  63   GstIteratorFreeFunction free;
  64
  65   GstIterator *pushed;          /* pushed iterator */
  66
  67   GType     type;
  68   GMutex   *lock;
  69   guint32   cookie;             /* cookie of the iterator */
  70   guint32  *master_cookie;      /* pointer to guint32 holding the cookie when this
  71                                    iterator was created */
  72
  73   /*< private >*/
  74   gpointer _gst_reserved[GST_PADDING];
  75 };
  76
  77 /* creating iterators */
  78 GstIterator*            gst_iterator_new                (guint size,
  79                                                          GType type,
  80                                                          GMutex *lock,
  81                                                          guint32 *master_cookie,
  82                                                          GstIteratorNextFunction next,
  83                                                          GstIteratorItemFunction item,
  84                                                          GstIteratorResyncFunction resync,
  85                                                          GstIteratorFreeFunction free);
  86
  87 GstIterator*            gst_iterator_new_list           (GType type,
  88                                                          GMutex *lock,
  89                                                          guint32 *master_cookie,
  90                                                          GList **list,
  91                                                          gpointer owner,
  92                                                          GstIteratorItemFunction item,
  93                                                          GstIteratorDisposeFunction free);
  94
  95 /* using iterators */
  96 GstIteratorResult       gst_iterator_next               (GstIterator *it, gpointer *elem);
  97 void                    gst_iterator_resync             (GstIterator *it);
  98 void                    gst_iterator_free               (GstIterator *it);
  99
 100 void                    gst_iterator_push               (GstIterator *it, GstIterator *other);
 101
 102 /* higher-order functions that operate on iterators */
 103 GstIterator*            gst_iterator_filter             (GstIterator *it, GCompareFunc func,
 104                                                          gpointer user_data);
 105 GstIteratorResult       gst_iterator_fold               (GstIterator *iter,
 106                                                          GstIteratorFoldFunction func,
 107                                                          GValue *ret, gpointer user_data);
 108 GstIteratorResult       gst_iterator_foreach            (GstIterator *iter,
 109                                                          GFunc func, gpointer user_data);
 110 gpointer                gst_iterator_find_custom        (GstIterator *it, GCompareFunc func,
 111                                                          gpointer user_data);
 112
 113 G_END_DECLS
 114
 115 #endif /* __GST_ITERATOR_H__ */