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 }