2 * Copyright (C) 2004 Wim Taymans <wim@fluendo.com>
4 * gstiterator.h: Header for GstIterator
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.
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.
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.
22 #ifndef __GST_ITERATOR_H__
23 #define __GST_ITERATOR_H__
25 #include <glib-object.h> /* for GValue in the fold */
26 #include <gst/gstconfig.h>
32 * @GST_ITERATOR_DONE: No more items in the iterator
33 * @GST_ITERATOR_OK: An item was retrieved
34 * @GST_ITERATOR_RESYNC: Datastructure changed while iterating
35 * @GST_ITERATOR_ERROR: An error happened
37 * The result of gst_iterator_next().
40 GST_ITERATOR_DONE = 0,
42 GST_ITERATOR_RESYNC = 2,
43 GST_ITERATOR_ERROR = 3
46 typedef struct _GstIterator GstIterator;
50 * @GST_ITERATOR_ITEM_SKIP: Skip this item
51 * @GST_ITERATOR_ITEM_PASS: Return item
52 * @GST_ITERATOR_ITEM_END: Stop after this item.
54 * The result of a #GstIteratorItemFunction.
57 GST_ITERATOR_ITEM_SKIP = 0,
58 GST_ITERATOR_ITEM_PASS = 1,
59 GST_ITERATOR_ITEM_END = 2
63 * GstIteratorDisposeFunction:
64 * @owner: the owner of the iterator
66 * The function that will be called when a #GList iterator is freed. The
67 * owner of the #GList iterator can then clean up its resources.
69 typedef void (*GstIteratorDisposeFunction) (gpointer owner);
72 * GstIteratorNextFunction:
74 * @result: a pointer to hold the next item
76 * The function that will be called when the next element of the iterator
77 * should be retrieved.
79 * Implementors of a #GstIterator should implement this
80 * function and pass it to the constructor of the custom iterator.
81 * The function will be called with the iterator lock held.
83 * Returns: the result of the operation.
85 typedef GstIteratorResult (*GstIteratorNextFunction) (GstIterator *it, gpointer *result);
87 * GstIteratorItemFunction:
89 * @item: the item being retrieved.
91 * The function that will be called after the next item of the iterator
92 * has been retrieved. This function will typically increase the refcount
93 * of the item or make a copy.
95 * Implementors of a #GstIterator should implement this
96 * function and pass it to the constructor of the custom iterator.
97 * The function will be called with the iterator lock held.
99 * Returns: the result of the operation.
101 typedef GstIteratorItem (*GstIteratorItemFunction) (GstIterator *it, gpointer item);
103 * GstIteratorResyncFunction:
106 * This function will be called whenever a concurrent update happened
107 * to the iterated datastructure. The implementor of the iterator should
108 * restart the iterator from the beginning and clean up any state it might
111 * Implementors of a #GstIterator should implement this
112 * function and pass it to the constructor of the custom iterator.
113 * The function will be called with the iterator lock held.
115 typedef void (*GstIteratorResyncFunction) (GstIterator *it);
117 * GstIteratorFreeFunction:
120 * This function will be called when the iterator is freed.
122 * Implementors of a #GstIterator should implement this
123 * function and pass it to the constructor of the custom iterator.
124 * The function will be called with the iterator lock held.
126 typedef void (*GstIteratorFreeFunction) (GstIterator *it);
129 * GstIteratorFoldFunction:
130 * @item: the item to fold
131 * @ret: a #GValue collecting the result
132 * @user_data: data passed to gst_iterator_fold()
134 * A function to be passed to gst_iterator_fold().
136 * Returns: TRUE if the fold should continue, FALSE if it should stop.
138 typedef gboolean (*GstIteratorFoldFunction) (gpointer item, GValue *ret, gpointer user_data);
142 * @it: the #GstIterator value
144 * Macro to cast to a #GstIterator
146 #define GST_ITERATOR(it) ((GstIterator*)(it))
149 * @it: the #GstIterator to get the lock of
151 * Macro to get the lock protecting the datastructure being iterated.
153 #define GST_ITERATOR_LOCK(it) (GST_ITERATOR(it)->lock)
155 * GST_ITERATOR_COOKIE:
156 * @it: the #GstIterator to get the cookie of
158 * Macro to get the cookie of a #GstIterator. The cookie of the
159 * iterator is the value of the master cookie when the iterator
161 * Whenever the iterator is iterated, the value is compared to the
162 * value of the master cookie. If they are different, a concurrent
163 * modification happened to the iterator and a resync is needed.
165 #define GST_ITERATOR_COOKIE(it) (GST_ITERATOR(it)->cookie)
167 * GST_ITERATOR_ORIG_COOKIE:
168 * @it: the #GstIterator to get the master cookie of
170 * Macro to get a pointer to where the master cookie is stored. The
171 * master cookie protects the structure being iterated and gets updated
172 * whenever the datastructure changes.
174 #define GST_ITERATOR_ORIG_COOKIE(it) (GST_ITERATOR(it)->master_cookie)
178 * @next: The function to get the next item in the iterator
179 * @item: The function to be called for each item retrieved
180 * @resync: The function to call when a resync is needed.
181 * @free: The function to call when the iterator is freed
182 * @pushed: The iterator that is currently pushed with gst_iterator_push()
183 * @type: The type of the object that this iterator will return
184 * @lock: The lock protecting the data structure and the cookie.
185 * @cookie: The cookie; the value of the master_cookie when this iterator was
187 * @master_cookie: A pointer to the master cookie.
189 * #GstIterator base structure. The values of this structure are
190 * protected for subclasses, use the methods to use the #GstIterator.
192 struct _GstIterator {
194 GstIteratorNextFunction next;
195 GstIteratorItemFunction item;
196 GstIteratorResyncFunction resync;
197 GstIteratorFreeFunction free;
199 GstIterator *pushed; /* pushed iterator */
203 guint32 cookie; /* cookie of the iterator */
204 guint32 *master_cookie; /* pointer to guint32 holding the cookie when this
205 iterator was created */
208 gpointer _gst_reserved[GST_PADDING];
211 /* creating iterators */
212 GstIterator* gst_iterator_new (guint size,
215 guint32 *master_cookie,
216 GstIteratorNextFunction next,
217 GstIteratorItemFunction item,
218 GstIteratorResyncFunction resync,
219 GstIteratorFreeFunction free);
221 GstIterator* gst_iterator_new_list (GType type,
223 guint32 *master_cookie,
226 GstIteratorItemFunction item,
227 GstIteratorDisposeFunction free);
229 /* using iterators */
230 GstIteratorResult gst_iterator_next (GstIterator *it, gpointer *elem);
231 void gst_iterator_resync (GstIterator *it);
232 void gst_iterator_free (GstIterator *it);
234 void gst_iterator_push (GstIterator *it, GstIterator *other);
236 /* higher-order functions that operate on iterators */
237 GstIterator* gst_iterator_filter (GstIterator *it, GCompareFunc func,
239 GstIteratorResult gst_iterator_fold (GstIterator *it,
240 GstIteratorFoldFunction func,
241 GValue *ret, gpointer user_data);
242 GstIteratorResult gst_iterator_foreach (GstIterator *it,
243 GFunc func, gpointer user_data);
244 gpointer gst_iterator_find_custom (GstIterator *it, GCompareFunc func,
249 #endif /* __GST_ITERATOR_H__ */