1/* GStreamer
2 * Copyright (C) 2004 Wim Taymans <wim@fluendo.com>
3 * Copyright (C) 2011 Sebastian Dröge <sebastian.droege@collabora.co.uk>
4 *
5 * gstiterator.h: Header for GstIterator
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
16 *
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
21 */
22
23#ifndef __GST_ITERATOR_H__
24#define __GST_ITERATOR_H__
25
26#include <glib-object.h> /* for GValue in the fold */
27#include <gst/gstconfig.h>
28
29G_BEGIN_DECLS
30
31#define GST_TYPE_ITERATOR (gst_iterator_get_type ())
32
33/**
34 * GstIteratorResult:
35 * @GST_ITERATOR_DONE: No more items in the iterator
36 * @GST_ITERATOR_OK: An item was retrieved
37 * @GST_ITERATOR_RESYNC: Datastructure changed while iterating
38 * @GST_ITERATOR_ERROR: An error happened
39 *
40 * The result of gst_iterator_next().
41 */
42typedef enum {
43 GST_ITERATOR_DONE = 0,
44 GST_ITERATOR_OK = 1,
45 GST_ITERATOR_RESYNC = 2,
46 GST_ITERATOR_ERROR = 3
47} GstIteratorResult;
48
49typedef struct _GstIterator GstIterator;
50
51/**
52 * GstIteratorItem:
53 * @GST_ITERATOR_ITEM_SKIP: Skip this item
54 * @GST_ITERATOR_ITEM_PASS: Return item
55 * @GST_ITERATOR_ITEM_END: Stop after this item.
56 *
57 * The result of a #GstIteratorItemFunction.
58 */
59typedef enum {
60 GST_ITERATOR_ITEM_SKIP = 0,
61 GST_ITERATOR_ITEM_PASS = 1,
62 GST_ITERATOR_ITEM_END = 2
63} GstIteratorItem;
64
65/**
66 * GstIteratorCopyFunction:
67 * @it: The original iterator
68 * @copy: The copied iterator
69 *
70 * This function will be called when creating a copy of @it and should
71 * create a copy of all custom iterator fields or increase their
72 * reference counts.
73 */
74typedef void (*GstIteratorCopyFunction) (const GstIterator *it, GstIterator *copy);
75
76/**
77 * GstIteratorItemFunction:
78 * @it: the iterator
79 * @item: the item being retrieved.
80 *
81 * The function that will be called after the next item of the iterator
82 * has been retrieved. This function can be used to skip items or stop
83 * the iterator.
84 *
85 * The function will be called with the iterator lock held.
86 *
87 * Returns: the result of the operation.
88 */
89typedef GstIteratorItem (*GstIteratorItemFunction) (GstIterator *it, const GValue * item);
90
91/**
92 * GstIteratorNextFunction:
93 * @it: the iterator
94 * @result: a pointer to hold the next item
95 *
96 * The function that will be called when the next element of the iterator
97 * should be retrieved.
98 *
99 * Implementors of a #GstIterator should implement this
100 * function and pass it to the constructor of the custom iterator.
101 * The function will be called with the iterator lock held.
102 *
103 * Returns: the result of the operation.
104 */
105typedef GstIteratorResult (*GstIteratorNextFunction) (GstIterator *it, GValue *result);
106/**
107 * GstIteratorResyncFunction:
108 * @it: the iterator
109 *
110 * This function will be called whenever a concurrent update happened
111 * to the iterated datastructure. The implementor of the iterator should
112 * restart the iterator from the beginning and clean up any state it might
113 * have.
114 *
115 * Implementors of a #GstIterator should implement this
116 * function and pass it to the constructor of the custom iterator.
117 * The function will be called with the iterator lock held.
118 */
119typedef void (*GstIteratorResyncFunction) (GstIterator *it);
120/**
121 * GstIteratorFreeFunction:
122 * @it: the iterator
123 *
124 * This function will be called when the iterator is freed.
125 *
126 * Implementors of a #GstIterator should implement this
127 * function and pass it to the constructor of the custom iterator.
128 * The function will be called with the iterator lock held.
129 */
130typedef void (*GstIteratorFreeFunction) (GstIterator *it);
131
132/**
133 * GstIteratorForeachFunction:
134 * @item: The item
135 * @user_data: User data
136 *
137 * A function that is called by gst_iterator_foreach() for every element.
138 */
139typedef void (*GstIteratorForeachFunction) (const GValue * item, gpointer user_data);
140
141/**
142 * GstIteratorFoldFunction:
143 * @item: the item to fold
144 * @ret: a #GValue collecting the result
145 * @user_data: data passed to gst_iterator_fold()
146 *
147 * A function to be passed to gst_iterator_fold().
148 *
149 * Returns: %TRUE if the fold should continue, %FALSE if it should stop.
150 */
151typedef gboolean (*GstIteratorFoldFunction) (const GValue * item, GValue * ret, gpointer user_data);
152
153/**
154 * GST_ITERATOR:
155 * @it: the #GstIterator value
156 *
157 * Macro to cast to a #GstIterator
158 */
159#define GST_ITERATOR(it) ((GstIterator*)(it))
160/**
161 * GST_ITERATOR_LOCK:
162 * @it: the #GstIterator to get the lock of
163 *
164 * Macro to get the lock protecting the datastructure being iterated.
165 */
166#define GST_ITERATOR_LOCK(it) (GST_ITERATOR(it)->lock)
167/**
168 * GST_ITERATOR_COOKIE:
169 * @it: the #GstIterator to get the cookie of
170 *
171 * Macro to get the cookie of a #GstIterator. The cookie of the
172 * iterator is the value of the master cookie when the iterator
173 * was created.
174 * Whenever the iterator is iterated, the value is compared to the
175 * value of the master cookie. If they are different, a concurrent
176 * modification happened to the iterator and a resync is needed.
177 */
178#define GST_ITERATOR_COOKIE(it) (GST_ITERATOR(it)->cookie)
179/**
180 * GST_ITERATOR_ORIG_COOKIE:
181 * @it: the #GstIterator to get the master cookie of
182 *
183 * Macro to get a pointer to where the master cookie is stored. The
184 * master cookie protects the structure being iterated and gets updated
185 * whenever the datastructure changes.
186 */
187#define GST_ITERATOR_ORIG_COOKIE(it) (GST_ITERATOR(it)->master_cookie)
188
189/**
190 * GstIterator:
191 * @copy: The function to copy the iterator
192 * @next: The function to get the next item in the iterator
193 * @item: The function to be called for each item retrieved
194 * @resync: The function to call when a resync is needed.
195 * @free: The function to call when the iterator is freed
196 * @pushed: The iterator that is currently pushed with gst_iterator_push()
197 * @type: The type of the object that this iterator will return
198 * @lock: The lock protecting the data structure and the cookie.
199 * @cookie: The cookie; the value of the master_cookie when this iterator was
200 * created.
201 * @master_cookie: A pointer to the master cookie.
202 * @size: the size of the iterator
203 *
204 * #GstIterator base structure. The values of this structure are
205 * protected for subclasses, use the methods to use the #GstIterator.
206 */
207struct _GstIterator {
208 /*< protected >*/
209 GstIteratorCopyFunction copy;
210 GstIteratorNextFunction next;
211 GstIteratorItemFunction item;
212 GstIteratorResyncFunction resync;
213 GstIteratorFreeFunction free;
214
215 GstIterator *pushed; /* pushed iterator */
216
217 GType type;
218 GMutex *lock;
219 guint32 cookie; /* cookie of the iterator */
220 guint32 *master_cookie; /* pointer to guint32 holding the cookie when this
221 iterator was created */
222 guint size;
223
224 /*< private >*/
225 gpointer _gst_reserved[GST_PADDING];
226};
227
228GST_API
229GType gst_iterator_get_type (void);
230
231/* creating iterators */
232
233GST_API
234GstIterator* gst_iterator_new (guint size,
235 GType type,
236 GMutex *lock,
237 guint32 *master_cookie,
238 GstIteratorCopyFunction copy,
239 GstIteratorNextFunction next,
240 GstIteratorItemFunction item,
241 GstIteratorResyncFunction resync,
242 GstIteratorFreeFunction free) G_GNUC_MALLOC;
243GST_API
244GstIterator* gst_iterator_new_list (GType type,
245 GMutex *lock,
246 guint32 *master_cookie,
247 GList **list,
248 GObject * owner,
249 GstIteratorItemFunction item) G_GNUC_MALLOC;
250GST_API
251GstIterator* gst_iterator_new_single (GType type,
252 const GValue * object) G_GNUC_MALLOC;
253GST_API
254GstIterator* gst_iterator_copy (const GstIterator *it) G_GNUC_MALLOC;
255
256/* using iterators */
257
258GST_API
259GstIteratorResult gst_iterator_next (GstIterator *it, GValue * elem);
260
261GST_API
262void gst_iterator_resync (GstIterator *it);
263
264GST_API
265void gst_iterator_free (GstIterator *it);
266
267GST_API
268void gst_iterator_push (GstIterator *it, GstIterator *other);
269
270/* higher-order functions that operate on iterators */
271
272GST_API
273GstIterator* gst_iterator_filter (GstIterator *it, GCompareFunc func,
274 const GValue * user_data) G_GNUC_MALLOC;
275GST_API
276GstIteratorResult gst_iterator_fold (GstIterator *it,
277 GstIteratorFoldFunction func,
278 GValue *ret, gpointer user_data);
279GST_API
280GstIteratorResult gst_iterator_foreach (GstIterator *it,
281 GstIteratorForeachFunction func, gpointer user_data);
282GST_API
283gboolean gst_iterator_find_custom (GstIterator *it, GCompareFunc func,
284 GValue *elem, gpointer user_data);
285
286G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstIterator, gst_iterator_free)
287
288G_END_DECLS
289
290#endif /* __GST_ITERATOR_H__ */
291

source code of include/gstreamer-1.0/gst/gstiterator.h