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