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