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  * Conversion parameters:
26  * inFile  = glib-Asynchronous-Queues.html
27  * outPack = glib
28  * outFile = AsyncQueue
29  * strct   = GAsyncQueue
30  * realStrct=
31  * ctorStrct=
32  * clss    = AsyncQueue
33  * interf  = 
34  * class Code: No
35  * interface Code: No
36  * template for:
37  * extend  = 
38  * implements:
39  * prefixes:
40  * 	- g_async_queue_
41  * omit structs:
42  * omit prefixes:
43  * omit code:
44  * omit signals:
45  * imports:
46  * structWrap:
47  * 	- GAsyncQueue* -> AsyncQueue
48  * module aliases:
49  * local aliases:
50  * overrides:
51  */
52 
53 module glib.AsyncQueue;
54 
55 public  import gtkc.glibtypes;
56 
57 private import gtkc.glib;
58 private import glib.ConstructionException;
59 
60 
61 
62 
63 /**
64  * Often you need to communicate between different threads. In general
65  * it's safer not to do this by shared memory, but by explicit message
66  * passing. These messages only make sense asynchronously for
67  * multi-threaded applications though, as a synchronous operation could
68  * as well be done in the same thread.
69  *
70  * Asynchronous queues are an exception from most other GLib data
71  * structures, as they can be used simultaneously from multiple threads
72  * without explicit locking and they bring their own builtin reference
73  * counting. This is because the nature of an asynchronous queue is that
74  * it will always be used by at least 2 concurrent threads.
75  *
76  * For using an asynchronous queue you first have to create one with
77  * g_async_queue_new(). GAsyncQueue structs are reference counted,
78  * use g_async_queue_ref() and g_async_queue_unref() to manage your
79  * references.
80  *
81  * A thread which wants to send a message to that queue simply calls
82  * g_async_queue_push() to push the message to the queue.
83  *
84  * A thread which is expecting messages from an asynchronous queue
85  * simply calls g_async_queue_pop() for that queue. If no message is
86  * available in the queue at that point, the thread is now put to sleep
87  * until a message arrives. The message will be removed from the queue
88  * and returned. The functions g_async_queue_try_pop() and
89  * g_async_queue_timeout_pop() can be used to only check for the presence
90  * of messages or to only wait a certain time for messages respectively.
91  *
92  * For almost every function there exist two variants, one that locks
93  * the queue and one that doesn't. That way you can hold the queue lock
94  * (acquire it with g_async_queue_lock() and release it with
95  * g_async_queue_unlock()) over multiple queue accessing instructions.
96  * This can be necessary to ensure the integrity of the queue, but should
97  * only be used when really necessary, as it can make your life harder
98  * if used unwisely. Normally you should only use the locking function
99  * variants (those without the _unlocked suffix).
100  *
101  * In many cases, it may be more convenient to use GThreadPool when
102  * you need to distribute work to a set of worker threads instead of
103  * using GAsyncQueue manually. GThreadPool uses a GAsyncQueue
104  * internally.
105  */
106 public class AsyncQueue
107 {
108 	
109 	/** the main Gtk struct */
110 	protected GAsyncQueue* gAsyncQueue;
111 	
112 	
113 	/** Get the main Gtk struct */
114 	public GAsyncQueue* getAsyncQueueStruct()
115 	{
116 		return gAsyncQueue;
117 	}
118 	
119 	
120 	/** the main Gtk struct as a void* */
121 	protected void* getStruct()
122 	{
123 		return cast(void*)gAsyncQueue;
124 	}
125 	
126 	/**
127 	 * Sets our main struct and passes it to the parent class
128 	 */
129 	public this (GAsyncQueue* gAsyncQueue)
130 	{
131 		this.gAsyncQueue = gAsyncQueue;
132 	}
133 	
134 	/**
135 	 */
136 	
137 	/**
138 	 * Creates a new asynchronous queue.
139 	 * Throws: ConstructionException GTK+ fails to create the object.
140 	 */
141 	public this ()
142 	{
143 		// GAsyncQueue * g_async_queue_new (void);
144 		auto p = g_async_queue_new();
145 		if(p is null)
146 		{
147 			throw new ConstructionException("null returned by g_async_queue_new()");
148 		}
149 		this(cast(GAsyncQueue*) p);
150 	}
151 	
152 	/**
153 	 * Creates a new asynchronous queue and sets up a destroy notify
154 	 * function that is used to free any remaining queue items when
155 	 * the queue is destroyed after the final unref.
156 	 * Since 2.16
157 	 * Params:
158 	 * itemFreeFunc = function to free queue elements
159 	 * Throws: ConstructionException GTK+ fails to create the object.
160 	 */
161 	public this (GDestroyNotify itemFreeFunc)
162 	{
163 		// GAsyncQueue * g_async_queue_new_full (GDestroyNotify item_free_func);
164 		auto p = g_async_queue_new_full(itemFreeFunc);
165 		if(p is null)
166 		{
167 			throw new ConstructionException("null returned by g_async_queue_new_full(itemFreeFunc)");
168 		}
169 		this(cast(GAsyncQueue*) p);
170 	}
171 	
172 	/**
173 	 * Increases the reference count of the asynchronous queue by 1.
174 	 * You do not need to hold the lock to call this function.
175 	 * Returns: the queue that was passed in (since 2.6)
176 	 */
177 	public AsyncQueue doref()
178 	{
179 		// GAsyncQueue * g_async_queue_ref (GAsyncQueue *queue);
180 		auto p = g_async_queue_ref(gAsyncQueue);
181 		
182 		if(p is null)
183 		{
184 			return null;
185 		}
186 		
187 		return new AsyncQueue(cast(GAsyncQueue*) p);
188 	}
189 	
190 	/**
191 	 * Decreases the reference count of the asynchronous queue by 1.
192 	 * If the reference count went to 0, the queue will be destroyed
193 	 * and the memory allocated will be freed. So you are not allowed
194 	 * to use the queue afterwards, as it might have disappeared.
195 	 * You do not need to hold the lock to call this function.
196 	 */
197 	public void unref()
198 	{
199 		// void g_async_queue_unref (GAsyncQueue *queue);
200 		g_async_queue_unref(gAsyncQueue);
201 	}
202 	
203 	/**
204 	 * Pushes the data into the queue. data must not be NULL.
205 	 * Params:
206 	 * data = data to push into the queue
207 	 */
208 	public void push(void* data)
209 	{
210 		// void g_async_queue_push (GAsyncQueue *queue,  gpointer data);
211 		g_async_queue_push(gAsyncQueue, data);
212 	}
213 	
214 	/**
215 	 * Inserts data into queue using func to determine the new
216 	 * position.
217 	 * This function requires that the queue is sorted before pushing on
218 	 * new elements, see g_async_queue_sort().
219 	 * This function will lock queue before it sorts the queue and unlock
220 	 * it when it is finished.
221 	 * For an example of func see g_async_queue_sort().
222 	 * Since 2.10
223 	 * Params:
224 	 * data = the data to push into the queue
225 	 * func = the GCompareDataFunc is used to sort queue
226 	 * userData = user data passed to func.
227 	 */
228 	public void pushSorted(void* data, GCompareDataFunc func, void* userData)
229 	{
230 		// void g_async_queue_push_sorted (GAsyncQueue *queue,  gpointer data,  GCompareDataFunc func,  gpointer user_data);
231 		g_async_queue_push_sorted(gAsyncQueue, data, func, userData);
232 	}
233 	
234 	/**
235 	 * Pops data from the queue. If queue is empty, this function
236 	 * blocks until data becomes available.
237 	 * Returns: data from the queue
238 	 */
239 	public void* pop()
240 	{
241 		// gpointer g_async_queue_pop (GAsyncQueue *queue);
242 		return g_async_queue_pop(gAsyncQueue);
243 	}
244 	
245 	/**
246 	 * Tries to pop data from the queue. If no data is available,
247 	 * NULL is returned.
248 	 * Returns: data from the queue or NULL, when no data is available immediately.
249 	 */
250 	public void* tryPop()
251 	{
252 		// gpointer g_async_queue_try_pop (GAsyncQueue *queue);
253 		return g_async_queue_try_pop(gAsyncQueue);
254 	}
255 	
256 	/**
257 	 * Pops data from the queue. If the queue is empty, blocks for
258 	 * timeout microseconds, or until data becomes available.
259 	 * If no data is received before the timeout, NULL is returned.
260 	 * Params:
261 	 * timeout = the number of microseconds to wait
262 	 * Returns: data from the queue or NULL, when no data is received before the timeout.
263 	 */
264 	public void* timeoutPop(ulong timeout)
265 	{
266 		// gpointer g_async_queue_timeout_pop (GAsyncQueue *queue,  guint64 timeout);
267 		return g_async_queue_timeout_pop(gAsyncQueue, timeout);
268 	}
269 	
270 	/**
271 	 * Returns the length of the queue.
272 	 * Actually this function returns the number of data items in
273 	 * the queue minus the number of waiting threads, so a negative
274 	 * value means waiting threads, and a positive value means available
275 	 * entries in the queue. A return value of 0 could mean n entries
276 	 * in the queue and n threads waiting. This can happen due to locking
277 	 * of the queue or due to scheduling.
278 	 * Returns: the length of the queue
279 	 */
280 	public int length()
281 	{
282 		// gint g_async_queue_length (GAsyncQueue *queue);
283 		return g_async_queue_length(gAsyncQueue);
284 	}
285 	
286 	/**
287 	 * Sorts queue using func.
288 	 * The sort function func is passed two elements of the queue.
289 	 * It should return 0 if they are equal, a negative value if the
290 	 * first element should be higher in the queue or a positive value
291 	 * if the first element should be lower in the queue than the second
292 	 * element.
293 	 * This function will lock queue before it sorts the queue and unlock
294 	 * it when it is finished.
295 	 * If you were sorting a list of priority numbers to make sure the
296 	 * Since 2.10
297 	 * Params:
298 	 * func = the GCompareDataFunc is used to sort queue
299 	 * userData = user data passed to func
300 	 */
301 	public void sort(GCompareDataFunc func, void* userData)
302 	{
303 		// void g_async_queue_sort (GAsyncQueue *queue,  GCompareDataFunc func,  gpointer user_data);
304 		g_async_queue_sort(gAsyncQueue, func, userData);
305 	}
306 	
307 	/**
308 	 * Acquires the queue's lock. If another thread is already
309 	 * holding the lock, this call will block until the lock
310 	 * becomes available.
311 	 * Call g_async_queue_unlock() to drop the lock again.
312 	 * While holding the lock, you can only call the
313 	 * g_async_queue_*_unlocked() functions
314 	 * on queue. Otherwise, deadlock may occur.
315 	 */
316 	public void lock()
317 	{
318 		// void g_async_queue_lock (GAsyncQueue *queue);
319 		g_async_queue_lock(gAsyncQueue);
320 	}
321 	
322 	/**
323 	 * Releases the queue's lock.
324 	 * Calling this function when you have not acquired
325 	 * the with g_async_queue_lock() leads to undefined
326 	 * behaviour.
327 	 */
328 	public void unlock()
329 	{
330 		// void g_async_queue_unlock (GAsyncQueue *queue);
331 		g_async_queue_unlock(gAsyncQueue);
332 	}
333 	
334 	/**
335 	 * Warning
336 	 * g_async_queue_ref_unlocked has been deprecated since version 2.8 and should not be used in newly-written code. Reference counting is done atomically.
337 	 * so g_async_queue_ref() can be used regardless of the queue's
338 	 * lock.
339 	 * Increases the reference count of the asynchronous queue by 1.
340 	 */
341 	public void refUnlocked()
342 	{
343 		// void g_async_queue_ref_unlocked (GAsyncQueue *queue);
344 		g_async_queue_ref_unlocked(gAsyncQueue);
345 	}
346 	
347 	/**
348 	 * Warning
349 	 * g_async_queue_unref_and_unlock has been deprecated since version 2.8 and should not be used in newly-written code. Reference counting is done atomically.
350 	 * so g_async_queue_unref() can be used regardless of the queue's
351 	 * lock.
352 	 * Decreases the reference count of the asynchronous queue by 1
353 	 * and releases the lock. This function must be called while holding
354 	 * the queue's lock. If the reference count went to 0, the queue
355 	 * will be destroyed and the memory allocated will be freed.
356 	 */
357 	public void unrefAndUnlock()
358 	{
359 		// void g_async_queue_unref_and_unlock (GAsyncQueue *queue);
360 		g_async_queue_unref_and_unlock(gAsyncQueue);
361 	}
362 	
363 	/**
364 	 * Pushes the data into the queue. data must not be NULL.
365 	 * This function must be called while holding the queue's lock.
366 	 * Params:
367 	 * data = data to push into the queue
368 	 */
369 	public void pushUnlocked(void* data)
370 	{
371 		// void g_async_queue_push_unlocked (GAsyncQueue *queue,  gpointer data);
372 		g_async_queue_push_unlocked(gAsyncQueue, data);
373 	}
374 	
375 	/**
376 	 * Inserts data into queue using func to determine the new
377 	 * position.
378 	 * The sort function func is passed two elements of the queue.
379 	 * It should return 0 if they are equal, a negative value if the
380 	 * first element should be higher in the queue or a positive value
381 	 * if the first element should be lower in the queue than the second
382 	 * element.
383 	 * This function requires that the queue is sorted before pushing on
384 	 * new elements, see g_async_queue_sort().
385 	 * This function must be called while holding the queue's lock.
386 	 * For an example of func see g_async_queue_sort().
387 	 * Since 2.10
388 	 * Params:
389 	 * data = the data to push into the queue
390 	 * func = the GCompareDataFunc is used to sort queue
391 	 * userData = user data passed to func.
392 	 */
393 	public void pushSortedUnlocked(void* data, GCompareDataFunc func, void* userData)
394 	{
395 		// void g_async_queue_push_sorted_unlocked (GAsyncQueue *queue,  gpointer data,  GCompareDataFunc func,  gpointer user_data);
396 		g_async_queue_push_sorted_unlocked(gAsyncQueue, data, func, userData);
397 	}
398 	
399 	/**
400 	 * Pops data from the queue. If queue is empty, this function
401 	 * blocks until data becomes available.
402 	 * This function must be called while holding the queue's lock.
403 	 * Returns: data from the queue.
404 	 */
405 	public void* popUnlocked()
406 	{
407 		// gpointer g_async_queue_pop_unlocked (GAsyncQueue *queue);
408 		return g_async_queue_pop_unlocked(gAsyncQueue);
409 	}
410 	
411 	/**
412 	 * Tries to pop data from the queue. If no data is available,
413 	 * NULL is returned.
414 	 * This function must be called while holding the queue's lock.
415 	 * Returns: data from the queue or NULL, when no data is available immediately.
416 	 */
417 	public void* tryPopUnlocked()
418 	{
419 		// gpointer g_async_queue_try_pop_unlocked (GAsyncQueue *queue);
420 		return g_async_queue_try_pop_unlocked(gAsyncQueue);
421 	}
422 	
423 	/**
424 	 * Pops data from the queue. If the queue is empty, blocks for
425 	 * timeout microseconds, or until data becomes available.
426 	 * If no data is received before the timeout, NULL is returned.
427 	 * This function must be called while holding the queue's lock.
428 	 * Params:
429 	 * timeout = the number of microseconds to wait
430 	 * Returns: data from the queue or NULL, when no data is received before the timeout.
431 	 */
432 	public void* timeoutPopUnlocked(ulong timeout)
433 	{
434 		// gpointer g_async_queue_timeout_pop_unlocked (GAsyncQueue *queue,  guint64 timeout);
435 		return g_async_queue_timeout_pop_unlocked(gAsyncQueue, timeout);
436 	}
437 	
438 	/**
439 	 * Returns the length of the queue.
440 	 * Actually this function returns the number of data items in
441 	 * the queue minus the number of waiting threads, so a negative
442 	 * value means waiting threads, and a positive value means available
443 	 * entries in the queue. A return value of 0 could mean n entries
444 	 * in the queue and n threads waiting. This can happen due to locking
445 	 * of the queue or due to scheduling.
446 	 * This function must be called while holding the queue's lock.
447 	 * Returns: the length of the queue.
448 	 */
449 	public int lengthUnlocked()
450 	{
451 		// gint g_async_queue_length_unlocked (GAsyncQueue *queue);
452 		return g_async_queue_length_unlocked(gAsyncQueue);
453 	}
454 	
455 	/**
456 	 * Sorts queue using func.
457 	 * The sort function func is passed two elements of the queue.
458 	 * It should return 0 if they are equal, a negative value if the
459 	 * first element should be higher in the queue or a positive value
460 	 * if the first element should be lower in the queue than the second
461 	 * element.
462 	 * This function must be called while holding the queue's lock.
463 	 * Since 2.10
464 	 * Params:
465 	 * func = the GCompareDataFunc is used to sort queue
466 	 * userData = user data passed to func
467 	 */
468 	public void sortUnlocked(GCompareDataFunc func, void* userData)
469 	{
470 		// void g_async_queue_sort_unlocked (GAsyncQueue *queue,  GCompareDataFunc func,  gpointer user_data);
471 		g_async_queue_sort_unlocked(gAsyncQueue, func, userData);
472 	}
473 	
474 	/**
475 	 * Warning
476 	 * g_async_queue_timed_pop is deprecated and should not be used in newly-written code. use g_async_queue_timeout_pop().
477 	 * Pops data from the queue. If the queue is empty, blocks until
478 	 * end_time or until data becomes available.
479 	 * If no data is received before end_time, NULL is returned.
480 	 * To easily calculate end_time, a combination of g_get_current_time()
481 	 * and g_time_val_add() can be used.
482 	 * Params:
483 	 * endTime = a GTimeVal, determining the final time
484 	 * Returns: data from the queue or NULL, when no data is received before end_time.
485 	 */
486 	public void* timedPop(ref GTimeVal endTime)
487 	{
488 		// gpointer g_async_queue_timed_pop (GAsyncQueue *queue,  GTimeVal *end_time);
489 		return g_async_queue_timed_pop(gAsyncQueue, &endTime);
490 	}
491 	
492 	/**
493 	 * Warning
494 	 * g_async_queue_timed_pop_unlocked is deprecated and should not be used in newly-written code. use g_async_queue_timeout_pop_unlocked().
495 	 * Pops data from the queue. If the queue is empty, blocks until
496 	 * end_time or until data becomes available.
497 	 * If no data is received before end_time, NULL is returned.
498 	 * To easily calculate end_time, a combination of g_get_current_time()
499 	 * and g_time_val_add() can be used.
500 	 * This function must be called while holding the queue's lock.
501 	 * Params:
502 	 * endTime = a GTimeVal, determining the final time
503 	 * Returns: data from the queue or NULL, when no data is received before end_time.
504 	 */
505 	public void* timedPopUnlocked(ref GTimeVal endTime)
506 	{
507 		// gpointer g_async_queue_timed_pop_unlocked (GAsyncQueue *queue,  GTimeVal *end_time);
508 		return g_async_queue_timed_pop_unlocked(gAsyncQueue, &endTime);
509 	}
510 }