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