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.MainContext; 26 27 private import glib.Cond; 28 private import glib.ConstructionException; 29 private import glib.Mutex; 30 private import glib.Source; 31 private import gtkc.glib; 32 public import gtkc.glibtypes; 33 private import gtkd.Loader; 34 35 36 /** 37 * The `GMainContext` struct is an opaque data 38 * type representing a set of sources to be handled in a main loop. 39 */ 40 public class MainContext 41 { 42 /** the main Gtk struct */ 43 protected GMainContext* gMainContext; 44 protected bool ownedRef; 45 46 /** Get the main Gtk struct */ 47 public GMainContext* getMainContextStruct(bool transferOwnership = false) 48 { 49 if (transferOwnership) 50 ownedRef = false; 51 return gMainContext; 52 } 53 54 /** the main Gtk struct as a void* */ 55 protected void* getStruct() 56 { 57 return cast(void*)gMainContext; 58 } 59 60 /** 61 * Sets our main struct and passes it to the parent class. 62 */ 63 public this (GMainContext* gMainContext, bool ownedRef = false) 64 { 65 this.gMainContext = gMainContext; 66 this.ownedRef = ownedRef; 67 } 68 69 ~this () 70 { 71 if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef ) 72 g_main_context_unref(gMainContext); 73 } 74 75 76 /** 77 * Creates a new #GMainContext structure. 78 * 79 * Returns: the new #GMainContext 80 * 81 * Throws: ConstructionException GTK+ fails to create the object. 82 */ 83 public this() 84 { 85 auto p = g_main_context_new(); 86 87 if(p is null) 88 { 89 throw new ConstructionException("null returned by new"); 90 } 91 92 this(cast(GMainContext*) p); 93 } 94 95 /** 96 * Tries to become the owner of the specified context. 97 * If some other thread is the owner of the context, 98 * returns %FALSE immediately. Ownership is properly 99 * recursive: the owner can require ownership again 100 * and will release ownership when g_main_context_release() 101 * is called as many times as g_main_context_acquire(). 102 * 103 * You must be the owner of a context before you 104 * can call g_main_context_prepare(), g_main_context_query(), 105 * g_main_context_check(), g_main_context_dispatch(). 106 * 107 * Returns: %TRUE if the operation succeeded, and 108 * this thread is now the owner of @context. 109 */ 110 public bool acquire() 111 { 112 return g_main_context_acquire(gMainContext) != 0; 113 } 114 115 /** 116 * Adds a file descriptor to the set of file descriptors polled for 117 * this context. This will very seldom be used directly. Instead 118 * a typical event source will use g_source_add_unix_fd() instead. 119 * 120 * Params: 121 * fd = a #GPollFD structure holding information about a file 122 * descriptor to watch. 123 * priority = the priority for this file descriptor which should be 124 * the same as the priority used for g_source_attach() to ensure that the 125 * file descriptor is polled whenever the results may be needed. 126 */ 127 public void addPoll(GPollFD* fd, int priority) 128 { 129 g_main_context_add_poll(gMainContext, fd, priority); 130 } 131 132 /** 133 * Passes the results of polling back to the main loop. 134 * 135 * You must have successfully acquired the context with 136 * g_main_context_acquire() before you may call this function. 137 * 138 * Params: 139 * maxPriority = the maximum numerical priority of sources to check 140 * fds = array of #GPollFD's that was passed to 141 * the last call to g_main_context_query() 142 * nFds = return value of g_main_context_query() 143 * 144 * Returns: %TRUE if some sources are ready to be dispatched. 145 */ 146 public bool check(int maxPriority, GPollFD[] fds) 147 { 148 return g_main_context_check(gMainContext, maxPriority, fds.ptr, cast(int)fds.length) != 0; 149 } 150 151 /** 152 * Dispatches all pending sources. 153 * 154 * You must have successfully acquired the context with 155 * g_main_context_acquire() before you may call this function. 156 */ 157 public void dispatch() 158 { 159 g_main_context_dispatch(gMainContext); 160 } 161 162 /** 163 * Finds a source with the given source functions and user data. If 164 * multiple sources exist with the same source function and user data, 165 * the first one found will be returned. 166 * 167 * Params: 168 * funcs = the @source_funcs passed to g_source_new(). 169 * userData = the user data from the callback. 170 * 171 * Returns: the source, if one was found, otherwise %NULL 172 */ 173 public Source findSourceByFuncsUserData(GSourceFuncs* funcs, void* userData) 174 { 175 auto p = g_main_context_find_source_by_funcs_user_data(gMainContext, funcs, userData); 176 177 if(p is null) 178 { 179 return null; 180 } 181 182 return new Source(cast(GSource*) p); 183 } 184 185 /** 186 * Finds a #GSource given a pair of context and ID. 187 * 188 * It is a programmer error to attempt to lookup a non-existent source. 189 * 190 * More specifically: source IDs can be reissued after a source has been 191 * destroyed and therefore it is never valid to use this function with a 192 * source ID which may have already been removed. An example is when 193 * scheduling an idle to run in another thread with g_idle_add(): the 194 * idle may already have run and been removed by the time this function 195 * is called on its (now invalid) source ID. This source ID may have 196 * been reissued, leading to the operation being performed against the 197 * wrong source. 198 * 199 * Params: 200 * sourceId = the source ID, as returned by g_source_get_id(). 201 * 202 * Returns: the #GSource 203 */ 204 public Source findSourceById(uint sourceId) 205 { 206 auto p = g_main_context_find_source_by_id(gMainContext, sourceId); 207 208 if(p is null) 209 { 210 return null; 211 } 212 213 return new Source(cast(GSource*) p); 214 } 215 216 /** 217 * Finds a source with the given user data for the callback. If 218 * multiple sources exist with the same user data, the first 219 * one found will be returned. 220 * 221 * Params: 222 * userData = the user_data for the callback. 223 * 224 * Returns: the source, if one was found, otherwise %NULL 225 */ 226 public Source findSourceByUserData(void* userData) 227 { 228 auto p = g_main_context_find_source_by_user_data(gMainContext, userData); 229 230 if(p is null) 231 { 232 return null; 233 } 234 235 return new Source(cast(GSource*) p); 236 } 237 238 /** 239 * Gets the poll function set by g_main_context_set_poll_func(). 240 * 241 * Returns: the poll function 242 */ 243 public GPollFunc getPollFunc() 244 { 245 return g_main_context_get_poll_func(gMainContext); 246 } 247 248 /** 249 * Invokes a function in such a way that @context is owned during the 250 * invocation of @function. 251 * 252 * If @context is %NULL then the global default main context — as 253 * returned by g_main_context_default() — is used. 254 * 255 * If @context is owned by the current thread, @function is called 256 * directly. Otherwise, if @context is the thread-default main context 257 * of the current thread and g_main_context_acquire() succeeds, then 258 * @function is called and g_main_context_release() is called 259 * afterwards. 260 * 261 * In any other case, an idle source is created to call @function and 262 * that source is attached to @context (presumably to be run in another 263 * thread). The idle source is attached with #G_PRIORITY_DEFAULT 264 * priority. If you want a different priority, use 265 * g_main_context_invoke_full(). 266 * 267 * Note that, as with normal idle functions, @function should probably 268 * return %FALSE. If it returns %TRUE, it will be continuously run in a 269 * loop (and may prevent this call from returning). 270 * 271 * Params: 272 * funct = function to call 273 * data = data to pass to @function 274 * 275 * Since: 2.28 276 */ 277 public void invoke(GSourceFunc funct, void* data) 278 { 279 g_main_context_invoke(gMainContext, funct, data); 280 } 281 282 /** 283 * Invokes a function in such a way that @context is owned during the 284 * invocation of @function. 285 * 286 * This function is the same as g_main_context_invoke() except that it 287 * lets you specify the priority incase @function ends up being 288 * scheduled as an idle and also lets you give a #GDestroyNotify for @data. 289 * 290 * @notify should not assume that it is called from any particular 291 * thread or with any particular context acquired. 292 * 293 * Params: 294 * priority = the priority at which to run @function 295 * funct = function to call 296 * data = data to pass to @function 297 * notify = a function to call when @data is no longer in use, or %NULL. 298 * 299 * Since: 2.28 300 */ 301 public void invokeFull(int priority, GSourceFunc funct, void* data, GDestroyNotify notify) 302 { 303 g_main_context_invoke_full(gMainContext, priority, funct, data, notify); 304 } 305 306 /** 307 * Determines whether this thread holds the (recursive) 308 * ownership of this #GMainContext. This is useful to 309 * know before waiting on another thread that may be 310 * blocking to get ownership of @context. 311 * 312 * Returns: %TRUE if current thread is owner of @context. 313 * 314 * Since: 2.10 315 */ 316 public bool isOwner() 317 { 318 return g_main_context_is_owner(gMainContext) != 0; 319 } 320 321 /** 322 * Runs a single iteration for the given main loop. This involves 323 * checking to see if any event sources are ready to be processed, 324 * then if no events sources are ready and @may_block is %TRUE, waiting 325 * for a source to become ready, then dispatching the highest priority 326 * events sources that are ready. Otherwise, if @may_block is %FALSE 327 * sources are not waited to become ready, only those highest priority 328 * events sources will be dispatched (if any), that are ready at this 329 * given moment without further waiting. 330 * 331 * Note that even when @may_block is %TRUE, it is still possible for 332 * g_main_context_iteration() to return %FALSE, since the wait may 333 * be interrupted for other reasons than an event source becoming ready. 334 * 335 * Params: 336 * mayBlock = whether the call may block. 337 * 338 * Returns: %TRUE if events were dispatched. 339 */ 340 public bool iteration(bool mayBlock) 341 { 342 return g_main_context_iteration(gMainContext, mayBlock) != 0; 343 } 344 345 /** 346 * Checks if any sources have pending events for the given context. 347 * 348 * Returns: %TRUE if events are pending. 349 */ 350 public bool pending() 351 { 352 return g_main_context_pending(gMainContext) != 0; 353 } 354 355 /** 356 * Pops @context off the thread-default context stack (verifying that 357 * it was on the top of the stack). 358 * 359 * Since: 2.22 360 */ 361 public void popThreadDefault() 362 { 363 g_main_context_pop_thread_default(gMainContext); 364 } 365 366 /** 367 * Prepares to poll sources within a main loop. The resulting information 368 * for polling is determined by calling g_main_context_query (). 369 * 370 * You must have successfully acquired the context with 371 * g_main_context_acquire() before you may call this function. 372 * 373 * Params: 374 * priority = location to store priority of highest priority 375 * source already ready. 376 * 377 * Returns: %TRUE if some source is ready to be dispatched 378 * prior to polling. 379 */ 380 public bool prepare(int* priority) 381 { 382 return g_main_context_prepare(gMainContext, priority) != 0; 383 } 384 385 /** 386 * Acquires @context and sets it as the thread-default context for the 387 * current thread. This will cause certain asynchronous operations 388 * (such as most [gio][gio]-based I/O) which are 389 * started in this thread to run under @context and deliver their 390 * results to its main loop, rather than running under the global 391 * default context in the main thread. Note that calling this function 392 * changes the context returned by g_main_context_get_thread_default(), 393 * not the one returned by g_main_context_default(), so it does not affect 394 * the context used by functions like g_idle_add(). 395 * 396 * Normally you would call this function shortly after creating a new 397 * thread, passing it a #GMainContext which will be run by a 398 * #GMainLoop in that thread, to set a new default context for all 399 * async operations in that thread. In this case you may not need to 400 * ever call g_main_context_pop_thread_default(), assuming you want the 401 * new #GMainContext to be the default for the whole lifecycle of the 402 * thread. 403 * 404 * If you don't have control over how the new thread was created (e.g. 405 * in the new thread isn't newly created, or if the thread life 406 * cycle is managed by a #GThreadPool), it is always suggested to wrap 407 * the logic that needs to use the new #GMainContext inside a 408 * g_main_context_push_thread_default() / g_main_context_pop_thread_default() 409 * pair, otherwise threads that are re-used will end up never explicitly 410 * releasing the #GMainContext reference they hold. 411 * 412 * In some cases you may want to schedule a single operation in a 413 * non-default context, or temporarily use a non-default context in 414 * the main thread. In that case, you can wrap the call to the 415 * asynchronous operation inside a 416 * g_main_context_push_thread_default() / 417 * g_main_context_pop_thread_default() pair, but it is up to you to 418 * ensure that no other asynchronous operations accidentally get 419 * started while the non-default context is active. 420 * 421 * Beware that libraries that predate this function may not correctly 422 * handle being used from a thread with a thread-default context. Eg, 423 * see g_file_supports_thread_contexts(). 424 * 425 * Since: 2.22 426 */ 427 public void pushThreadDefault() 428 { 429 g_main_context_push_thread_default(gMainContext); 430 } 431 432 /** 433 * Determines information necessary to poll this main loop. 434 * 435 * You must have successfully acquired the context with 436 * g_main_context_acquire() before you may call this function. 437 * 438 * Params: 439 * maxPriority = maximum priority source to check 440 * timeout = location to store timeout to be used in polling 441 * fds = location to 442 * store #GPollFD records that need to be polled. 443 * nFds = length of @fds. 444 * 445 * Returns: the number of records actually stored in @fds, 446 * or, if more than @n_fds records need to be stored, the number 447 * of records that need to be stored. 448 */ 449 public int query(int maxPriority, out int timeout, GPollFD[] fds) 450 { 451 return g_main_context_query(gMainContext, maxPriority, &timeout, fds.ptr, cast(int)fds.length); 452 } 453 454 /** 455 * Increases the reference count on a #GMainContext object by one. 456 * 457 * Returns: the @context that was passed in (since 2.6) 458 */ 459 public MainContext doref() 460 { 461 auto p = g_main_context_ref(gMainContext); 462 463 if(p is null) 464 { 465 return null; 466 } 467 468 return new MainContext(cast(GMainContext*) p, true); 469 } 470 471 /** 472 * Releases ownership of a context previously acquired by this thread 473 * with g_main_context_acquire(). If the context was acquired multiple 474 * times, the ownership will be released only when g_main_context_release() 475 * is called as many times as it was acquired. 476 */ 477 public void release() 478 { 479 g_main_context_release(gMainContext); 480 } 481 482 /** 483 * Removes file descriptor from the set of file descriptors to be 484 * polled for a particular context. 485 * 486 * Params: 487 * fd = a #GPollFD descriptor previously added with g_main_context_add_poll() 488 */ 489 public void removePoll(GPollFD* fd) 490 { 491 g_main_context_remove_poll(gMainContext, fd); 492 } 493 494 /** 495 * Sets the function to use to handle polling of file descriptors. It 496 * will be used instead of the poll() system call 497 * (or GLib's replacement function, which is used where 498 * poll() isn't available). 499 * 500 * This function could possibly be used to integrate the GLib event 501 * loop with an external event loop. 502 * 503 * Params: 504 * func = the function to call to poll all file descriptors 505 */ 506 public void setPollFunc(GPollFunc func) 507 { 508 g_main_context_set_poll_func(gMainContext, func); 509 } 510 511 /** 512 * Decreases the reference count on a #GMainContext object by one. If 513 * the result is zero, free the context and free all associated memory. 514 */ 515 public void unref() 516 { 517 g_main_context_unref(gMainContext); 518 } 519 520 /** 521 * Tries to become the owner of the specified context, 522 * as with g_main_context_acquire(). But if another thread 523 * is the owner, atomically drop @mutex and wait on @cond until 524 * that owner releases ownership or until @cond is signaled, then 525 * try again (once) to become the owner. 526 * 527 * Params: 528 * cond = a condition variable 529 * mutex = a mutex, currently held 530 * 531 * Returns: %TRUE if the operation succeeded, and 532 * this thread is now the owner of @context. 533 */ 534 public bool wait(Cond cond, Mutex mutex) 535 { 536 return g_main_context_wait(gMainContext, (cond is null) ? null : cond.getCondStruct(), (mutex is null) ? null : mutex.getMutexStruct()) != 0; 537 } 538 539 /** 540 * If @context is currently blocking in g_main_context_iteration() 541 * waiting for a source to become ready, cause it to stop blocking 542 * and return. Otherwise, cause the next invocation of 543 * g_main_context_iteration() to return without blocking. 544 * 545 * This API is useful for low-level control over #GMainContext; for 546 * example, integrating it with main loop implementations such as 547 * #GMainLoop. 548 * 549 * Another related use for this function is when implementing a main 550 * loop with a termination condition, computed from multiple threads: 551 * 552 * |[<!-- language="C" --> 553 * #define NUM_TASKS 10 554 * static volatile gint tasks_remaining = NUM_TASKS; 555 * ... 556 * 557 * while (g_atomic_int_get (&tasks_remaining) != 0) 558 * g_main_context_iteration (NULL, TRUE); 559 * ]| 560 * 561 * Then in a thread: 562 * |[<!-- language="C" --> 563 * perform_work(); 564 * 565 * if (g_atomic_int_dec_and_test (&tasks_remaining)) 566 * g_main_context_wakeup (NULL); 567 * ]| 568 */ 569 public void wakeup() 570 { 571 g_main_context_wakeup(gMainContext); 572 } 573 574 /** 575 * Returns the global default main context. This is the main context 576 * used for main loop functions when a main loop is not explicitly 577 * specified, and corresponds to the "main" main loop. See also 578 * g_main_context_get_thread_default(). 579 * 580 * Returns: the global default main context. 581 */ 582 public static MainContext defaulx() 583 { 584 auto p = g_main_context_default(); 585 586 if(p is null) 587 { 588 return null; 589 } 590 591 return new MainContext(cast(GMainContext*) p); 592 } 593 594 /** 595 * Gets the thread-default #GMainContext for this thread. Asynchronous 596 * operations that want to be able to be run in contexts other than 597 * the default one should call this method or 598 * g_main_context_ref_thread_default() to get a #GMainContext to add 599 * their #GSources to. (Note that even in single-threaded 600 * programs applications may sometimes want to temporarily push a 601 * non-default context, so it is not safe to assume that this will 602 * always return %NULL if you are running in the default thread.) 603 * 604 * If you need to hold a reference on the context, use 605 * g_main_context_ref_thread_default() instead. 606 * 607 * Returns: the thread-default #GMainContext, or 608 * %NULL if the thread-default context is the global default context. 609 * 610 * Since: 2.22 611 */ 612 public static MainContext getThreadDefault() 613 { 614 auto p = g_main_context_get_thread_default(); 615 616 if(p is null) 617 { 618 return null; 619 } 620 621 return new MainContext(cast(GMainContext*) p); 622 } 623 624 /** 625 * Gets the thread-default #GMainContext for this thread, as with 626 * g_main_context_get_thread_default(), but also adds a reference to 627 * it with g_main_context_ref(). In addition, unlike 628 * g_main_context_get_thread_default(), if the thread-default context 629 * is the global default context, this will return that #GMainContext 630 * (with a ref added to it) rather than returning %NULL. 631 * 632 * Returns: the thread-default #GMainContext. Unref 633 * with g_main_context_unref() when you are done with it. 634 * 635 * Since: 2.32 636 */ 637 public static MainContext refThreadDefault() 638 { 639 auto p = g_main_context_ref_thread_default(); 640 641 if(p is null) 642 { 643 return null; 644 } 645 646 return new MainContext(cast(GMainContext*) p, true); 647 } 648 }