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