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 * Inserts @data into @queue using @func to determine the new 155 * position. 156 * 157 * This function requires that the @queue is sorted before pushing on 158 * new elements, see g_async_queue_sort(). 159 * 160 * This function will lock @queue before it sorts the queue and unlock 161 * it when it is finished. 162 * 163 * For an example of @func see g_async_queue_sort(). 164 * 165 * Params: 166 * data = the @data to push into the @queue 167 * func = the #GCompareDataFunc is used to sort @queue 168 * userData = user data passed to @func. 169 * 170 * Since: 2.10 171 */ 172 public void pushSorted(void* data, GCompareDataFunc func, void* userData) 173 { 174 g_async_queue_push_sorted(gAsyncQueue, data, func, userData); 175 } 176 177 /** 178 * Inserts @data into @queue using @func to determine the new 179 * position. 180 * 181 * The sort function @func is passed two elements of the @queue. 182 * It should return 0 if they are equal, a negative value if the 183 * first element should be higher in the @queue or a positive value 184 * if the first element should be lower in the @queue than the second 185 * element. 186 * 187 * This function requires that the @queue is sorted before pushing on 188 * new elements, see g_async_queue_sort(). 189 * 190 * This function must be called while holding the @queue's lock. 191 * 192 * For an example of @func see g_async_queue_sort(). 193 * 194 * Params: 195 * data = the @data to push into the @queue 196 * func = the #GCompareDataFunc is used to sort @queue 197 * userData = user data passed to @func. 198 * 199 * Since: 2.10 200 */ 201 public void pushSortedUnlocked(void* data, GCompareDataFunc func, void* userData) 202 { 203 g_async_queue_push_sorted_unlocked(gAsyncQueue, data, func, userData); 204 } 205 206 /** 207 * Pushes the @data into the @queue. @data must not be %NULL. 208 * 209 * This function must be called while holding the @queue's lock. 210 * 211 * Params: 212 * data = @data to push into the @queue 213 */ 214 public void pushUnlocked(void* data) 215 { 216 g_async_queue_push_unlocked(gAsyncQueue, data); 217 } 218 219 /** 220 * Increases the reference count of the asynchronous @queue by 1. 221 * You do not need to hold the lock to call this function. 222 * 223 * Return: the @queue that was passed in (since 2.6) 224 */ 225 public AsyncQueue doref() 226 { 227 auto p = g_async_queue_ref(gAsyncQueue); 228 229 if(p is null) 230 { 231 return null; 232 } 233 234 return new AsyncQueue(cast(GAsyncQueue*) p); 235 } 236 237 /** 238 * Increases the reference count of the asynchronous @queue by 1. 239 * 240 * Deprecated: Reference counting is done atomically. 241 * so g_async_queue_ref() can be used regardless of the @queue's 242 * lock. 243 */ 244 public void refUnlocked() 245 { 246 g_async_queue_ref_unlocked(gAsyncQueue); 247 } 248 249 /** 250 * Sorts @queue using @func. 251 * 252 * The sort function @func is passed two elements of the @queue. 253 * It should return 0 if they are equal, a negative value if the 254 * first element should be higher in the @queue or a positive value 255 * if the first element should be lower in the @queue than the second 256 * element. 257 * 258 * This function will lock @queue before it sorts the queue and unlock 259 * it when it is finished. 260 * 261 * If you were sorting a list of priority numbers to make sure the 262 * lowest priority would be at the top of the queue, you could use: 263 * |[<!-- language="C" --> 264 * gint32 id1; 265 * gint32 id2; 266 * 267 * id1 = GPOINTER_TO_INT (element1); 268 * id2 = GPOINTER_TO_INT (element2); 269 * 270 * return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1); 271 * ]| 272 * 273 * Params: 274 * func = the #GCompareDataFunc is used to sort @queue 275 * userData = user data passed to @func 276 * 277 * Since: 2.10 278 */ 279 public void sort(GCompareDataFunc func, void* userData) 280 { 281 g_async_queue_sort(gAsyncQueue, func, userData); 282 } 283 284 /** 285 * Sorts @queue using @func. 286 * 287 * The sort function @func is passed two elements of the @queue. 288 * It should return 0 if they are equal, a negative value if the 289 * first element should be higher in the @queue or a positive value 290 * if the first element should be lower in the @queue than the second 291 * element. 292 * 293 * This function must be called while holding the @queue's lock. 294 * 295 * Params: 296 * func = the #GCompareDataFunc is used to sort @queue 297 * userData = user data passed to @func 298 * 299 * Since: 2.10 300 */ 301 public void sortUnlocked(GCompareDataFunc func, void* userData) 302 { 303 g_async_queue_sort_unlocked(gAsyncQueue, func, userData); 304 } 305 306 /** 307 * Pops data from the @queue. If the queue is empty, blocks until 308 * @end_time or until data becomes available. 309 * 310 * If no data is received before @end_time, %NULL is returned. 311 * 312 * To easily calculate @end_time, a combination of g_get_current_time() 313 * and g_time_val_add() can be used. 314 * 315 * Deprecated: use g_async_queue_timeout_pop(). 316 * 317 * Params: 318 * endTime = a #GTimeVal, determining the final time 319 * 320 * Return: data from the queue or %NULL, when no data is 321 * received before @end_time. 322 */ 323 public void* timedPop(TimeVal endTime) 324 { 325 return g_async_queue_timed_pop(gAsyncQueue, (endTime is null) ? null : endTime.getTimeValStruct()); 326 } 327 328 /** 329 * Pops data from the @queue. If the queue is empty, blocks until 330 * @end_time or until data becomes available. 331 * 332 * If no data is received before @end_time, %NULL is returned. 333 * 334 * To easily calculate @end_time, a combination of g_get_current_time() 335 * and g_time_val_add() can be used. 336 * 337 * This function must be called while holding the @queue's lock. 338 * 339 * Deprecated: use g_async_queue_timeout_pop_unlocked(). 340 * 341 * Params: 342 * endTime = a #GTimeVal, determining the final time 343 * 344 * Return: data from the queue or %NULL, when no data is 345 * received before @end_time. 346 */ 347 public void* timedPopUnlocked(TimeVal endTime) 348 { 349 return g_async_queue_timed_pop_unlocked(gAsyncQueue, (endTime is null) ? null : endTime.getTimeValStruct()); 350 } 351 352 /** 353 * Pops data from the @queue. If the queue is empty, blocks for 354 * @timeout microseconds, or until data becomes available. 355 * 356 * If no data is received before the timeout, %NULL is returned. 357 * 358 * Params: 359 * timeout = the number of microseconds to wait 360 * 361 * Return: data from the queue or %NULL, when no data is 362 * received before the timeout. 363 */ 364 public void* timeoutPop(ulong timeout) 365 { 366 return g_async_queue_timeout_pop(gAsyncQueue, timeout); 367 } 368 369 /** 370 * Pops data from the @queue. If the queue is empty, blocks for 371 * @timeout microseconds, or until data becomes available. 372 * 373 * If no data is received before the timeout, %NULL is returned. 374 * 375 * This function must be called while holding the @queue's lock. 376 * 377 * Params: 378 * timeout = the number of microseconds to wait 379 * 380 * Return: data from the queue or %NULL, when no data is 381 * received before the timeout. 382 */ 383 public void* timeoutPopUnlocked(ulong timeout) 384 { 385 return g_async_queue_timeout_pop_unlocked(gAsyncQueue, timeout); 386 } 387 388 /** 389 * Tries to pop data from the @queue. If no data is available, 390 * %NULL is returned. 391 * 392 * Return: data from the queue or %NULL, when no data is 393 * available immediately. 394 */ 395 public void* tryPop() 396 { 397 return g_async_queue_try_pop(gAsyncQueue); 398 } 399 400 /** 401 * Tries to pop data from the @queue. If no data is available, 402 * %NULL is returned. 403 * 404 * This function must be called while holding the @queue's lock. 405 * 406 * Return: data from the queue or %NULL, when no data is 407 * available immediately. 408 */ 409 public void* tryPopUnlocked() 410 { 411 return g_async_queue_try_pop_unlocked(gAsyncQueue); 412 } 413 414 /** 415 * Releases the queue's lock. 416 * 417 * Calling this function when you have not acquired 418 * the with g_async_queue_lock() leads to undefined 419 * behaviour. 420 */ 421 public void unlock() 422 { 423 g_async_queue_unlock(gAsyncQueue); 424 } 425 426 /** 427 * Decreases the reference count of the asynchronous @queue by 1. 428 * 429 * If the reference count went to 0, the @queue will be destroyed 430 * and the memory allocated will be freed. So you are not allowed 431 * to use the @queue afterwards, as it might have disappeared. 432 * You do not need to hold the lock to call this function. 433 */ 434 public void unref() 435 { 436 g_async_queue_unref(gAsyncQueue); 437 } 438 439 /** 440 * Decreases the reference count of the asynchronous @queue by 1 441 * and releases the lock. This function must be called while holding 442 * the @queue's lock. If the reference count went to 0, the @queue 443 * will be destroyed and the memory allocated will be freed. 444 * 445 * Deprecated: Reference counting is done atomically. 446 * so g_async_queue_unref() can be used regardless of the @queue's 447 * lock. 448 */ 449 public void unrefAndUnlock() 450 { 451 g_async_queue_unref_and_unlock(gAsyncQueue); 452 } 453 454 /** 455 * Creates a new asynchronous queue. 456 * 457 * Return: a new #GAsyncQueue. Free with g_async_queue_unref() 458 * 459 * Throws: ConstructionException GTK+ fails to create the object. 460 */ 461 public this() 462 { 463 auto p = g_async_queue_new(); 464 465 if(p is null) 466 { 467 throw new ConstructionException("null returned by new"); 468 } 469 470 this(cast(GAsyncQueue*) p); 471 } 472 473 /** 474 * Creates a new asynchronous queue and sets up a destroy notify 475 * function that is used to free any remaining queue items when 476 * the queue is destroyed after the final unref. 477 * 478 * Params: 479 * itemFreeFunc = function to free queue elements 480 * 481 * Return: a new #GAsyncQueue. Free with g_async_queue_unref() 482 * 483 * Since: 2.16 484 * 485 * Throws: ConstructionException GTK+ fails to create the object. 486 */ 487 public this(GDestroyNotify itemFreeFunc) 488 { 489 auto p = g_async_queue_new_full(itemFreeFunc); 490 491 if(p is null) 492 { 493 throw new ConstructionException("null returned by new_full"); 494 } 495 496 this(cast(GAsyncQueue*) p); 497 } 498 }