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.h>
  26 #include <glib-object.h> /* for GValue in the fold */
  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   GMutex   *lock;
  68   guint32   cookie;             /* cookie of the iterator */
  69   guint32  *master_cookie;      /* pointer to guint32 holding the cookie when this
  70                                    iterator was created */
  71 };
  72
  73 /* creating iterators */
  74 GstIterator*            gst_iterator_new                (guint size,
  75                                                          GMutex *lock,
  76                                                          guint32 *master_cookie,
  77                                                          GstIteratorNextFunction next,
  78                                                          GstIteratorItemFunction item,
  79                                                          GstIteratorResyncFunction resync,
  80                                                          GstIteratorFreeFunction free);
  81
  82 GstIterator*            gst_iterator_new_list           (GMutex *lock,
  83                                                          guint32 *master_cookie,
  84                                                          GList **list,
  85                                                          gpointer owner,
  86                                                          GstIteratorItemFunction item,
  87                                                          GstIteratorDisposeFunction free);
  88
  89 /* using iterators */
  90 GstIteratorResult       gst_iterator_next               (GstIterator *it, gpointer *result);
  91 void                    gst_iterator_resync             (GstIterator *it);
  92 void                    gst_iterator_free               (GstIterator *it);
  93
  94 void                    gst_iterator_push               (GstIterator *it, GstIterator *other);
  95
  96 /* higher-order functions that operate on iterators */
  97 GstIterator*            gst_iterator_filter             (GstIterator *it, GCompareFunc func,
  98                                                          gpointer user_data);
  99 GstIteratorResult       gst_iterator_fold               (GstIterator *iter,
 100                                                          GstIteratorFoldFunction func,
 101                                                          GValue *ret, gpointer user_data);
 102 GstIteratorResult       gst_iterator_foreach            (GstIterator *iter,
 103                                                          GFunc func, gpointer user_data);
 104 gpointer                gst_iterator_find_custom        (GstIterator *it, GCompareFunc func,
 105                                                          gpointer user_data);
 106
 107 G_END_DECLS
 108
 109 #endif /* __GST_ITERATOR_H__ */