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 #define GST_TYPE_ITERATOR (gst_iterator_get_type ())
  31
  32 /**
  33  * GstIteratorResult:
  34  * @GST_ITERATOR_DONE:   No more items in the iterator
  35  * @GST_ITERATOR_OK:     An item was retrieved
  36  * @GST_ITERATOR_RESYNC: Datastructure changed while iterating
  37  * @GST_ITERATOR_ERROR:  An error happened
  38  *
  39  * The result of gst_iterator_next().
  40  */
  41 typedef enum {
  42   GST_ITERATOR_DONE     = 0,
  43   GST_ITERATOR_OK       = 1,
  44   GST_ITERATOR_RESYNC   = 2,
  45   GST_ITERATOR_ERROR    = 3
  46 } GstIteratorResult;
  47
  48 typedef struct _GstIterator GstIterator;
  49
  50 /**
  51  * GstIteratorItem:
  52  * @GST_ITERATOR_ITEM_SKIP:  Skip this item
  53  * @GST_ITERATOR_ITEM_PASS:  Return item
  54  * @GST_ITERATOR_ITEM_END:   Stop after this item.
  55  *
  56  * The result of a #GstIteratorItemFunction.
  57  */
  58 typedef enum {
  59   GST_ITERATOR_ITEM_SKIP        = 0,
  60   GST_ITERATOR_ITEM_PASS        = 1,
  61   GST_ITERATOR_ITEM_END         = 2
  62 } GstIteratorItem;
  63
  64 /**
  65  * GstIteratorDisposeFunction:
  66  * @owner: the owner of the iterator
  67  *
  68  * The function that will be called when a #GList iterator is freed. The
  69  * owner of the #GList iterator can then clean up its resources.
  70  */
  71 typedef void              (*GstIteratorDisposeFunction) (gpointer owner);
  72
  73 /**
  74  * GstIteratorNextFunction:
  75  * @it: the iterator
  76  * @result: a pointer to hold the next item
  77  *
  78  * The function that will be called when the next element of the iterator
  79  * should be retrieved.
  80  *
  81  * Implementors of a #GstIterator should implement this
  82  * function and pass it to the constructor of the custom iterator.
  83  * The function will be called with the iterator lock held.
  84  *
  85  * Returns: the result of the operation.
  86  */
  87 typedef GstIteratorResult (*GstIteratorNextFunction)    (GstIterator *it, gpointer *result);
  88 /**
  89  * GstIteratorItemFunction:
  90  * @it: the iterator
  91  * @item: the item being retrieved.
  92  *
  93  * The function that will be called after the next item of the iterator
  94  * has been retrieved. This function will typically increase the refcount
  95  * of the item or make a copy.
  96  *
  97  * Implementors of a #GstIterator should implement this
  98  * function and pass it to the constructor of the custom iterator.
  99  * The function will be called with the iterator lock held.
 100  *
 101  * Returns: the result of the operation.
 102  */
 103 typedef GstIteratorItem   (*GstIteratorItemFunction)    (GstIterator *it, gpointer item);
 104 /**
 105  * GstIteratorResyncFunction:
 106  * @it: the iterator
 107  *
 108  * This function will be called whenever a concurrent update happened
 109  * to the iterated datastructure. The implementor of the iterator should
 110  * restart the iterator from the beginning and clean up any state it might
 111  * have.
 112  *
 113  * Implementors of a #GstIterator should implement this
 114  * function and pass it to the constructor of the custom iterator.
 115  * The function will be called with the iterator lock held.
 116  */
 117 typedef void              (*GstIteratorResyncFunction)  (GstIterator *it);
 118 /**
 119  * GstIteratorFreeFunction:
 120  * @it: the iterator
 121  *
 122  * This function will be called when the iterator is freed.
 123  *
 124  * Implementors of a #GstIterator should implement this
 125  * function and pass it to the constructor of the custom iterator.
 126  * The function will be called with the iterator lock held.
 127  */
 128 typedef void              (*GstIteratorFreeFunction)    (GstIterator *it);
 129
 130 /**
 131  * GstIteratorFoldFunction:
 132  * @item: the item to fold
 133  * @ret: a #GValue collecting the result
 134  * @user_data: data passed to gst_iterator_fold()
 135  *
 136  * A function to be passed to gst_iterator_fold().
 137  *
 138  * Returns: TRUE if the fold should continue, FALSE if it should stop.
 139  */
 140 typedef gboolean          (*GstIteratorFoldFunction)    (gpointer item, GValue *ret, gpointer user_data);
 141
 142 /**
 143  * GstCopyFunction:
 144  * @object: The object to copy
 145  *
 146  * A function to create a copy of some object or
 147  * increase its reference count.
 148  *
 149  * Returns: a copy of the object or the same object with increased reference count
 150  *
 151  * Since: 0.10.25
 152  */
 153 typedef gpointer          (*GstCopyFunction)             (gpointer object);
 154
 155 /**
 156  * GST_ITERATOR:
 157  * @it: the #GstIterator value
 158  *
 159  * Macro to cast to a #GstIterator
 160  */
 161 #define GST_ITERATOR(it)                ((GstIterator*)(it))
 162 /**
 163  * GST_ITERATOR_LOCK:
 164  * @it: the #GstIterator to get the lock of
 165  *
 166  * Macro to get the lock protecting the datastructure being iterated.
 167  */
 168 #define GST_ITERATOR_LOCK(it)           (GST_ITERATOR(it)->lock)
 169 /**
 170  * GST_ITERATOR_COOKIE:
 171  * @it: the #GstIterator to get the cookie of
 172  *
 173  * Macro to get the cookie of a #GstIterator. The cookie of the
 174  * iterator is the value of the master cookie when the iterator
 175  * was created.
 176  * Whenever the iterator is iterated, the value is compared to the
 177  * value of the master cookie. If they are different, a concurrent
 178  * modification happened to the iterator and a resync is needed.
 179  */
 180 #define GST_ITERATOR_COOKIE(it)         (GST_ITERATOR(it)->cookie)
 181 /**
 182  * GST_ITERATOR_ORIG_COOKIE:
 183  * @it: the #GstIterator to get the master cookie of
 184  *
 185  * Macro to get a pointer to where the master cookie is stored. The
 186  * master cookie protects the structure being iterated and gets updated
 187  * whenever the datastructure changes.
 188  */
 189 #define GST_ITERATOR_ORIG_COOKIE(it)    (GST_ITERATOR(it)->master_cookie)
 190
 191 /**
 192  * GstIterator:
 193  * @next: The function to get the next item in the iterator
 194  * @item: The function to be called for each item retrieved
 195  * @resync: The function to call when a resync is needed.
 196  * @free: The function to call when the iterator is freed
 197  * @pushed: The iterator that is currently pushed with gst_iterator_push()
 198  * @type: The type of the object that this iterator will return
 199  * @lock: The lock protecting the data structure and the cookie.
 200  * @cookie: The cookie; the value of the master_cookie when this iterator was
 201  *          created.
 202  * @master_cookie: A pointer to the master cookie.
 203  *
 204  * #GstIterator base structure. The values of this structure are
 205  * protected for subclasses, use the methods to use the #GstIterator.
 206  */
 207 struct _GstIterator {
 208   /*< protected >*/
 209   GstIteratorNextFunction next;
 210   GstIteratorItemFunction item;
 211   GstIteratorResyncFunction resync;
 212   GstIteratorFreeFunction free;
 213
 214   GstIterator *pushed;          /* pushed iterator */
 215
 216   GType     type;
 217   GMutex   *lock;
 218   guint32   cookie;             /* cookie of the iterator */
 219   guint32  *master_cookie;      /* pointer to guint32 holding the cookie when this
 220                                    iterator was created */
 221   guint     size;
 222
 223   /*< private >*/
 224   gpointer _gst_reserved[GST_PADDING-1];
 225 };
 226
 227 GType                   gst_iterator_get_type           (void);
 228
 229 /* creating iterators */
 230 GstIterator*            gst_iterator_new                (guint size,
 231                                                          GType type,
 232                                                          GMutex *lock,
 233                                                          guint32 *master_cookie,
 234                                                          GstIteratorNextFunction next,
 235                                                          GstIteratorItemFunction item,
 236                                                          GstIteratorResyncFunction resync,
 237                                                          GstIteratorFreeFunction free);
 238
 239 GstIterator*            gst_iterator_new_list           (GType type,
 240                                                          GMutex *lock,
 241                                                          guint32 *master_cookie,
 242                                                          GList **list,
 243                                                          gpointer owner,
 244                                                          GstIteratorItemFunction item,
 245                                                          GstIteratorDisposeFunction free);
 246
 247 GstIterator*            gst_iterator_new_single         (GType type,
 248                                                          gpointer object,
 249                                                          GstCopyFunction copy,
 250                                                          GFreeFunc free);
 251
 252 /* using iterators */
 253 GstIteratorResult       gst_iterator_next               (GstIterator *it, gpointer *elem);
 254 void                    gst_iterator_resync             (GstIterator *it);
 255 void                    gst_iterator_free               (GstIterator *it);
 256
 257 void                    gst_iterator_push               (GstIterator *it, GstIterator *other);
 258
 259 /* higher-order functions that operate on iterators */
 260 GstIterator*            gst_iterator_filter             (GstIterator *it, GCompareFunc func,
 261                                                          gpointer user_data);
 262 GstIteratorResult       gst_iterator_fold               (GstIterator *it,
 263                                                          GstIteratorFoldFunction func,
 264                                                          GValue *ret, gpointer user_data);
 265 GstIteratorResult       gst_iterator_foreach            (GstIterator *it,
 266                                                          GFunc func, gpointer user_data);
 267 gpointer                gst_iterator_find_custom        (GstIterator *it, GCompareFunc func,
 268                                                          gpointer user_data);
 269
 270 G_END_DECLS
 271
 272 #endif /* __GST_ITERATOR_H__ */