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