glib/gmain.h

   1 /* gmain.h - the GLib Main loop
   2  * Copyright (C) 1998-2000 Red Hat, Inc.
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-or-later
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public License
  17  * along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #ifndef __G_MAIN_H__
  21 #define __G_MAIN_H__
  22
  23 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  24 #error "Only <glib.h> can be included directly."
  25 #endif
  26
  27 #include <glib/gpoll.h>
  28 #include <glib/gslist.h>
  29 #include <glib/gthread.h>
  30
  31 G_BEGIN_DECLS
  32
  33 typedef enum /*< flags >*/
  34 {
  35   G_IO_IN       GLIB_SYSDEF_POLLIN,
  36   G_IO_OUT      GLIB_SYSDEF_POLLOUT,
  37   G_IO_PRI      GLIB_SYSDEF_POLLPRI,
  38   G_IO_ERR      GLIB_SYSDEF_POLLERR,
  39   G_IO_HUP      GLIB_SYSDEF_POLLHUP,
  40   G_IO_NVAL     GLIB_SYSDEF_POLLNVAL
  41 } GIOCondition;
  42
  43 /**
  44  * GMainContextFlags:
  45  * @G_MAIN_CONTEXT_FLAGS_NONE: Default behaviour.
  46  * @G_MAIN_CONTEXT_FLAGS_OWNERLESS_POLLING: Assume that polling for events will
  47  * free the thread to process other jobs. That's useful if you're using
  48  * `g_main_context_{prepare,query,check,dispatch}` to integrate GMainContext in
  49  * other event loops.
  50  *
  51  * Flags to pass to g_main_context_new_with_flags() which affect the behaviour
  52  * of a #GMainContext.
  53  *
  54  * Since: 2.72
  55  */
  56 GLIB_AVAILABLE_TYPE_IN_2_72
  57 typedef enum /*< flags >*/
  58 {
  59   G_MAIN_CONTEXT_FLAGS_NONE = 0,
  60   G_MAIN_CONTEXT_FLAGS_OWNERLESS_POLLING = 1
  61 } GMainContextFlags;
  62
  63
  64 /**
  65  * GMainContext:
  66  *
  67  * The `GMainContext` struct is an opaque data
  68  * type representing a set of sources to be handled in a main loop.
  69  */
  70 typedef struct _GMainContext            GMainContext;
  71
  72 /**
  73  * GMainLoop:
  74  *
  75  * The `GMainLoop` struct is an opaque data type
  76  * representing the main event loop of a GLib or GTK application.
  77  */
  78 typedef struct _GMainLoop               GMainLoop;
  79
  80 /**
  81  * GSource:
  82  *
  83  * The `GSource` struct is an opaque data type
  84  * representing an event source.
  85  */
  86 typedef struct _GSource                 GSource;
  87 typedef struct _GSourcePrivate          GSourcePrivate;
  88
  89 /**
  90  * GSourceCallbackFuncs:
  91  * @ref: Called when a reference is added to the callback object
  92  * @unref: Called when a reference to the callback object is dropped
  93  * @get: Called to extract the callback function and data from the
  94  *     callback object.
  95  *
  96  * The `GSourceCallbackFuncs` struct contains
  97  * functions for managing callback objects.
  98  */
  99 typedef struct _GSourceCallbackFuncs    GSourceCallbackFuncs;
 100
 101 /**
 102  * GSourceFuncs:
 103  * @prepare: Called before all the file descriptors are polled. If the
 104  *     source can determine that it is ready here (without waiting for the
 105  *     results of the poll() call) it should return %TRUE. It can also return
 106  *     a @timeout_ value which should be the maximum timeout (in milliseconds)
 107  *     which should be passed to the poll() call. The actual timeout used will
 108  *     be -1 if all sources returned -1, or it will be the minimum of all
 109  *     the @timeout_ values returned which were >= 0.  Since 2.36 this may
 110  *     be %NULL, in which case the effect is as if the function always returns
 111  *     %FALSE with a timeout of -1.  If @prepare returns a
 112  *     timeout and the source also has a ready time set, then the
 113  *     lower of the two will be used.
 114  * @check: Called after all the file descriptors are polled. The source
 115  *     should return %TRUE if it is ready to be dispatched. Note that some
 116  *     time may have passed since the previous prepare function was called,
 117  *     so the source should be checked again here.  Since 2.36 this may
 118  *     be %NULL, in which case the effect is as if the function always returns
 119  *     %FALSE.
 120  * @dispatch: Called to dispatch the event source, after it has returned
 121  *     %TRUE in either its @prepare or its @check function, or if a ready time
 122  *     has been reached. The @dispatch function receives a callback function and
 123  *     user data. The callback function may be %NULL if the source was never
 124  *     connected to a callback using g_source_set_callback(). The @dispatch
 125  *     function should call the callback function with @user_data and whatever
 126  *     additional parameters are needed for this type of event source. The
 127  *     return value of the @dispatch function should be %G_SOURCE_REMOVE if the
 128  *     source should be removed or %G_SOURCE_CONTINUE to keep it.
 129  * @finalize: Called when the source is finalized. At this point, the source
 130  *     will have been destroyed, had its callback cleared, and have been removed
 131  *     from its #GMainContext, but it will still have its final reference count,
 132  *     so methods can be called on it from within this function.
 133  *
 134  * The `GSourceFuncs` struct contains a table of
 135  * functions used to handle event sources in a generic manner.
 136  *
 137  * For idle sources, the prepare and check functions always return %TRUE
 138  * to indicate that the source is always ready to be processed. The prepare
 139  * function also returns a timeout value of 0 to ensure that the poll() call
 140  * doesn't block (since that would be time wasted which could have been spent
 141  * running the idle function).
 142  *
 143  * For timeout sources, the prepare and check functions both return %TRUE
 144  * if the timeout interval has expired. The prepare function also returns
 145  * a timeout value to ensure that the poll() call doesn't block too long
 146  * and miss the next timeout.
 147  *
 148  * For file descriptor sources, the prepare function typically returns %FALSE,
 149  * since it must wait until poll() has been called before it knows whether
 150  * any events need to be processed. It sets the returned timeout to -1 to
 151  * indicate that it doesn't mind how long the poll() call blocks. In the
 152  * check function, it tests the results of the poll() call to see if the
 153  * required condition has been met, and returns %TRUE if so.
 154  */
 155 typedef struct _GSourceFuncs            GSourceFuncs;
 156
 157 /**
 158  * GPid:
 159  *
 160  * A type which is used to hold a process identification.
 161  *
 162  * On UNIX, processes are identified by a process id (an integer),
 163  * while Windows uses process handles (which are pointers).
 164  *
 165  * GPid is used in GLib only for descendant processes spawned with
 166  * the g_spawn functions.
 167  */
 168 /* defined in glibconfig.h */
 169
 170 /**
 171  * G_PID_FORMAT:
 172  *
 173  * A format specifier that can be used in printf()-style format strings
 174  * when printing a #GPid.
 175  *
 176  * Since: 2.50
 177  */
 178 /* defined in glibconfig.h */
 179
 180 /**
 181  * GSourceFunc:
 182  * @user_data: data passed to the function, set when the source was
 183  *     created with one of the above functions
 184  *
 185  * Specifies the type of function passed to g_timeout_add(),
 186  * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
 187  *
 188  * When calling g_source_set_callback(), you may need to cast a function of a
 189  * different type to this type. Use G_SOURCE_FUNC() to avoid warnings about
 190  * incompatible function types.
 191  *
 192  * Returns: %FALSE if the source should be removed. %G_SOURCE_CONTINUE and
 193  * %G_SOURCE_REMOVE are more memorable names for the return value.
 194  */
 195 typedef gboolean (*GSourceFunc)       (gpointer user_data);
 196
 197 /**
 198  * GSourceOnceFunc:
 199  * @user_data: data passed to the function, set when the source was
 200  *   created
 201  *
 202  * A source function that is only called once before being removed from the main
 203  * context automatically.
 204  *
 205  * See: g_idle_add_once(), g_timeout_add_once()
 206  *
 207  * Since: 2.74
 208  */
 209 typedef void (* GSourceOnceFunc) (gpointer user_data);
 210
 211 /**
 212  * G_SOURCE_FUNC:
 213  * @f: a function pointer.
 214  *
 215  * Cast a function pointer to a #GSourceFunc, suppressing warnings from GCC 8
 216  * onwards with `-Wextra` or `-Wcast-function-type` enabled about the function
 217  * types being incompatible.
 218  *
 219  * For example, the correct type of callback for a source created by
 220  * g_child_watch_source_new() is #GChildWatchFunc, which accepts more arguments
 221  * than #GSourceFunc. Casting the function with `(GSourceFunc)` to call
 222  * g_source_set_callback() will trigger a warning, even though it will be cast
 223  * back to the correct type before it is called by the source.
 224  *
 225  * Since: 2.58
 226  */
 227 #define G_SOURCE_FUNC(f) ((GSourceFunc) (void (*)(void)) (f)) GLIB_AVAILABLE_MACRO_IN_2_58
 228
 229 /**
 230  * GChildWatchFunc:
 231  * @pid: the process id of the child process
 232  * @wait_status: Status information about the child process, encoded
 233  *               in a platform-specific manner
 234  * @user_data: user data passed to g_child_watch_add()
 235  *
 236  * Prototype of a #GChildWatchSource callback, called when a child
 237  * process has exited.
 238  *
 239  * To interpret @wait_status, see the documentation
 240  * for g_spawn_check_wait_status(). In particular,
 241  * on Unix platforms, note that it is usually not equal
 242  * to the integer passed to `exit()` or returned from `main()`.
 243  */
 244 typedef void     (*GChildWatchFunc)   (GPid     pid,
 245                                        gint     wait_status,
 246                                        gpointer user_data);
 247
 248
 249 /**
 250  * GSourceDisposeFunc:
 251  * @source: #GSource that is currently being disposed
 252  *
 253  * Dispose function for @source. See g_source_set_dispose_function() for
 254  * details.
 255  *
 256  * Since: 2.64
 257  */
 258 GLIB_AVAILABLE_TYPE_IN_2_64
 259 typedef void (*GSourceDisposeFunc)       (GSource *source);
 260
 261 struct _GSource
 262 {
 263   /*< private >*/
 264   gpointer callback_data;
 265   GSourceCallbackFuncs *callback_funcs;
 266
 267   const GSourceFuncs *source_funcs;
 268   guint ref_count;
 269
 270   GMainContext *context;
 271
 272   gint priority;
 273   guint flags;
 274   guint source_id;
 275
 276   GSList *poll_fds;
 277
 278   GSource *prev;
 279   GSource *next;
 280
 281   char    *name;
 282
 283   GSourcePrivate *priv;
 284 };
 285
 286 struct _GSourceCallbackFuncs
 287 {
 288   void (*ref)   (gpointer     cb_data);
 289   void (*unref) (gpointer     cb_data);
 290   void (*get)   (gpointer     cb_data,
 291                  GSource     *source,
 292                  GSourceFunc *func,
 293                  gpointer    *data);
 294 };
 295
 296 /**
 297  * GSourceDummyMarshal:
 298  *
 299  * This is just a placeholder for #GClosureMarshal,
 300  * which cannot be used here for dependency reasons.
 301  */
 302 typedef void (*GSourceDummyMarshal) (void);
 303
 304 struct _GSourceFuncs
 305 {
 306   gboolean (*prepare)  (GSource    *source,
 307                         gint       *timeout_);/* Can be NULL */
 308   gboolean (*check)    (GSource    *source);/* Can be NULL */
 309   gboolean (*dispatch) (GSource    *source,
 310                         GSourceFunc callback,
 311                         gpointer    user_data);
 312   void     (*finalize) (GSource    *source); /* Can be NULL */
 313
 314   /*< private >*/
 315   /* For use by g_source_set_closure */
 316   GSourceFunc     closure_callback;
 317   GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
 318 };
 319
 320 /* Standard priorities */
 321
 322 /**
 323  * G_PRIORITY_HIGH:
 324  *
 325  * Use this for high priority event sources.
 326  *
 327  * It is not used within GLib or GTK.
 328  */
 329 #define G_PRIORITY_HIGH            -100
 330
 331 /**
 332  * G_PRIORITY_DEFAULT:
 333  *
 334  * Use this for default priority event sources.
 335  *
 336  * In GLib this priority is used when adding timeout functions
 337  * with g_timeout_add(). In GDK this priority is used for events
 338  * from the X server.
 339  */
 340 #define G_PRIORITY_DEFAULT          0
 341
 342 /**
 343  * G_PRIORITY_HIGH_IDLE:
 344  *
 345  * Use this for high priority idle functions.
 346  *
 347  * GTK uses %G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
 348  * and %G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
 349  * done to ensure that any pending resizes are processed before any
 350  * pending redraws, so that widgets are not redrawn twice unnecessarily.)
 351  */
 352 #define G_PRIORITY_HIGH_IDLE        100
 353
 354 /**
 355  * G_PRIORITY_DEFAULT_IDLE:
 356  *
 357  * Use this for default priority idle functions.
 358  *
 359  * In GLib this priority is used when adding idle functions with
 360  * g_idle_add().
 361  */
 362 #define G_PRIORITY_DEFAULT_IDLE     200
 363
 364 /**
 365  * G_PRIORITY_LOW:
 366  *
 367  * Use this for very low priority background tasks.
 368  *
 369  * It is not used within GLib or GTK.
 370  */
 371 #define G_PRIORITY_LOW              300
 372
 373 /**
 374  * G_SOURCE_REMOVE:
 375  *
 376  * Use this macro as the return value of a #GSourceFunc to remove
 377  * the #GSource from the main loop.
 378  *
 379  * Since: 2.32
 380  */
 381 #define G_SOURCE_REMOVE         FALSE
 382
 383 /**
 384  * G_SOURCE_CONTINUE:
 385  *
 386  * Use this macro as the return value of a #GSourceFunc to leave
 387  * the #GSource in the main loop.
 388  *
 389  * Since: 2.32
 390  */
 391 #define G_SOURCE_CONTINUE       TRUE
 392
 393 /* GMainContext: */
 394
 395 GLIB_AVAILABLE_IN_ALL
 396 GMainContext *g_main_context_new       (void);
 397 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 398 GLIB_AVAILABLE_IN_2_72
 399 GMainContext *g_main_context_new_with_flags (GMainContextFlags flags);
 400 G_GNUC_END_IGNORE_DEPRECATIONS
 401 GLIB_AVAILABLE_IN_ALL
 402 GMainContext *g_main_context_ref       (GMainContext *context);
 403 GLIB_AVAILABLE_IN_ALL
 404 void          g_main_context_unref     (GMainContext *context);
 405 GLIB_AVAILABLE_IN_ALL
 406 GMainContext *g_main_context_default   (void);
 407
 408 GLIB_AVAILABLE_IN_ALL
 409 gboolean      g_main_context_iteration (GMainContext *context,
 410                                         gboolean      may_block);
 411 GLIB_AVAILABLE_IN_ALL
 412 gboolean      g_main_context_pending   (GMainContext *context);
 413
 414 /* For implementation of legacy interfaces
 415  */
 416 GLIB_AVAILABLE_IN_ALL
 417 GSource      *g_main_context_find_source_by_id              (GMainContext *context,
 418                                                              guint         source_id);
 419 GLIB_AVAILABLE_IN_ALL
 420 GSource      *g_main_context_find_source_by_user_data       (GMainContext *context,
 421                                                              gpointer      user_data);
 422 GLIB_AVAILABLE_IN_ALL
 423 GSource      *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
 424                                                              GSourceFuncs *funcs,
 425                                                              gpointer      user_data);
 426
 427 /* Low level functions for implementing custom main loops.
 428  */
 429 GLIB_AVAILABLE_IN_ALL
 430 void     g_main_context_wakeup  (GMainContext *context);
 431 GLIB_AVAILABLE_IN_ALL
 432 gboolean g_main_context_acquire (GMainContext *context);
 433 GLIB_AVAILABLE_IN_ALL
 434 void     g_main_context_release (GMainContext *context);
 435 GLIB_AVAILABLE_IN_ALL
 436 gboolean g_main_context_is_owner (GMainContext *context);
 437 GLIB_DEPRECATED_IN_2_58_FOR(g_main_context_is_owner)
 438 gboolean g_main_context_wait    (GMainContext *context,
 439                                  GCond        *cond,
 440                                  GMutex       *mutex);
 441
 442 GLIB_AVAILABLE_IN_ALL
 443 gboolean g_main_context_prepare  (GMainContext *context,
 444                                   gint         *priority);
 445 GLIB_AVAILABLE_IN_ALL
 446 gint     g_main_context_query    (GMainContext *context,
 447                                   gint          max_priority,
 448                                   gint         *timeout_,
 449                                   GPollFD      *fds,
 450                                   gint          n_fds);
 451 GLIB_AVAILABLE_IN_ALL
 452 gboolean     g_main_context_check    (GMainContext *context,
 453                                       gint          max_priority,
 454                                       GPollFD      *fds,
 455                                       gint          n_fds);
 456 GLIB_AVAILABLE_IN_ALL
 457 void     g_main_context_dispatch (GMainContext *context);
 458
 459 GLIB_AVAILABLE_IN_ALL
 460 void     g_main_context_set_poll_func (GMainContext *context,
 461                                        GPollFunc     func);
 462 GLIB_AVAILABLE_IN_ALL
 463 GPollFunc g_main_context_get_poll_func (GMainContext *context);
 464
 465 /* Low level functions for use by source implementations
 466  */
 467 GLIB_AVAILABLE_IN_ALL
 468 void     g_main_context_add_poll    (GMainContext *context,
 469                                      GPollFD      *fd,
 470                                      gint          priority);
 471 GLIB_AVAILABLE_IN_ALL
 472 void     g_main_context_remove_poll (GMainContext *context,
 473                                      GPollFD      *fd);
 474
 475 GLIB_AVAILABLE_IN_ALL
 476 gint     g_main_depth               (void);
 477 GLIB_AVAILABLE_IN_ALL
 478 GSource *g_main_current_source      (void);
 479
 480 /* GMainContexts for other threads
 481  */
 482 GLIB_AVAILABLE_IN_ALL
 483 void          g_main_context_push_thread_default (GMainContext *context);
 484 GLIB_AVAILABLE_IN_ALL
 485 void          g_main_context_pop_thread_default  (GMainContext *context);
 486 GLIB_AVAILABLE_IN_ALL
 487 GMainContext *g_main_context_get_thread_default  (void);
 488 GLIB_AVAILABLE_IN_ALL
 489 GMainContext *g_main_context_ref_thread_default  (void);
 490
 491 /**
 492  * GMainContextPusher:
 493  *
 494  * Opaque type. See g_main_context_pusher_new() for details.
 495  *
 496  * Since: 2.64
 497  */
 498 typedef void GMainContextPusher GLIB_AVAILABLE_TYPE_IN_2_64;
 499
 500 /**
 501  * g_main_context_pusher_new:
 502  * @main_context: (transfer none): a main context to push
 503  *
 504  * Push @main_context as the new thread-default main context for the current
 505  * thread, using g_main_context_push_thread_default(), and return a new
 506  * #GMainContextPusher. Pop with g_main_context_pusher_free(). Using
 507  * g_main_context_pop_thread_default() on @main_context while a
 508  * #GMainContextPusher exists for it can lead to undefined behaviour.
 509  *
 510  * Using two #GMainContextPushers in the same scope is not allowed, as it leads
 511  * to an undefined pop order.
 512  *
 513  * This is intended to be used with g_autoptr().  Note that g_autoptr()
 514  * is only available when using GCC or clang, so the following example
 515  * will only work with those compilers:
 516  * |[
 517  * typedef struct
 518  * {
 519  *   ...
 520  *   GMainContext *context;
 521  *   ...
 522  * } MyObject;
 523  *
 524  * static void
 525  * my_object_do_stuff (MyObject *self)
 526  * {
 527  *   g_autoptr(GMainContextPusher) pusher = g_main_context_pusher_new (self->context);
 528  *
 529  *   // Code with main context as the thread default here
 530  *
 531  *   if (cond)
 532  *     // No need to pop
 533  *     return;
 534  *
 535  *   // Optionally early pop
 536  *   g_clear_pointer (&pusher, g_main_context_pusher_free);
 537  *
 538  *   // Code with main context no longer the thread default here
 539  * }
 540  * ]|
 541  *
 542  * Returns: (transfer full): a #GMainContextPusher
 543  * Since: 2.64
 544  */
 545 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 546 GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
 547 static inline GMainContextPusher *
 548 g_main_context_pusher_new (GMainContext *main_context)
 549 {
 550   g_main_context_push_thread_default (main_context);
 551   return (GMainContextPusher *) main_context;
 552 }
 553 G_GNUC_END_IGNORE_DEPRECATIONS
 554
 555 /**
 556  * g_main_context_pusher_free:
 557  * @pusher: (transfer full): a #GMainContextPusher
 558  *
 559  * Pop @pusher’s main context as the thread default main context.
 560  * See g_main_context_pusher_new() for details.
 561  *
 562  * This will pop the #GMainContext as the current thread-default main context,
 563  * but will not call g_main_context_unref() on it.
 564  *
 565  * Since: 2.64
 566  */
 567 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 568 GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
 569 static inline void
 570 g_main_context_pusher_free (GMainContextPusher *pusher)
 571 {
 572   g_main_context_pop_thread_default ((GMainContext *) pusher);
 573 }
 574 G_GNUC_END_IGNORE_DEPRECATIONS
 575
 576 /* GMainLoop: */
 577
 578 GLIB_AVAILABLE_IN_ALL
 579 GMainLoop *g_main_loop_new        (GMainContext *context,
 580                                    gboolean      is_running);
 581 GLIB_AVAILABLE_IN_ALL
 582 void       g_main_loop_run        (GMainLoop    *loop);
 583 GLIB_AVAILABLE_IN_ALL
 584 void       g_main_loop_quit       (GMainLoop    *loop);
 585 GLIB_AVAILABLE_IN_ALL
 586 GMainLoop *g_main_loop_ref        (GMainLoop    *loop);
 587 GLIB_AVAILABLE_IN_ALL
 588 void       g_main_loop_unref      (GMainLoop    *loop);
 589 GLIB_AVAILABLE_IN_ALL
 590 gboolean   g_main_loop_is_running (GMainLoop    *loop);
 591 GLIB_AVAILABLE_IN_ALL
 592 GMainContext *g_main_loop_get_context (GMainLoop    *loop);
 593
 594 /* GSource: */
 595
 596 GLIB_AVAILABLE_IN_ALL
 597 GSource *g_source_new             (GSourceFuncs   *source_funcs,
 598                                    guint           struct_size);
 599
 600 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 601 GLIB_AVAILABLE_IN_2_64
 602 void     g_source_set_dispose_function (GSource            *source,
 603                                         GSourceDisposeFunc  dispose);
 604 G_GNUC_END_IGNORE_DEPRECATIONS
 605
 606 GLIB_AVAILABLE_IN_ALL
 607 GSource *g_source_ref             (GSource        *source);
 608 GLIB_AVAILABLE_IN_ALL
 609 void     g_source_unref           (GSource        *source);
 610
 611 GLIB_AVAILABLE_IN_ALL
 612 guint    g_source_attach          (GSource        *source,
 613                                    GMainContext   *context);
 614 GLIB_AVAILABLE_IN_ALL
 615 void     g_source_destroy         (GSource        *source);
 616
 617 GLIB_AVAILABLE_IN_ALL
 618 void     g_source_set_priority    (GSource        *source,
 619                                    gint            priority);
 620 GLIB_AVAILABLE_IN_ALL
 621 gint     g_source_get_priority    (GSource        *source);
 622 GLIB_AVAILABLE_IN_ALL
 623 void     g_source_set_can_recurse (GSource        *source,
 624                                    gboolean        can_recurse);
 625 GLIB_AVAILABLE_IN_ALL
 626 gboolean g_source_get_can_recurse (GSource        *source);
 627 GLIB_AVAILABLE_IN_ALL
 628 guint    g_source_get_id          (GSource        *source);
 629
 630 GLIB_AVAILABLE_IN_ALL
 631 GMainContext *g_source_get_context (GSource       *source);
 632
 633 GLIB_AVAILABLE_IN_ALL
 634 void     g_source_set_callback    (GSource        *source,
 635                                    GSourceFunc     func,
 636                                    gpointer        data,
 637                                    GDestroyNotify  notify);
 638
 639 GLIB_AVAILABLE_IN_ALL
 640 void     g_source_set_funcs       (GSource        *source,
 641                                    GSourceFuncs   *funcs);
 642 GLIB_AVAILABLE_IN_ALL
 643 gboolean g_source_is_destroyed    (GSource        *source);
 644
 645 GLIB_AVAILABLE_IN_ALL
 646 void                 g_source_set_name       (GSource        *source,
 647                                               const char     *name);
 648 GLIB_AVAILABLE_IN_2_70
 649 void                 g_source_set_static_name (GSource        *source,
 650                                                const char     *name);
 651 GLIB_AVAILABLE_IN_ALL
 652 const char *         g_source_get_name       (GSource        *source);
 653 GLIB_AVAILABLE_IN_ALL
 654 void                 g_source_set_name_by_id (guint           tag,
 655                                               const char     *name);
 656
 657 GLIB_AVAILABLE_IN_2_36
 658 void                 g_source_set_ready_time (GSource        *source,
 659                                               gint64          ready_time);
 660 GLIB_AVAILABLE_IN_2_36
 661 gint64               g_source_get_ready_time (GSource        *source);
 662
 663 #ifdef G_OS_UNIX
 664 GLIB_AVAILABLE_IN_2_36
 665 gpointer             g_source_add_unix_fd    (GSource        *source,
 666                                               gint            fd,
 667                                               GIOCondition    events);
 668 GLIB_AVAILABLE_IN_2_36
 669 void                 g_source_modify_unix_fd (GSource        *source,
 670                                               gpointer        tag,
 671                                               GIOCondition    new_events);
 672 GLIB_AVAILABLE_IN_2_36
 673 void                 g_source_remove_unix_fd (GSource        *source,
 674                                               gpointer        tag);
 675 GLIB_AVAILABLE_IN_2_36
 676 GIOCondition         g_source_query_unix_fd  (GSource        *source,
 677                                               gpointer        tag);
 678 #endif
 679
 680 /* Used to implement g_source_connect_closure and internally*/
 681 GLIB_AVAILABLE_IN_ALL
 682 void g_source_set_callback_indirect (GSource              *source,
 683                                      gpointer              callback_data,
 684                                      GSourceCallbackFuncs *callback_funcs);
 685
 686 GLIB_AVAILABLE_IN_ALL
 687 void     g_source_add_poll            (GSource        *source,
 688                                        GPollFD        *fd);
 689 GLIB_AVAILABLE_IN_ALL
 690 void     g_source_remove_poll         (GSource        *source,
 691                                        GPollFD        *fd);
 692
 693 GLIB_AVAILABLE_IN_ALL
 694 void     g_source_add_child_source    (GSource        *source,
 695                                        GSource        *child_source);
 696 GLIB_AVAILABLE_IN_ALL
 697 void     g_source_remove_child_source (GSource        *source,
 698                                        GSource        *child_source);
 699
 700 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 701 GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time)
 702 void     g_source_get_current_time (GSource        *source,
 703                                     GTimeVal       *timeval);
 704 G_GNUC_END_IGNORE_DEPRECATIONS
 705
 706 GLIB_AVAILABLE_IN_ALL
 707 gint64   g_source_get_time         (GSource        *source);
 708
 709  /* void g_source_connect_closure (GSource        *source,
 710                                   GClosure       *closure);
 711  */
 712
 713 /* Specific source types
 714  */
 715 GLIB_AVAILABLE_IN_ALL
 716 GSource *g_idle_source_new        (void);
 717 GLIB_AVAILABLE_IN_ALL
 718 GSource *g_child_watch_source_new (GPid pid);
 719 GLIB_AVAILABLE_IN_ALL
 720 GSource *g_timeout_source_new     (guint interval);
 721 GLIB_AVAILABLE_IN_ALL
 722 GSource *g_timeout_source_new_seconds (guint interval);
 723
 724 /* Miscellaneous functions
 725  */
 726 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 727 GLIB_DEPRECATED_IN_2_62_FOR(g_get_real_time)
 728 void   g_get_current_time                 (GTimeVal       *result);
 729 G_GNUC_END_IGNORE_DEPRECATIONS
 730
 731 GLIB_AVAILABLE_IN_ALL
 732 gint64 g_get_monotonic_time               (void);
 733 GLIB_AVAILABLE_IN_ALL
 734 gint64 g_get_real_time                    (void);
 735
 736
 737 /* Source manipulation by ID */
 738 GLIB_AVAILABLE_IN_ALL
 739 gboolean g_source_remove                     (guint          tag);
 740 GLIB_AVAILABLE_IN_ALL
 741 gboolean g_source_remove_by_user_data        (gpointer       user_data);
 742 GLIB_AVAILABLE_IN_ALL
 743 gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
 744                                               gpointer       user_data);
 745
 746 /**
 747  * GClearHandleFunc:
 748  * @handle_id: the handle ID to clear
 749  *
 750  * Specifies the type of function passed to g_clear_handle_id().
 751  * The implementation is expected to free the resource identified
 752  * by @handle_id; for instance, if @handle_id is a #GSource ID,
 753  * g_source_remove() can be used.
 754  *
 755  * Since: 2.56
 756  */
 757 typedef void (* GClearHandleFunc) (guint handle_id);
 758
 759 GLIB_AVAILABLE_IN_2_56
 760 void    g_clear_handle_id (guint           *tag_ptr,
 761                            GClearHandleFunc clear_func);
 762
 763 #define g_clear_handle_id(tag_ptr, clear_func)             \
 764   G_STMT_START {                                           \
 765     G_STATIC_ASSERT (sizeof *(tag_ptr) == sizeof (guint)); \
 766     guint *_tag_ptr = (guint *) (tag_ptr);                 \
 767     guint _handle_id;                                      \
 768                                                            \
 769     _handle_id = *_tag_ptr;                                \
 770     if (_handle_id > 0)                                    \
 771       {                                                    \
 772         *_tag_ptr = 0;                                     \
 773         clear_func (_handle_id);                           \
 774       }                                                    \
 775   } G_STMT_END                                             \
 776   GLIB_AVAILABLE_MACRO_IN_2_56
 777
 778 /* Idles, child watchers and timeouts */
 779 GLIB_AVAILABLE_IN_ALL
 780 guint    g_timeout_add_full         (gint            priority,
 781                                      guint           interval,
 782                                      GSourceFunc     function,
 783                                      gpointer        data,
 784                                      GDestroyNotify  notify);
 785 GLIB_AVAILABLE_IN_ALL
 786 guint    g_timeout_add              (guint           interval,
 787                                      GSourceFunc     function,
 788                                      gpointer        data);
 789 GLIB_AVAILABLE_IN_2_74
 790 guint    g_timeout_add_once         (guint           interval,
 791                                      GSourceOnceFunc function,
 792                                      gpointer        data);
 793 GLIB_AVAILABLE_IN_ALL
 794 guint    g_timeout_add_seconds_full (gint            priority,
 795                                      guint           interval,
 796                                      GSourceFunc     function,
 797                                      gpointer        data,
 798                                      GDestroyNotify  notify);
 799 GLIB_AVAILABLE_IN_ALL
 800 guint    g_timeout_add_seconds      (guint           interval,
 801                                      GSourceFunc     function,
 802                                      gpointer        data);
 803 GLIB_AVAILABLE_IN_2_78
 804 guint    g_timeout_add_seconds_once (guint           interval,
 805                                      GSourceOnceFunc function,
 806                                      gpointer        data);
 807 GLIB_AVAILABLE_IN_ALL
 808 guint    g_child_watch_add_full     (gint            priority,
 809                                      GPid            pid,
 810                                      GChildWatchFunc function,
 811                                      gpointer        data,
 812                                      GDestroyNotify  notify);
 813 GLIB_AVAILABLE_IN_ALL
 814 guint    g_child_watch_add          (GPid            pid,
 815                                      GChildWatchFunc function,
 816                                      gpointer        data);
 817 GLIB_AVAILABLE_IN_ALL
 818 guint    g_idle_add                 (GSourceFunc     function,
 819                                      gpointer        data);
 820 GLIB_AVAILABLE_IN_ALL
 821 guint    g_idle_add_full            (gint            priority,
 822                                      GSourceFunc     function,
 823                                      gpointer        data,
 824                                      GDestroyNotify  notify);
 825 GLIB_AVAILABLE_IN_2_74
 826 guint    g_idle_add_once            (GSourceOnceFunc function,
 827                                      gpointer        data);
 828 GLIB_AVAILABLE_IN_ALL
 829 gboolean g_idle_remove_by_data      (gpointer        data);
 830
 831 GLIB_AVAILABLE_IN_ALL
 832 void     g_main_context_invoke_full (GMainContext   *context,
 833                                      gint            priority,
 834                                      GSourceFunc     function,
 835                                      gpointer        data,
 836                                      GDestroyNotify  notify);
 837 GLIB_AVAILABLE_IN_ALL
 838 void     g_main_context_invoke      (GMainContext   *context,
 839                                      GSourceFunc     function,
 840                                      gpointer        data);
 841
 842 GLIB_AVAILABLE_STATIC_INLINE_IN_2_70
 843 static inline int
 844 g_steal_fd (int *fd_ptr)
 845 {
 846   int fd = *fd_ptr;
 847   *fd_ptr = -1;
 848   return fd;
 849 }
 850
 851 /* Hook for GClosure / GSource integration. Don't touch */
 852 GLIB_VAR GSourceFuncs g_timeout_funcs;
 853 GLIB_VAR GSourceFuncs g_child_watch_funcs;
 854 GLIB_VAR GSourceFuncs g_idle_funcs;
 855 #ifdef G_OS_UNIX
 856 GLIB_VAR GSourceFuncs g_unix_signal_funcs;
 857 GLIB_VAR GSourceFuncs g_unix_fd_source_funcs;
 858 #endif
 859
 860 G_END_DECLS
 861
 862 #endif /* __G_MAIN_H__ */