Debian Codegraph @

libs/gst/base/gstqueuearray.c

raw
1 /* GStreamer
2 * Copyright (C) 2009 Edward Hervey <[email protected]>
3 * Copyright (C) 2015 Tim-Philipp Müller <[email protected]>
4 *
5 * gstqueuearray.c:
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 /**
24 * SECTION:gstqueuearray
25 * @title: GstQueueArray
26 * @short_description: Array based queue object
27 *
28 * #GstQueueArray is an object that provides standard queue functionality
29 * based on an array instead of linked lists. This reduces the overhead
30 * caused by memory management by a large factor.
31 */
32 #ifdef HAVE_CONFIG_H
33 #include "config.h"
34 #endif
35
36 #include <gst/gst.h>
37 #include "gstqueuearray.h"
38
39 /**
40 * gst_queue_array_new_for_struct: (skip)
41 * @struct_size: Size of each element (e.g. structure) in the array
42 * @initial_size: Initial size of the new queue
43 *
44 * Allocates a new #GstQueueArray object for elements (e.g. structures)
45 * of size @struct_size, with an initial queue size of @initial_size.
46 *
47 * Returns: a new #GstQueueArray object
48 *
49 * Since: 1.6
50 * Deprecated: 1.26: Use #GstVecDeque instead.
51 */
52 GstQueueArray *
53 gst_queue_array_new_for_struct (gsize struct_size, guint initial_size)
54 {
55 return (GstQueueArray *) gst_vec_deque_new_for_struct (struct_size,
56 initial_size);
57 }
58
59 /**
60 * gst_queue_array_new: (skip)
61 * @initial_size: Initial size of the new queue
62 *
63 * Allocates a new #GstQueueArray object with an initial
64 * queue size of @initial_size.
65 *
66 * Returns: a new #GstQueueArray object
67 *
68 * Since: 1.2
69 */
70 GstQueueArray *
71 gst_queue_array_new (guint initial_size)
72 {
73 return (GstQueueArray *) gst_vec_deque_new (initial_size);
74 }
75
76 /**
77 * gst_queue_array_free: (skip)
78 * @array: a #GstQueueArray object
79 *
80 * Frees queue @array and all memory associated to it.
81 *
82 * Since: 1.2
83 * Deprecated: 1.26: Use #GstVecDeque instead.
84 */
85 void
86 gst_queue_array_free (GstQueueArray * array)
87 {
88 gst_vec_deque_free ((GstVecDeque *) array);
89 }
90
91 /**
92 * gst_queue_array_set_clear_func: (skip)
93 * @array: a #GstQueueArray object
94 * @clear_func: a function to clear an element of @array
95 *
96 * Sets a function to clear an element of @array.
97 *
98 * The @clear_func will be called when an element in the array
99 * data segment is removed and when the array is freed and data
100 * segment is deallocated as well. @clear_func will be passed a
101 * pointer to the element to clear, rather than the element itself.
102 *
103 * Note that in contrast with other uses of #GDestroyNotify
104 * functions, @clear_func is expected to clear the contents of
105 * the array element it is given, but not free the element itself.
106 *
107 * Since: 1.16
108 * Deprecated: 1.26: Use #GstVecDeque instead.
109 */
110 void
111 gst_queue_array_set_clear_func (GstQueueArray * array,
112 GDestroyNotify clear_func)
113 {
114 gst_vec_deque_set_clear_func ((GstVecDeque *) array, clear_func);
115 }
116
117 /**
118 * gst_queue_array_clear: (skip)
119 * @array: a #GstQueueArray object
120 *
121 * Clears queue @array and frees all memory associated to it.
122 *
123 * Since: 1.16
124 * Deprecated: 1.26: Use #GstVecDeque instead.
125 */
126 void
127 gst_queue_array_clear (GstQueueArray * array)
128 {
129 gst_vec_deque_clear ((GstVecDeque *) array);
130 }
131
132 /**
133 * gst_queue_array_pop_head_struct: (skip)
134 * @array: a #GstQueueArray object
135 *
136 * Returns the head of the queue @array and removes it from the queue.
137 *
138 * Returns: (nullable): pointer to element or struct, or NULL if @array was empty. The
139 * data pointed to by the returned pointer stays valid only as long as
140 * the queue array is not modified further!
141 *
142 * Since: 1.6
143 * Deprecated: 1.26: Use #GstVecDeque instead.
144 */
145 gpointer
146 gst_queue_array_pop_head_struct (GstQueueArray * array)
147 {
148 return gst_vec_deque_pop_head_struct ((GstVecDeque *) array);
149 }
150
151 /**
152 * gst_queue_array_pop_head: (skip)
153 * @array: a #GstQueueArray object
154 *
155 * Returns and head of the queue @array and removes
156 * it from the queue.
157 *
158 * Returns: The head of the queue
159 *
160 * Since: 1.2
161 * Deprecated: 1.26: Use #GstVecDeque instead.
162 */
163 gpointer
164 gst_queue_array_pop_head (GstQueueArray * array)
165 {
166 return gst_vec_deque_pop_head ((GstVecDeque *) array);
167 }
168
169 /**
170 * gst_queue_array_peek_head_struct: (skip)
171 * @array: a #GstQueueArray object
172 *
173 * Returns the head of the queue @array without removing it from the queue.
174 *
175 * Returns: (nullable): pointer to element or struct, or NULL if @array was empty. The
176 * data pointed to by the returned pointer stays valid only as long as
177 * the queue array is not modified further!
178 *
179 * Since: 1.6
180 * Deprecated: 1.26: Use #GstVecDeque instead.
181 */
182 gpointer
183 gst_queue_array_peek_head_struct (GstQueueArray * array)
184 {
185 return gst_vec_deque_peek_head_struct ((GstVecDeque *) array);
186 }
187
188 /**
189 * gst_queue_array_peek_head: (skip)
190 * @array: a #GstQueueArray object
191 *
192 * Returns the head of the queue @array and does not
193 * remove it from the queue.
194 *
195 * Returns: The head of the queue
196 *
197 * Since: 1.2
198 * Deprecated: 1.26: Use #GstVecDeque instead.
199 */
200 gpointer
201 gst_queue_array_peek_head (GstQueueArray * array)
202 {
203 return gst_vec_deque_peek_head ((GstVecDeque *) array);
204 }
205
206 /**
207 * gst_queue_array_peek_nth: (skip)
208 *
209 * Returns the item at @idx in @array, but does not remove it from the queue.
210 *
211 * Returns: (nullable): The item, or %NULL if @idx was out of bounds
212 *
213 * Since: 1.16
214 * Deprecated: 1.26: Use #GstVecDeque instead.
215 */
216 gpointer
217 gst_queue_array_peek_nth (GstQueueArray * array, guint idx)
218 {
219 return gst_vec_deque_peek_nth ((GstVecDeque *) array, idx);
220 }
221
222 /**
223 * gst_queue_array_peek_nth_struct: (skip)
224 *
225 * Returns the item at @idx in @array, but does not remove it from the queue.
226 *
227 * Returns: (nullable): The item, or %NULL if @idx was out of bounds
228 *
229 * Since: 1.16
230 * Deprecated: 1.26: Use #GstVecDeque instead.
231 */
232 gpointer
233 gst_queue_array_peek_nth_struct (GstQueueArray * array, guint idx)
234 {
235 return gst_vec_deque_peek_nth_struct ((GstVecDeque *) array, idx);
236 }
237
238 /**
239 * gst_queue_array_push_element_tail: (skip)
240 * @array: a #GstQueueArray object
241 * @p_struct: address of element or structure to push to the tail of the queue
242 *
243 * Pushes the element at address @p_struct to the tail of the queue @array
244 * (Copies the contents of a structure of the struct_size specified when
245 * creating the queue into the array).
246 *
247 * Since: 1.6
248 * Deprecated: 1.26: Use #GstVecDeque instead.
249 */
250 void
251 gst_queue_array_push_tail_struct (GstQueueArray * array, gpointer p_struct)
252 {
253 gst_vec_deque_push_tail_struct ((GstVecDeque *) array, p_struct);
254 }
255
256 /**
257 * gst_queue_array_push_tail: (skip)
258 * @array: a #GstQueueArray object
259 * @data: object to push
260 *
261 * Pushes @data to the tail of the queue @array.
262 *
263 * Since: 1.2
264 * Deprecated: 1.26: Use #GstVecDeque instead.
265 */
266 void
267 gst_queue_array_push_tail (GstQueueArray * array, gpointer data)
268 {
269 gst_vec_deque_push_tail ((GstVecDeque *) array, data);
270 }
271
272 /**
273 * gst_queue_array_push_sorted: (skip)
274 * @array: a #GstQueueArray object
275 * @data: object to push
276 * @func: comparison function
277 * @user_data: (nullable): data for comparison function
278 *
279 * Pushes @data to the queue @array, finding the correct position
280 * by comparing @data with each array element using @func.
281 *
282 * This has a time complexity of O(n), so depending on the size of the queue
283 * and expected access patterns, a different data structure might be better.
284 *
285 * Assumes that the array is already sorted. If it is not, make sure
286 * to call gst_queue_array_sort() first.
287 *
288 * Since: 1.24
289 * Deprecated: 1.26: Use #GstVecDeque instead.
290 */
291 void
292 gst_queue_array_push_sorted (GstQueueArray * array, gpointer data,
293 GCompareDataFunc func, gpointer user_data)
294 {
295 gst_vec_deque_push_sorted ((GstVecDeque *) array, data, func, user_data);
296 }
297
298 /**
299 * gst_queue_array_push_sorted_struct: (skip)
300 * @array: a #GstQueueArray object
301 * @p_struct: address of element or structure to push into the queue
302 * @func: comparison function
303 * @user_data: (nullable): data for comparison function
304 *
305 * Pushes the element at address @p_struct into the queue @array
306 * (copying the contents of a structure of the struct_size specified
307 * when creating the queue into the array), finding the correct position
308 * by comparing the element at @p_struct with each element in the array using @func.
309 *
310 * This has a time complexity of O(n), so depending on the size of the queue
311 * and expected access patterns, a different data structure might be better.
312 *
313 * Assumes that the array is already sorted. If it is not, make sure
314 * to call gst_queue_array_sort() first.
315 *
316 * Since: 1.24
317 * Deprecated: 1.26: Use #GstVecDeque instead.
318 */
319 void
320 gst_queue_array_push_sorted_struct (GstQueueArray * array, gpointer p_struct,
321 GCompareDataFunc func, gpointer user_data)
322 {
323 gst_vec_deque_push_sorted_struct ((GstVecDeque *) array, p_struct, func,
324 user_data);
325 }
326
327 /**
328 * gst_queue_array_sort: (skip)
329 * @array: a #GstQueueArray object
330 * @compare_func: comparison function
331 * @user_data: (nullable): data for comparison function
332 *
333 * Sorts the queue @array by comparing elements against each other using
334 * the provided @compare_func.
335 *
336 * Since: 1.24
337 * Deprecated: 1.26: Use #GstVecDeque instead.
338 */
339 void
340 gst_queue_array_sort (GstQueueArray * array, GCompareDataFunc compare_func,
341 gpointer user_data)
342 {
343 gst_vec_deque_sort ((GstVecDeque *) array, compare_func, user_data);
344 }
345
346 /**
347 * gst_queue_array_peek_tail: (skip)
348 * @array: a #GstQueueArray object
349 *
350 * Returns the tail of the queue @array, but does not remove it from the queue.
351 *
352 * Returns: The tail of the queue
353 *
354 * Since: 1.14
355 * Deprecated: 1.26: Use #GstVecDeque instead.
356 */
357 gpointer
358 gst_queue_array_peek_tail (GstQueueArray * array)
359 {
360 return gst_vec_deque_peek_tail ((GstVecDeque *) array);
361 }
362
363 /**
364 * gst_queue_array_peek_tail_struct: (skip)
365 * @array: a #GstQueueArray object
366 *
367 * Returns the tail of the queue @array, but does not remove it from the queue.
368 *
369 * Returns: The tail of the queue
370 *
371 * Since: 1.14
372 * Deprecated: 1.26: Use #GstVecDeque instead.
373 */
374 gpointer
375 gst_queue_array_peek_tail_struct (GstQueueArray * array)
376 {
377 return gst_vec_deque_peek_tail_struct ((GstVecDeque *) array);
378 }
379
380 /**
381 * gst_queue_array_pop_tail: (skip)
382 * @array: a #GstQueueArray object
383 *
384 * Returns the tail of the queue @array and removes
385 * it from the queue.
386 *
387 * Returns: The tail of the queue
388 *
389 * Since: 1.14
390 * Deprecated: 1.26: Use #GstVecDeque instead.
391 */
392 gpointer
393 gst_queue_array_pop_tail (GstQueueArray * array)
394 {
395 return gst_vec_deque_pop_tail ((GstVecDeque *) array);
396 }
397
398 /**
399 * gst_queue_array_pop_tail_struct: (skip)
400 * @array: a #GstQueueArray object
401 *
402 * Returns the tail of the queue @array and removes
403 * it from the queue.
404 *
405 * Returns: The tail of the queue
406 *
407 * Since: 1.14
408 * Deprecated: 1.26: Use #GstVecDeque instead.
409 */
410 gpointer
411 gst_queue_array_pop_tail_struct (GstQueueArray * array)
412 {
413 return gst_vec_deque_pop_tail_struct ((GstVecDeque *) array);
414 }
415
416 /**
417 * gst_queue_array_is_empty: (skip)
418 * @array: a #GstQueueArray object
419 *
420 * Checks if the queue @array is empty.
421 *
422 * Returns: %TRUE if the queue @array is empty
423 *
424 * Since: 1.2
425 * Deprecated: 1.26: Use #GstVecDeque instead.
426 */
427 gboolean
428 gst_queue_array_is_empty (GstQueueArray * array)
429 {
430 return gst_vec_deque_is_empty ((GstVecDeque *) array);
431 }
432
433
434 /**
435 * gst_queue_array_drop_struct: (skip)
436 * @array: a #GstQueueArray object
437 * @idx: index to drop
438 * @p_struct: address into which to store the data of the dropped structure, or NULL
439 *
440 * Drops the queue element at position @idx from queue @array and copies the
441 * data of the element or structure that was removed into @p_struct if
442 * @p_struct is set (not NULL).
443 *
444 * Returns: TRUE on success, or FALSE on error
445 *
446 * Since: 1.6
447 * Deprecated: 1.26: Use #GstVecDeque instead.
448 */
449 gboolean
450 gst_queue_array_drop_struct (GstQueueArray * array, guint idx,
451 gpointer p_struct)
452 {
453 return gst_vec_deque_drop_struct ((GstVecDeque *) array, idx, p_struct);
454 }
455
456 /**
457 * gst_queue_array_drop_element: (skip)
458 * @array: a #GstQueueArray object
459 * @idx: index to drop
460 *
461 * Drops the queue element at position @idx from queue @array.
462 *
463 * Returns: the dropped element
464 *
465 * Since: 1.2
466 * Deprecated: 1.26: Use #GstVecDeque instead.
467 */
468 gpointer
469 gst_queue_array_drop_element (GstQueueArray * array, guint idx)
470 {
471 return gst_vec_deque_drop_element ((GstVecDeque *) array, idx);
472 }
473
474 /**
475 * gst_queue_array_find: (skip)
476 * @array: a #GstQueueArray object
477 * @func: (nullable): comparison function, or %NULL to find @data by value
478 * @data: data for comparison function
479 *
480 * Finds an element in the queue @array, either by comparing every element
481 * with @func or by looking up @data if no compare function @func is provided,
482 * and returning the index of the found element.
483 *
484 * Returns: Index of the found element or -1 if nothing was found.
485 *
486 * Since: 1.2
487 * Deprecated: 1.26: Use #GstVecDeque instead.
488 */
489 guint
490 gst_queue_array_find (GstQueueArray * array, GCompareFunc func, gpointer data)
491 {
492 return gst_vec_deque_find ((GstVecDeque *) array, func, data);
493 }
494
495 /**
496 * gst_queue_array_get_length: (skip)
497 * @array: a #GstQueueArray object
498 *
499 * Returns the length of the queue @array
500 *
501 * Returns: the length of the queue @array.
502 *
503 * Since: 1.2
504 * Deprecated: 1.26: Use #GstVecDeque instead.
505 */
506 guint
507 gst_queue_array_get_length (GstQueueArray * array)
508 {
509 return gst_vec_deque_get_length ((GstVecDeque *) array);
510 }