source: appstream-generator/build/girepo/glib/AsyncQueue.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 14.6 KB
Line 
1/*
2 * Licensed under the GNU Lesser General Public License Version 3
3 *
4 * This library is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the license, or
7 * (at your option) any later version.
8 *
9 * This software is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18// generated automatically - do not change
19
20
21module glib.AsyncQueue;
22
23private import gi.glib;
24public  import gi.glibtypes;
25private import glib.ConstructionException;
26private import glib.TimeVal;
27
28
29/**
30 * The GAsyncQueue struct is an opaque data structure which represents
31 * an asynchronous queue. It should only be accessed through the
32 * g_async_queue_* functions.
33 */
34public class AsyncQueue
35{
36        /** the main Gtk struct */
37        protected GAsyncQueue* gAsyncQueue;
38        protected bool ownedRef;
39
40        /** Get the main Gtk struct */
41        public GAsyncQueue* getAsyncQueueStruct()
42        {
43                return gAsyncQueue;
44        }
45
46        /** the main Gtk struct as a void* */
47        protected void* getStruct()
48        {
49                return cast(void*)gAsyncQueue;
50        }
51
52        /**
53         * Sets our main struct and passes it to the parent class.
54         */
55        public this (GAsyncQueue* gAsyncQueue, bool ownedRef = false)
56        {
57                this.gAsyncQueue = gAsyncQueue;
58                this.ownedRef = ownedRef;
59        }
60
61
62        /**
63         * Returns the length of the queue.
64         *
65         * Actually this function returns the number of data items in
66         * the queue minus the number of waiting threads, so a negative
67         * value means waiting threads, and a positive value means available
68         * entries in the @queue. A return value of 0 could mean n entries
69         * in the queue and n threads waiting. This can happen due to locking
70         * of the queue or due to scheduling.
71         *
72         * Returns: the length of the @queue
73         */
74        public int length()
75        {
76                return g_async_queue_length(gAsyncQueue);
77        }
78
79        /**
80         * Returns the length of the queue.
81         *
82         * Actually this function returns the number of data items in
83         * the queue minus the number of waiting threads, so a negative
84         * value means waiting threads, and a positive value means available
85         * entries in the @queue. A return value of 0 could mean n entries
86         * in the queue and n threads waiting. This can happen due to locking
87         * of the queue or due to scheduling.
88         *
89         * This function must be called while holding the @queue's lock.
90         *
91         * Returns: the length of the @queue.
92         */
93        public int lengthUnlocked()
94        {
95                return g_async_queue_length_unlocked(gAsyncQueue);
96        }
97
98        /**
99         * Acquires the @queue's lock. If another thread is already
100         * holding the lock, this call will block until the lock
101         * becomes available.
102         *
103         * Call g_async_queue_unlock() to drop the lock again.
104         *
105         * While holding the lock, you can only call the
106         * g_async_queue_*_unlocked() functions on @queue. Otherwise,
107         * deadlock may occur.
108         */
109        public void lock()
110        {
111                g_async_queue_lock(gAsyncQueue);
112        }
113
114        /**
115         * Pops data from the @queue. If @queue is empty, this function
116         * blocks until data becomes available.
117         *
118         * Returns: data from the queue
119         */
120        public void* pop()
121        {
122                return g_async_queue_pop(gAsyncQueue);
123        }
124
125        /**
126         * Pops data from the @queue. If @queue is empty, this function
127         * blocks until data becomes available.
128         *
129         * This function must be called while holding the @queue's lock.
130         *
131         * Returns: data from the queue.
132         */
133        public void* popUnlocked()
134        {
135                return g_async_queue_pop_unlocked(gAsyncQueue);
136        }
137
138        /**
139         * Pushes the @data into the @queue. @data must not be %NULL.
140         *
141         * Params:
142         *     data = @data to push into the @queue
143         */
144        public void push(void* data)
145        {
146                g_async_queue_push(gAsyncQueue, data);
147        }
148
149        /**
150         * Pushes the @data into the @queue. @data must not be %NULL.
151         * In contrast to g_async_queue_push(), this function
152         * pushes the new item ahead of the items already in the queue,
153         * so that it will be the next one to be popped off the queue.
154         *
155         * Since: 2.46
156         */
157        public void pushFront(void* item)
158        {
159                g_async_queue_push_front(gAsyncQueue, item);
160        }
161
162        /**
163         * Pushes the @data into the @queue. @data must not be %NULL.
164         * In contrast to g_async_queue_push_unlocked(), this function
165         * pushes the new item ahead of the items already in the queue,
166         * so that it will be the next one to be popped off the queue.
167         *
168         * This function must be called while holding the @queue's lock.
169         *
170         * Since: 2.46
171         */
172        public void pushFrontUnlocked(void* item)
173        {
174                g_async_queue_push_front_unlocked(gAsyncQueue, item);
175        }
176
177        /**
178         * Inserts @data into @queue using @func to determine the new
179         * position.
180         *
181         * This function requires that the @queue is sorted before pushing on
182         * new elements, see g_async_queue_sort().
183         *
184         * This function will lock @queue before it sorts the queue and unlock
185         * it when it is finished.
186         *
187         * For an example of @func see g_async_queue_sort().
188         *
189         * Params:
190         *     data = the @data to push into the @queue
191         *     func = the #GCompareDataFunc is used to sort @queue
192         *     userData = user data passed to @func.
193         *
194         * Since: 2.10
195         */
196        public void pushSorted(void* data, GCompareDataFunc func, void* userData)
197        {
198                g_async_queue_push_sorted(gAsyncQueue, data, func, userData);
199        }
200
201        /**
202         * Inserts @data into @queue using @func to determine the new
203         * position.
204         *
205         * The sort function @func is passed two elements of the @queue.
206         * It should return 0 if they are equal, a negative value if the
207         * first element should be higher in the @queue or a positive value
208         * if the first element should be lower in the @queue than the second
209         * element.
210         *
211         * This function requires that the @queue is sorted before pushing on
212         * new elements, see g_async_queue_sort().
213         *
214         * This function must be called while holding the @queue's lock.
215         *
216         * For an example of @func see g_async_queue_sort().
217         *
218         * Params:
219         *     data = the @data to push into the @queue
220         *     func = the #GCompareDataFunc is used to sort @queue
221         *     userData = user data passed to @func.
222         *
223         * Since: 2.10
224         */
225        public void pushSortedUnlocked(void* data, GCompareDataFunc func, void* userData)
226        {
227                g_async_queue_push_sorted_unlocked(gAsyncQueue, data, func, userData);
228        }
229
230        /**
231         * Pushes the @data into the @queue. @data must not be %NULL.
232         *
233         * This function must be called while holding the @queue's lock.
234         *
235         * Params:
236         *     data = @data to push into the @queue
237         */
238        public void pushUnlocked(void* data)
239        {
240                g_async_queue_push_unlocked(gAsyncQueue, data);
241        }
242
243        /**
244         * Increases the reference count of the asynchronous @queue by 1.
245         * You do not need to hold the lock to call this function.
246         *
247         * Returns: the @queue that was passed in (since 2.6)
248         */
249        public AsyncQueue doref()
250        {
251                auto p = g_async_queue_ref(gAsyncQueue);
252               
253                if(p is null)
254                {
255                        return null;
256                }
257               
258                return new AsyncQueue(cast(GAsyncQueue*) p);
259        }
260
261        /**
262         * Increases the reference count of the asynchronous @queue by 1.
263         *
264         * Deprecated: Reference counting is done atomically.
265         * so g_async_queue_ref() can be used regardless of the @queue's
266         * lock.
267         */
268        public void refUnlocked()
269        {
270                g_async_queue_ref_unlocked(gAsyncQueue);
271        }
272
273        /**
274         * Remove an item from the queue.
275         *
276         * Returns: %TRUE if the item was removed
277         *
278         * Since: 2.46
279         */
280        public bool remove(void* item)
281        {
282                return g_async_queue_remove(gAsyncQueue, item) != 0;
283        }
284
285        /**
286         * Remove an item from the queue.
287         *
288         * This function must be called while holding the @queue's lock.
289         *
290         * Returns: %TRUE if the item was removed
291         *
292         * Since: 2.46
293         */
294        public bool removeUnlocked(void* item)
295        {
296                return g_async_queue_remove_unlocked(gAsyncQueue, item) != 0;
297        }
298
299        /**
300         * Sorts @queue using @func.
301         *
302         * The sort function @func is passed two elements of the @queue.
303         * It should return 0 if they are equal, a negative value if the
304         * first element should be higher in the @queue or a positive value
305         * if the first element should be lower in the @queue than the second
306         * element.
307         *
308         * This function will lock @queue before it sorts the queue and unlock
309         * it when it is finished.
310         *
311         * If you were sorting a list of priority numbers to make sure the
312         * lowest priority would be at the top of the queue, you could use:
313         * |[<!-- language="C" -->
314         * gint32 id1;
315         * gint32 id2;
316         *
317         * id1 = GPOINTER_TO_INT (element1);
318         * id2 = GPOINTER_TO_INT (element2);
319         *
320         * return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);
321         * ]|
322         *
323         * Params:
324         *     func = the #GCompareDataFunc is used to sort @queue
325         *     userData = user data passed to @func
326         *
327         * Since: 2.10
328         */
329        public void sort(GCompareDataFunc func, void* userData)
330        {
331                g_async_queue_sort(gAsyncQueue, func, userData);
332        }
333
334        /**
335         * Sorts @queue using @func.
336         *
337         * The sort function @func is passed two elements of the @queue.
338         * It should return 0 if they are equal, a negative value if the
339         * first element should be higher in the @queue or a positive value
340         * if the first element should be lower in the @queue than the second
341         * element.
342         *
343         * This function must be called while holding the @queue's lock.
344         *
345         * Params:
346         *     func = the #GCompareDataFunc is used to sort @queue
347         *     userData = user data passed to @func
348         *
349         * Since: 2.10
350         */
351        public void sortUnlocked(GCompareDataFunc func, void* userData)
352        {
353                g_async_queue_sort_unlocked(gAsyncQueue, func, userData);
354        }
355
356        /**
357         * Pops data from the @queue. If the queue is empty, blocks until
358         * @end_time or until data becomes available.
359         *
360         * If no data is received before @end_time, %NULL is returned.
361         *
362         * To easily calculate @end_time, a combination of g_get_current_time()
363         * and g_time_val_add() can be used.
364         *
365         * Deprecated: use g_async_queue_timeout_pop().
366         *
367         * Params:
368         *     endTime = a #GTimeVal, determining the final time
369         *
370         * Returns: data from the queue or %NULL, when no data is
371         *     received before @end_time.
372         */
373        public void* timedPop(TimeVal endTime)
374        {
375                return g_async_queue_timed_pop(gAsyncQueue, (endTime is null) ? null : endTime.getTimeValStruct());
376        }
377
378        /**
379         * Pops data from the @queue. If the queue is empty, blocks until
380         * @end_time or until data becomes available.
381         *
382         * If no data is received before @end_time, %NULL is returned.
383         *
384         * To easily calculate @end_time, a combination of g_get_current_time()
385         * and g_time_val_add() can be used.
386         *
387         * This function must be called while holding the @queue's lock.
388         *
389         * Deprecated: use g_async_queue_timeout_pop_unlocked().
390         *
391         * Params:
392         *     endTime = a #GTimeVal, determining the final time
393         *
394         * Returns: data from the queue or %NULL, when no data is
395         *     received before @end_time.
396         */
397        public void* timedPopUnlocked(TimeVal endTime)
398        {
399                return g_async_queue_timed_pop_unlocked(gAsyncQueue, (endTime is null) ? null : endTime.getTimeValStruct());
400        }
401
402        /**
403         * Pops data from the @queue. If the queue is empty, blocks for
404         * @timeout microseconds, or until data becomes available.
405         *
406         * If no data is received before the timeout, %NULL is returned.
407         *
408         * Params:
409         *     timeout = the number of microseconds to wait
410         *
411         * Returns: data from the queue or %NULL, when no data is
412         *     received before the timeout.
413         */
414        public void* timeoutPop(ulong timeout)
415        {
416                return g_async_queue_timeout_pop(gAsyncQueue, timeout);
417        }
418
419        /**
420         * Pops data from the @queue. If the queue is empty, blocks for
421         * @timeout microseconds, or until data becomes available.
422         *
423         * If no data is received before the timeout, %NULL is returned.
424         *
425         * This function must be called while holding the @queue's lock.
426         *
427         * Params:
428         *     timeout = the number of microseconds to wait
429         *
430         * Returns: data from the queue or %NULL, when no data is
431         *     received before the timeout.
432         */
433        public void* timeoutPopUnlocked(ulong timeout)
434        {
435                return g_async_queue_timeout_pop_unlocked(gAsyncQueue, timeout);
436        }
437
438        /**
439         * Tries to pop data from the @queue. If no data is available,
440         * %NULL is returned.
441         *
442         * Returns: data from the queue or %NULL, when no data is
443         *     available immediately.
444         */
445        public void* tryPop()
446        {
447                return g_async_queue_try_pop(gAsyncQueue);
448        }
449
450        /**
451         * Tries to pop data from the @queue. If no data is available,
452         * %NULL is returned.
453         *
454         * This function must be called while holding the @queue's lock.
455         *
456         * Returns: data from the queue or %NULL, when no data is
457         *     available immediately.
458         */
459        public void* tryPopUnlocked()
460        {
461                return g_async_queue_try_pop_unlocked(gAsyncQueue);
462        }
463
464        /**
465         * Releases the queue's lock.
466         *
467         * Calling this function when you have not acquired
468         * the with g_async_queue_lock() leads to undefined
469         * behaviour.
470         */
471        public void unlock()
472        {
473                g_async_queue_unlock(gAsyncQueue);
474        }
475
476        /**
477         * Decreases the reference count of the asynchronous @queue by 1.
478         *
479         * If the reference count went to 0, the @queue will be destroyed
480         * and the memory allocated will be freed. So you are not allowed
481         * to use the @queue afterwards, as it might have disappeared.
482         * You do not need to hold the lock to call this function.
483         */
484        public void unref()
485        {
486                g_async_queue_unref(gAsyncQueue);
487        }
488
489        /**
490         * Decreases the reference count of the asynchronous @queue by 1
491         * and releases the lock. This function must be called while holding
492         * the @queue's lock. If the reference count went to 0, the @queue
493         * will be destroyed and the memory allocated will be freed.
494         *
495         * Deprecated: Reference counting is done atomically.
496         * so g_async_queue_unref() can be used regardless of the @queue's
497         * lock.
498         */
499        public void unrefAndUnlock()
500        {
501                g_async_queue_unref_and_unlock(gAsyncQueue);
502        }
503
504        /**
505         * Creates a new asynchronous queue.
506         *
507         * Returns: a new #GAsyncQueue. Free with g_async_queue_unref()
508         *
509         * Throws: ConstructionException GTK+ fails to create the object.
510         */
511        public this()
512        {
513                auto p = g_async_queue_new();
514               
515                if(p is null)
516                {
517                        throw new ConstructionException("null returned by new");
518                }
519               
520                this(cast(GAsyncQueue*) p);
521        }
522
523        /**
524         * Creates a new asynchronous queue and sets up a destroy notify
525         * function that is used to free any remaining queue items when
526         * the queue is destroyed after the final unref.
527         *
528         * Params:
529         *     itemFreeFunc = function to free queue elements
530         *
531         * Returns: a new #GAsyncQueue. Free with g_async_queue_unref()
532         *
533         * Since: 2.16
534         *
535         * Throws: ConstructionException GTK+ fails to create the object.
536         */
537        public this(GDestroyNotify itemFreeFunc)
538        {
539                auto p = g_async_queue_new_full(itemFreeFunc);
540               
541                if(p is null)
542                {
543                        throw new ConstructionException("null returned by new_full");
544                }
545               
546                this(cast(GAsyncQueue*) p);
547        }
548}
Note: See TracBrowser for help on using the repository browser.