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