glib-2.0/glib/gmain.h

0001 /* gmain.h - the GLib Main loop
0002  * Copyright (C) 1998-2000 Red Hat, Inc.
0003  *
0004  * SPDX-License-Identifier: LGPL-2.1-or-later
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Lesser General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2.1 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Lesser General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Lesser General Public License
0017  * along with this library; if not, see <http://www.gnu.org/licenses/>.
0018  */
0019
0020 #ifndef __G_MAIN_H__
0021 #define __G_MAIN_H__
0022
0023 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0024 #error "Only <glib.h> can be included directly."
0025 #endif
0026
0027 #include <glib/gpoll.h>
0028 #include <glib/gslist.h>
0029 #include <glib/gthread.h>
0030
0031 G_BEGIN_DECLS
0032
0033 typedef enum /*< flags >*/
0034 {
0035   G_IO_IN   GLIB_SYSDEF_POLLIN,
0036   G_IO_OUT  GLIB_SYSDEF_POLLOUT,
0037   G_IO_PRI  GLIB_SYSDEF_POLLPRI,
0038   G_IO_ERR  GLIB_SYSDEF_POLLERR,
0039   G_IO_HUP  GLIB_SYSDEF_POLLHUP,
0040   G_IO_NVAL GLIB_SYSDEF_POLLNVAL
0041 } GIOCondition;
0042
0043 /**
0044  * GMainContextFlags:
0045  * @G_MAIN_CONTEXT_FLAGS_NONE: Default behaviour.
0046  * @G_MAIN_CONTEXT_FLAGS_OWNERLESS_POLLING: Assume that polling for events will
0047  * free the thread to process other jobs. That's useful if you're using
0048  * `g_main_context_{prepare,query,check,dispatch}` to integrate GMainContext in
0049  * other event loops.
0050  *
0051  * Flags to pass to [ctor@GLib.MainContext.new_with_flags] which affect the
0052  * behaviour of a [struct@GLib.MainContext].
0053  *
0054  * Since: 2.72
0055  */
0056 GLIB_AVAILABLE_TYPE_IN_2_72
0057 typedef enum /*< flags >*/
0058 {
0059   G_MAIN_CONTEXT_FLAGS_NONE = 0,
0060   G_MAIN_CONTEXT_FLAGS_OWNERLESS_POLLING = 1
0061 } GMainContextFlags;
0062
0063
0064 /**
0065  * GMainContext:
0066  *
0067  * The `GMainContext` struct is an opaque data
0068  * type representing a set of sources to be handled in a main loop.
0069  */
0070 typedef struct _GMainContext            GMainContext;
0071
0072 /**
0073  * GMainLoop:
0074  *
0075  * The `GMainLoop` struct is an opaque data type
0076  * representing the main event loop of a GLib or GTK application.
0077  */
0078 typedef struct _GMainLoop               GMainLoop;
0079
0080 /**
0081  * GSource:
0082  *
0083  * The `GSource` struct is an opaque data type
0084  * representing an event source.
0085  */
0086 typedef struct _GSource                 GSource;
0087 typedef struct _GSourcePrivate          GSourcePrivate;
0088
0089 /**
0090  * GSourceCallbackFuncs:
0091  * @ref: Called when a reference is added to the callback object
0092  * @unref: Called when a reference to the callback object is dropped
0093  * @get: Called to extract the callback function and data from the
0094  *     callback object.
0095  *
0096  * The `GSourceCallbackFuncs` struct contains
0097  * functions for managing callback objects.
0098  */
0099 typedef struct _GSourceCallbackFuncs    GSourceCallbackFuncs;
0100
0101 /**
0102  * GSourceFuncs:
0103  * @prepare: (nullable): Called before all the file descriptors are polled. If
0104  *     the source can determine that it is ready here (without waiting for the
0105  *     results of the poll() call) it should return %TRUE. It can also return
0106  *     a @timeout_ value which should be the maximum timeout (in milliseconds)
0107  *     which should be passed to the poll() call. The actual timeout used will
0108  *     be -1 if all sources returned -1, or it will be the minimum of all
0109  *     the @timeout_ values returned which were >= 0.  Since 2.36 this may
0110  *     be %NULL, in which case the effect is as if the function always returns
0111  *     %FALSE with a timeout of -1.  If @prepare returns a
0112  *     timeout and the source also has a ready time set, then the
0113  *     lower of the two will be used.
0114  * @check: (nullable): Called after all the file descriptors are polled. The
0115  *     source should return %TRUE if it is ready to be dispatched. Note that
0116  *     some time may have passed since the previous prepare function was called,
0117  *     so the source should be checked again here.  Since 2.36 this may
0118  *     be %NULL, in which case the effect is as if the function always returns
0119  *     %FALSE.
0120  * @dispatch: Called to dispatch the event source, after it has returned
0121  *     %TRUE in either its @prepare or its @check function, or if a ready time
0122  *     has been reached. The @dispatch function receives a callback function and
0123  *     user data. The callback function may be %NULL if the source was never
0124  *     connected to a callback using [method@GLib.Source.set_callback]. The
0125  *     @dispatch function should call the callback function with @user_data and
0126  *     whatever additional parameters are needed for this type of event source.
0127  *     The return value of the @dispatch function should be
0128  *     [const@GLib.SOURCE_REMOVE] if the source should be removed or
0129  *     [const@GLib.SOURCE_CONTINUE] to keep it.
0130  * @finalize: (nullable): Called when the source is finalized. At this point,
0131  *     the source will have been destroyed, had its callback cleared, and have
0132  *     been removed from its [struct@GLib.MainContext], but it will still have
0133  *     its final reference count, so methods can be called on it from within
0134  *     this function. This may be %NULL, in which case the effect is as if the
0135  *     function does nothing and returns.
0136  *
0137  * The `GSourceFuncs` struct contains a table of
0138  * functions used to handle event sources in a generic manner.
0139  *
0140  * For idle sources, the prepare and check functions always return %TRUE
0141  * to indicate that the source is always ready to be processed. The prepare
0142  * function also returns a timeout value of 0 to ensure that the poll() call
0143  * doesn't block (since that would be time wasted which could have been spent
0144  * running the idle function).
0145  *
0146  * For timeout sources, the prepare and check functions both return %TRUE
0147  * if the timeout interval has expired. The prepare function also returns
0148  * a timeout value to ensure that the poll() call doesn't block too long
0149  * and miss the next timeout.
0150  *
0151  * For file descriptor sources, the prepare function typically returns %FALSE,
0152  * since it must wait until poll() has been called before it knows whether
0153  * any events need to be processed. It sets the returned timeout to -1 to
0154  * indicate that it doesn't mind how long the poll() call blocks. In the
0155  * check function, it tests the results of the poll() call to see if the
0156  * required condition has been met, and returns %TRUE if so.
0157  */
0158 typedef struct _GSourceFuncs            GSourceFuncs;
0159
0160 /**
0161  * GPid:
0162  *
0163  * A type which is used to hold a process identification.
0164  *
0165  * On UNIX, processes are identified by a process id (an integer),
0166  * while Windows uses process handles (which are pointers).
0167  *
0168  * GPid is used in GLib only for descendant processes spawned with
0169  * the g_spawn functions.
0170  */
0171 /* defined in glibconfig.h */
0172
0173 /**
0174  * G_PID_FORMAT:
0175  *
0176  * A format specifier that can be used in printf()-style format strings
0177  * when printing a #GPid.
0178  *
0179  * Since: 2.50
0180  */
0181 /* defined in glibconfig.h */
0182
0183 /**
0184  * GSourceFunc:
0185  * @user_data: data passed to the function, set when the source was
0186  *     created with one of the above functions
0187  *
0188  * Specifies the type of function passed to [func@GLib.timeout_add],
0189  * [func@GLib.timeout_add_full], [func@GLib.idle_add], and
0190  * [func@GLib.idle_add_full].
0191  *
0192  * When calling [method@GLib.Source.set_callback], you may need to cast a
0193  * function of a different type to this type. Use [func@GLib.SOURCE_FUNC] to
0194  * avoid warnings about incompatible function types.
0195  *
0196  * Returns: %FALSE if the source should be removed.
0197  * [const@GLib.SOURCE_CONTINUE] and [const@GLib.SOURCE_REMOVE] are more
0198  * memorable names for the return value.
0199  */
0200 typedef gboolean (*GSourceFunc)       (gpointer user_data);
0201
0202 /**
0203  * GSourceOnceFunc:
0204  * @user_data: data passed to the function, set when the source was
0205  *   created
0206  *
0207  * A source function that is only called once before being removed from the main
0208  * context automatically.
0209  *
0210  * See: [func@GLib.idle_add_once], [func@GLib.timeout_add_once]
0211  *
0212  * Since: 2.74
0213  */
0214 typedef void (* GSourceOnceFunc) (gpointer user_data);
0215
0216 /**
0217  * G_SOURCE_FUNC:
0218  * @f: a function pointer.
0219  *
0220  * Cast a function pointer to a [callback@GLib.SourceFunc], suppressing
0221  * warnings from GCC 8 onwards with `-Wextra` or `-Wcast-function-type` enabled
0222  * about the function types being incompatible.
0223  *
0224  * For example, the correct type of callback for a source created by
0225  * [func@GLib.child_watch_source_new] is #GChildWatchFunc, which accepts more
0226  * arguments than [callback@GLib.SourceFunc]. Casting the function with
0227  * `(GSourceFunc)` to call [method@GLib.Source.set_callback] will trigger a
0228  * warning, even though it will be cast back to the correct type before it is
0229  * called by the source.
0230  *
0231  * Since: 2.58
0232  */
0233 #define G_SOURCE_FUNC(f) ((GSourceFunc) (void (*)(void)) (f)) GLIB_AVAILABLE_MACRO_IN_2_58
0234
0235 /**
0236  * GChildWatchFunc:
0237  * @pid: the process id of the child process
0238  * @wait_status: Status information about the child process, encoded
0239  *               in a platform-specific manner
0240  * @user_data: user data passed to [func@GLib.child_watch_add]
0241  *
0242  * Prototype of a #GChildWatchSource callback, called when a child
0243  * process has exited.
0244  *
0245  * To interpret @wait_status, see the documentation for
0246  * [func@GLib.spawn_check_wait_status]. In particular,
0247  * on Unix platforms, note that it is usually not equal
0248  * to the integer passed to `exit()` or returned from `main()`.
0249  */
0250 typedef void     (*GChildWatchFunc)   (GPid     pid,
0251                                        gint     wait_status,
0252                                        gpointer user_data);
0253
0254
0255 /**
0256  * GSourceDisposeFunc:
0257  * @source: #GSource that is currently being disposed
0258  *
0259  * Dispose function for @source. See [method@GLib.Source.set_dispose_function]
0260  * for details.
0261  *
0262  * Since: 2.64
0263  */
0264 GLIB_AVAILABLE_TYPE_IN_2_64
0265 typedef void (*GSourceDisposeFunc)       (GSource *source);
0266
0267 struct _GSource
0268 {
0269   /*< private >*/
0270   gpointer callback_data;
0271   GSourceCallbackFuncs *callback_funcs;
0272
0273   const GSourceFuncs *source_funcs;
0274   guint ref_count;
0275
0276   GMainContext *context;
0277
0278   gint priority;
0279   guint flags; /* (atomic) */
0280   guint source_id;
0281
0282   GSList *poll_fds;
0283
0284   GSource *prev;
0285   GSource *next;
0286
0287   char    *name;
0288
0289   GSourcePrivate *priv;
0290 };
0291
0292 struct _GSourceCallbackFuncs
0293 {
0294   void (*ref)   (gpointer     cb_data);
0295   void (*unref) (gpointer     cb_data);
0296   void (*get)   (gpointer     cb_data,
0297                  GSource     *source,
0298                  GSourceFunc *func,
0299                  gpointer    *data);
0300 };
0301
0302 /**
0303  * GSourceDummyMarshal:
0304  *
0305  * This is just a placeholder for #GClosureMarshal,
0306  * which cannot be used here for dependency reasons.
0307  */
0308 typedef void (*GSourceDummyMarshal) (void);
0309
0310 /**
0311  * GSourceFuncsPrepareFunc:
0312  * @source: The #GSource
0313  * @timeout_: (out) (optional): the maximum timeout (in milliseconds) which should be passed to the poll call
0314  *
0315  * Checks the source for readiness.
0316  *
0317  * Called before all the file descriptors are polled. If the
0318  * source can determine that it is ready here (without waiting for the
0319  * results of the poll call) it should return %TRUE. It can also return
0320  * a @timeout_ value which should be the maximum timeout (in milliseconds)
0321  * which should be passed to the poll call. The actual timeout used will
0322  * be `-1` if all sources returned `-1`, or it will be the minimum of all
0323  * the @timeout_ values returned which were greater than or equal to `0`.
0324  * If the prepare function returns a timeout and the source also has a
0325  * ready time set, then the lower of the two will be used.
0326  *
0327  * Since 2.36 this may be `NULL`, in which case the effect is as if the
0328  * function always returns `FALSE` with a timeout of `-1`.
0329  *
0330  * Returns: %TRUE if the source is ready, %FALSE otherwise
0331  *
0332  * Since: 2.82
0333  */
0334 typedef gboolean (*GSourceFuncsPrepareFunc) (GSource *source,
0335                                              gint    *timeout_);
0336
0337 /**
0338  * GSourceFuncsCheckFunc:
0339  * @source: The #GSource
0340  *
0341  * Checks if the source is ready to be dispatched.
0342  *
0343  * Called after all the file descriptors are polled. The source
0344  * should return %TRUE if it is ready to be dispatched. Note that some
0345  * time may have passed since the previous prepare function was called,
0346  * so the source should be checked again here.
0347  *
0348  * Since 2.36 this may be `NULL`, in which case the effect is
0349  * as if the function always returns `FALSE`.
0350  *
0351  * Returns: %TRUE if ready to be dispatched, %FALSE otherwise
0352  *
0353  * Since: 2.82
0354  */
0355 typedef gboolean (*GSourceFuncsCheckFunc) (GSource *source);
0356
0357 /**
0358  * GSourceFuncsDispatchFunc:
0359  * @source: The #GSource
0360  * @callback: (nullable): The #GSourceFunc to call
0361  * @user_data: (nullable): data to pass to @callback
0362  *
0363  * Dispatches the source callback.
0364  *
0365  * Called to dispatch the event source, after it has returned
0366  * `TRUE` in either its prepare or its check function, or if a ready time
0367  * has been reached. The dispatch function receives a callback function and
0368  * user data. The callback function may be `NULL` if the source was never
0369  * connected to a callback using [method@GLib.Source.set_callback]. The dispatch
0370  * function should call the callback function with @user_data and whatever
0371  * additional parameters are needed for this type of event source. The
0372  * return value of the dispatch function should be [const@GLib.SOURCE_REMOVE]
0373  * if the source should be removed or [const@GLib.SOURCE_CONTINUE] to keep it.
0374  *
0375  * Returns: [const@GLib.SOURCE_REMOVE] if the source should be removed,
0376  *   [const@GLib.SOURCE_CONTINUE] otherwise.
0377  *
0378  * Since: 2.82
0379  */
0380 typedef gboolean (*GSourceFuncsDispatchFunc) (GSource     *source,
0381                                               GSourceFunc  callback,
0382                                               gpointer     user_data);
0383
0384 /**
0385  * GSourceFuncsFinalizeFunc:
0386  * @source: The #GSource
0387  *
0388  * Finalizes the source.
0389  *
0390  * Called when the source is finalized. At this point, the source
0391  * will have been destroyed, had its callback cleared, and have been removed
0392  * from its [type@GLib.MainContext], but it will still have its final reference
0393  * count, so methods can be called on it from within this function.
0394  *
0395  * Since: 2.82
0396  */
0397 typedef void (*GSourceFuncsFinalizeFunc) (GSource *source);
0398
0399 struct _GSourceFuncs
0400 {
0401   GSourceFuncsPrepareFunc prepare; /* Can be NULL */
0402   GSourceFuncsCheckFunc check;     /* Can be NULL */
0403   GSourceFuncsDispatchFunc dispatch;
0404   GSourceFuncsFinalizeFunc finalize; /* Can be NULL */
0405
0406   /*< private >*/
0407   /* For use by g_source_set_closure */
0408   GSourceFunc     closure_callback;
0409   GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
0410 };
0411
0412 /* Standard priorities */
0413
0414 /**
0415  * G_PRIORITY_HIGH:
0416  *
0417  * Use this for high priority event sources.
0418  *
0419  * It is not used within GLib or GTK.
0420  */
0421 #define G_PRIORITY_HIGH            -100
0422
0423 /**
0424  * G_PRIORITY_DEFAULT:
0425  *
0426  * Use this for default priority event sources.
0427  *
0428  * In GLib this priority is used when adding timeout functions
0429  * with [func@GLib.timeout_add]. In GDK this priority is used for events
0430  * from the X server.
0431  */
0432 #define G_PRIORITY_DEFAULT          0
0433
0434 /**
0435  * G_PRIORITY_HIGH_IDLE:
0436  *
0437  * Use this for high priority idle functions.
0438  *
0439  * GTK uses %G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
0440  * and %G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
0441  * done to ensure that any pending resizes are processed before any
0442  * pending redraws, so that widgets are not redrawn twice unnecessarily.)
0443  */
0444 #define G_PRIORITY_HIGH_IDLE        100
0445
0446 /**
0447  * G_PRIORITY_DEFAULT_IDLE:
0448  *
0449  * Use this for default priority idle functions.
0450  *
0451  * In GLib this priority is used when adding idle functions with
0452  * [func@GLib.idle_add].
0453  */
0454 #define G_PRIORITY_DEFAULT_IDLE     200
0455
0456 /**
0457  * G_PRIORITY_LOW:
0458  *
0459  * Use this for very low priority background tasks.
0460  *
0461  * It is not used within GLib or GTK.
0462  */
0463 #define G_PRIORITY_LOW              300
0464
0465 /**
0466  * G_SOURCE_REMOVE:
0467  *
0468  * Use this macro as the return value of a [callback@GLib.SourceFunc] to remove
0469  * the [struct@GLib.Source] from the main loop.
0470  *
0471  * Since: 2.32
0472  */
0473 #define G_SOURCE_REMOVE         FALSE
0474
0475 /**
0476  * G_SOURCE_CONTINUE:
0477  *
0478  * Use this macro as the return value of a [callback@GLib.SourceFunc] to leave
0479  * the [struct@GLib.Source] in the main loop.
0480  *
0481  * Since: 2.32
0482  */
0483 #define G_SOURCE_CONTINUE       TRUE
0484
0485 /* GMainContext: */
0486
0487 GLIB_AVAILABLE_IN_ALL
0488 GMainContext *g_main_context_new       (void);
0489 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0490 GLIB_AVAILABLE_IN_2_72
0491 GMainContext *g_main_context_new_with_flags (GMainContextFlags flags);
0492 G_GNUC_END_IGNORE_DEPRECATIONS
0493 GLIB_AVAILABLE_IN_ALL
0494 GMainContext *g_main_context_ref       (GMainContext *context);
0495 GLIB_AVAILABLE_IN_ALL
0496 void          g_main_context_unref     (GMainContext *context);
0497 GLIB_AVAILABLE_IN_ALL
0498 GMainContext *g_main_context_default   (void);
0499
0500 GLIB_AVAILABLE_IN_ALL
0501 gboolean      g_main_context_iteration (GMainContext *context,
0502                                         gboolean      may_block);
0503 GLIB_AVAILABLE_IN_ALL
0504 gboolean      g_main_context_pending   (GMainContext *context);
0505
0506 /* For implementation of legacy interfaces
0507  */
0508 GLIB_AVAILABLE_IN_ALL
0509 GSource      *g_main_context_find_source_by_id              (GMainContext *context,
0510                                                              guint         source_id);
0511 GLIB_AVAILABLE_IN_ALL
0512 GSource      *g_main_context_find_source_by_user_data       (GMainContext *context,
0513                                                              gpointer      user_data);
0514 GLIB_AVAILABLE_IN_ALL
0515 GSource      *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
0516                                                              GSourceFuncs *funcs,
0517                                                              gpointer      user_data);
0518
0519 /* Low level functions for implementing custom main loops.
0520  */
0521 GLIB_AVAILABLE_IN_ALL
0522 void     g_main_context_wakeup  (GMainContext *context);
0523 GLIB_AVAILABLE_IN_ALL
0524 gboolean g_main_context_acquire (GMainContext *context);
0525 GLIB_AVAILABLE_IN_ALL
0526 void     g_main_context_release (GMainContext *context);
0527 GLIB_AVAILABLE_IN_ALL
0528 gboolean g_main_context_is_owner (GMainContext *context);
0529 GLIB_DEPRECATED_IN_2_58_FOR(g_main_context_is_owner)
0530 gboolean g_main_context_wait    (GMainContext *context,
0531                                  GCond        *cond,
0532                                  GMutex       *mutex);
0533
0534 GLIB_AVAILABLE_IN_ALL
0535 gboolean g_main_context_prepare  (GMainContext *context,
0536                                   gint         *priority);
0537 GLIB_AVAILABLE_IN_ALL
0538 gint     g_main_context_query    (GMainContext *context,
0539                                   gint          max_priority,
0540                                   gint         *timeout_,
0541                                   GPollFD      *fds,
0542                                   gint          n_fds);
0543 GLIB_AVAILABLE_IN_ALL
0544 gboolean     g_main_context_check    (GMainContext *context,
0545                                       gint          max_priority,
0546                                       GPollFD      *fds,
0547                                       gint          n_fds);
0548 GLIB_AVAILABLE_IN_ALL
0549 void     g_main_context_dispatch (GMainContext *context);
0550
0551 GLIB_AVAILABLE_IN_ALL
0552 void     g_main_context_set_poll_func (GMainContext *context,
0553                                        GPollFunc     func);
0554 GLIB_AVAILABLE_IN_ALL
0555 GPollFunc g_main_context_get_poll_func (GMainContext *context);
0556
0557 /* Low level functions for use by source implementations
0558  */
0559 GLIB_AVAILABLE_IN_ALL
0560 void     g_main_context_add_poll    (GMainContext *context,
0561                                      GPollFD      *fd,
0562                                      gint          priority);
0563 GLIB_AVAILABLE_IN_ALL
0564 void     g_main_context_remove_poll (GMainContext *context,
0565                                      GPollFD      *fd);
0566
0567 GLIB_AVAILABLE_IN_ALL
0568 gint     g_main_depth               (void);
0569 GLIB_AVAILABLE_IN_ALL
0570 GSource *g_main_current_source      (void);
0571
0572 /* GMainContexts for other threads
0573  */
0574 GLIB_AVAILABLE_IN_ALL
0575 void          g_main_context_push_thread_default (GMainContext *context);
0576 GLIB_AVAILABLE_IN_ALL
0577 void          g_main_context_pop_thread_default  (GMainContext *context);
0578 GLIB_AVAILABLE_IN_ALL
0579 GMainContext *g_main_context_get_thread_default  (void);
0580 GLIB_AVAILABLE_IN_ALL
0581 GMainContext *g_main_context_ref_thread_default  (void);
0582
0583 /**
0584  * GMainContextPusher:
0585  *
0586  * Opaque type. See g_main_context_pusher_new() for details.
0587  *
0588  * Since: 2.64
0589  */
0590 typedef void GMainContextPusher GLIB_AVAILABLE_TYPE_IN_2_64;
0591
0592 /**
0593  * g_main_context_pusher_new:
0594  * @main_context: (transfer none): a main context to push
0595  *
0596  * Push @main_context as the new thread-default main context for the current
0597  * thread, using [method@GLib.MainContext.push_thread_default], and return a
0598  * new [alias@GLib.MainContextPusher]. Pop with g_main_context_pusher_free().
0599  * Using [method@GLib.MainContext.pop_thread_default] on @main_context while a
0600  * [alias@GLib.MainContextPusher] exists for it can lead to undefined behaviour.
0601  *
0602  * Using two [alias@GLib.MainContextPusher]s in the same scope is not allowed,
0603  * as it leads to an undefined pop order.
0604  *
0605  * This is intended to be used with g_autoptr().  Note that g_autoptr()
0606  * is only available when using GCC or clang, so the following example
0607  * will only work with those compilers:
0608  * |[
0609  * typedef struct
0610  * {
0611  *   ...
0612  *   GMainContext *context;
0613  *   ...
0614  * } MyObject;
0615  *
0616  * static void
0617  * my_object_do_stuff (MyObject *self)
0618  * {
0619  *   g_autoptr(GMainContextPusher) pusher = g_main_context_pusher_new (self->context);
0620  *
0621  *   // Code with main context as the thread default here
0622  *
0623  *   if (cond)
0624  *     // No need to pop
0625  *     return;
0626  *
0627  *   // Optionally early pop
0628  *   g_clear_pointer (&pusher, g_main_context_pusher_free);
0629  *
0630  *   // Code with main context no longer the thread default here
0631  * }
0632  * ]|
0633  *
0634  * Returns: (transfer full): a #GMainContextPusher
0635  * Since: 2.64
0636  */
0637 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0638 GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
0639 static inline GMainContextPusher *g_main_context_pusher_new (GMainContext *main_context);
0640
0641 GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
0642 static inline GMainContextPusher *
0643 g_main_context_pusher_new (GMainContext *main_context)
0644 {
0645   g_main_context_push_thread_default (main_context);
0646   return (GMainContextPusher *) main_context;
0647 }
0648 G_GNUC_END_IGNORE_DEPRECATIONS
0649
0650 /**
0651  * g_main_context_pusher_free:
0652  * @pusher: (transfer full): a #GMainContextPusher
0653  *
0654  * Pop @pusher’s main context as the thread default main context.
0655  * See g_main_context_pusher_new() for details.
0656  *
0657  * This will pop the [struct@GLib.MainContext] as the current thread-default
0658  * main context, but will not call [method@GLib.MainContext.unref] on it.
0659  *
0660  * Since: 2.64
0661  */
0662 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0663 GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
0664 static inline void g_main_context_pusher_free (GMainContextPusher *pusher);
0665
0666 GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
0667 static inline void
0668 g_main_context_pusher_free (GMainContextPusher *pusher)
0669 {
0670   g_main_context_pop_thread_default ((GMainContext *) pusher);
0671 }
0672 G_GNUC_END_IGNORE_DEPRECATIONS
0673
0674 /* GMainLoop: */
0675
0676 GLIB_AVAILABLE_IN_ALL
0677 GMainLoop *g_main_loop_new        (GMainContext *context,
0678                                    gboolean      is_running);
0679 GLIB_AVAILABLE_IN_ALL
0680 void       g_main_loop_run        (GMainLoop    *loop);
0681 GLIB_AVAILABLE_IN_ALL
0682 void       g_main_loop_quit       (GMainLoop    *loop);
0683 GLIB_AVAILABLE_IN_ALL
0684 GMainLoop *g_main_loop_ref        (GMainLoop    *loop);
0685 GLIB_AVAILABLE_IN_ALL
0686 void       g_main_loop_unref      (GMainLoop    *loop);
0687 GLIB_AVAILABLE_IN_ALL
0688 gboolean   g_main_loop_is_running (GMainLoop    *loop);
0689 GLIB_AVAILABLE_IN_ALL
0690 GMainContext *g_main_loop_get_context (GMainLoop    *loop);
0691
0692 /* GSource: */
0693
0694 GLIB_AVAILABLE_IN_ALL
0695 GSource *g_source_new             (GSourceFuncs   *source_funcs,
0696                                    guint           struct_size);
0697
0698 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0699 GLIB_AVAILABLE_IN_2_64
0700 void     g_source_set_dispose_function (GSource            *source,
0701                                         GSourceDisposeFunc  dispose);
0702 G_GNUC_END_IGNORE_DEPRECATIONS
0703
0704 GLIB_AVAILABLE_IN_ALL
0705 GSource *g_source_ref             (GSource        *source);
0706 GLIB_AVAILABLE_IN_ALL
0707 void     g_source_unref           (GSource        *source);
0708
0709 GLIB_AVAILABLE_IN_ALL
0710 guint    g_source_attach          (GSource        *source,
0711                                    GMainContext   *context);
0712 GLIB_AVAILABLE_IN_ALL
0713 void     g_source_destroy         (GSource        *source);
0714
0715 GLIB_AVAILABLE_IN_ALL
0716 void     g_source_set_priority    (GSource        *source,
0717                                    gint            priority);
0718 GLIB_AVAILABLE_IN_ALL
0719 gint     g_source_get_priority    (GSource        *source);
0720 GLIB_AVAILABLE_IN_ALL
0721 void     g_source_set_can_recurse (GSource        *source,
0722                                    gboolean        can_recurse);
0723 GLIB_AVAILABLE_IN_ALL
0724 gboolean g_source_get_can_recurse (GSource        *source);
0725 GLIB_AVAILABLE_IN_ALL
0726 guint    g_source_get_id          (GSource        *source);
0727
0728 GLIB_AVAILABLE_IN_ALL
0729 GMainContext *g_source_get_context (GSource       *source);
0730 GLIB_AVAILABLE_IN_2_86
0731 GMainContext *g_source_dup_context (GSource       *source);
0732
0733 GLIB_AVAILABLE_IN_ALL
0734 void     g_source_set_callback    (GSource        *source,
0735                                    GSourceFunc     func,
0736                                    gpointer        data,
0737                                    GDestroyNotify  notify);
0738
0739 GLIB_AVAILABLE_IN_ALL
0740 void     g_source_set_funcs       (GSource        *source,
0741                                    GSourceFuncs   *funcs);
0742 GLIB_AVAILABLE_IN_ALL
0743 gboolean g_source_is_destroyed    (GSource        *source);
0744
0745 GLIB_AVAILABLE_IN_ALL
0746 void                 g_source_set_name       (GSource        *source,
0747                                               const char     *name);
0748 GLIB_AVAILABLE_IN_2_70
0749 void                 g_source_set_static_name (GSource        *source,
0750                                                const char     *name);
0751 GLIB_AVAILABLE_IN_ALL
0752 const char *         g_source_get_name       (GSource        *source);
0753 GLIB_AVAILABLE_IN_ALL
0754 void                 g_source_set_name_by_id (guint           tag,
0755                                               const char     *name);
0756
0757 GLIB_AVAILABLE_IN_2_36
0758 void                 g_source_set_ready_time (GSource        *source,
0759                                               gint64          ready_time);
0760 GLIB_AVAILABLE_IN_2_36
0761 gint64               g_source_get_ready_time (GSource        *source);
0762
0763 #ifdef G_OS_UNIX
0764 GLIB_AVAILABLE_IN_2_36
0765 gpointer             g_source_add_unix_fd    (GSource        *source,
0766                                               gint            fd,
0767                                               GIOCondition    events);
0768 GLIB_AVAILABLE_IN_2_36
0769 void                 g_source_modify_unix_fd (GSource        *source,
0770                                               gpointer        tag,
0771                                               GIOCondition    new_events);
0772 GLIB_AVAILABLE_IN_2_36
0773 void                 g_source_remove_unix_fd (GSource        *source,
0774                                               gpointer        tag);
0775 GLIB_AVAILABLE_IN_2_36
0776 GIOCondition         g_source_query_unix_fd  (GSource        *source,
0777                                               gpointer        tag);
0778 #endif
0779
0780 /* Used to implement g_source_connect_closure and internally*/
0781 GLIB_AVAILABLE_IN_ALL
0782 void g_source_set_callback_indirect (GSource              *source,
0783                                      gpointer              callback_data,
0784                                      GSourceCallbackFuncs *callback_funcs);
0785
0786 GLIB_AVAILABLE_IN_ALL
0787 void     g_source_add_poll            (GSource        *source,
0788                        GPollFD        *fd);
0789 GLIB_AVAILABLE_IN_ALL
0790 void     g_source_remove_poll         (GSource        *source,
0791                        GPollFD        *fd);
0792
0793 GLIB_AVAILABLE_IN_ALL
0794 void     g_source_add_child_source    (GSource        *source,
0795                        GSource        *child_source);
0796 GLIB_AVAILABLE_IN_ALL
0797 void     g_source_remove_child_source (GSource        *source,
0798                        GSource        *child_source);
0799
0800 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0801 GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time)
0802 void     g_source_get_current_time (GSource        *source,
0803                                     GTimeVal       *timeval);
0804 G_GNUC_END_IGNORE_DEPRECATIONS
0805
0806 GLIB_AVAILABLE_IN_ALL
0807 gint64   g_source_get_time         (GSource        *source);
0808
0809  /* void g_source_connect_closure (GSource        *source,
0810                                   GClosure       *closure);
0811  */
0812
0813 /* Specific source types
0814  */
0815 GLIB_AVAILABLE_IN_ALL
0816 GSource *g_idle_source_new        (void);
0817 GLIB_AVAILABLE_IN_ALL
0818 GSource *g_child_watch_source_new (GPid pid);
0819 GLIB_AVAILABLE_IN_ALL
0820 GSource *g_timeout_source_new     (guint interval);
0821 GLIB_AVAILABLE_IN_ALL
0822 GSource *g_timeout_source_new_seconds (guint interval);
0823
0824 /* Miscellaneous functions
0825  */
0826 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0827 GLIB_DEPRECATED_IN_2_62_FOR(g_get_real_time)
0828 void   g_get_current_time                 (GTimeVal       *result);
0829 G_GNUC_END_IGNORE_DEPRECATIONS
0830
0831 GLIB_AVAILABLE_IN_ALL
0832 gint64 g_get_monotonic_time               (void);
0833 GLIB_AVAILABLE_IN_ALL
0834 gint64 g_get_real_time                    (void);
0835
0836
0837 /* Source manipulation by ID */
0838 GLIB_AVAILABLE_IN_ALL
0839 gboolean g_source_remove                     (guint          tag);
0840 GLIB_AVAILABLE_IN_ALL
0841 gboolean g_source_remove_by_user_data        (gpointer       user_data);
0842 GLIB_AVAILABLE_IN_ALL
0843 gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
0844                                               gpointer       user_data);
0845
0846 /**
0847  * GClearHandleFunc:
0848  * @handle_id: the handle ID to clear
0849  *
0850  * Specifies the type of function passed to [func@GLib.clear_handle_id] The
0851  * implementation is expected to free the resource identified by @handle_id;
0852  * for instance, if @handle_id is a [struct@GLib.Source] ID,
0853  * [func@GLib.Source.remove] can be used.
0854  *
0855  * Since: 2.56
0856  */
0857 typedef void (* GClearHandleFunc) (guint handle_id);
0858
0859 GLIB_AVAILABLE_IN_2_56
0860 void    g_clear_handle_id (guint           *tag_ptr,
0861                            GClearHandleFunc clear_func);
0862
0863 #define g_clear_handle_id(tag_ptr, clear_func)             \
0864   G_STMT_START {                                           \
0865     G_STATIC_ASSERT (sizeof *(tag_ptr) == sizeof (guint)); \
0866     guint *_tag_ptr = (guint *) (tag_ptr);                 \
0867     guint _handle_id;                                      \
0868                                                            \
0869     _handle_id = *_tag_ptr;                                \
0870     if (_handle_id > 0)                                    \
0871       {                                                    \
0872         *_tag_ptr = 0;                                     \
0873         clear_func (_handle_id);                           \
0874       }                                                    \
0875   } G_STMT_END                                             \
0876   GLIB_AVAILABLE_MACRO_IN_2_56
0877
0878 /**
0879  * g_steal_handle_id:
0880  * @handle_pointer: (inout) (not optional): a pointer to a handle ID
0881  *
0882  * Sets @handle_pointer to `0`, returning the value that was there before.
0883  *
0884  * Conceptually, this transfers the ownership of the handle ID from the
0885  * referenced variable to the ‘caller’ of the macro (ie: ‘steals’ the
0886  * handle ID).
0887  *
0888  * This can be very useful to make ownership transfer explicit, or to prevent
0889  * a handle from being released multiple times. For example:
0890  *
0891  * ```c
0892  * void
0893  * maybe_unsubscribe_signal (ContextStruct *data)
0894  * {
0895  *   if (some_complex_logic (data))
0896  *     {
0897  *       g_dbus_connection_signal_unsubscribe (data->connection,
0898  *                                             g_steal_handle_id (&data->subscription_id));
0899  *       // now data->subscription_id isn’t a dangling handle
0900  *     }
0901  * }
0902  * ```
0903  *
0904  * While [func@GLib.clear_handle_id] can be used in many of the same situations
0905  * as `g_steal_handle_id()`, this is one situation where it cannot be used, as
0906  * there is no way to pass the `GDBusConnection` to a
0907  * [type@GLib.ClearHandleFunc].
0908  *
0909  * Since: 2.84
0910  */
0911 GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
0912 static inline unsigned int g_steal_handle_id (unsigned int *handle_pointer);
0913
0914 GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
0915 static inline unsigned int
0916 g_steal_handle_id (unsigned int *handle_pointer)
0917 {
0918   unsigned int handle;
0919
0920   handle = *handle_pointer;
0921   *handle_pointer = 0;
0922
0923   return handle;
0924 }
0925
0926 /* Idles, child watchers and timeouts */
0927 GLIB_AVAILABLE_IN_ALL
0928 guint    g_timeout_add_full         (gint            priority,
0929                                      guint           interval,
0930                                      GSourceFunc     function,
0931                                      gpointer        data,
0932                                      GDestroyNotify  notify);
0933 GLIB_AVAILABLE_IN_ALL
0934 guint    g_timeout_add              (guint           interval,
0935                                      GSourceFunc     function,
0936                                      gpointer        data);
0937 GLIB_AVAILABLE_IN_2_74
0938 guint    g_timeout_add_once         (guint           interval,
0939                                      GSourceOnceFunc function,
0940                                      gpointer        data);
0941 GLIB_AVAILABLE_IN_ALL
0942 guint    g_timeout_add_seconds_full (gint            priority,
0943                                      guint           interval,
0944                                      GSourceFunc     function,
0945                                      gpointer        data,
0946                                      GDestroyNotify  notify);
0947 GLIB_AVAILABLE_IN_ALL
0948 guint    g_timeout_add_seconds      (guint           interval,
0949                                      GSourceFunc     function,
0950                                      gpointer        data);
0951 GLIB_AVAILABLE_IN_2_78
0952 guint    g_timeout_add_seconds_once (guint           interval,
0953                                      GSourceOnceFunc function,
0954                                      gpointer        data);
0955 GLIB_AVAILABLE_IN_ALL
0956 guint    g_child_watch_add_full     (gint            priority,
0957                                      GPid            pid,
0958                                      GChildWatchFunc function,
0959                                      gpointer        data,
0960                                      GDestroyNotify  notify);
0961 GLIB_AVAILABLE_IN_ALL
0962 guint    g_child_watch_add          (GPid            pid,
0963                                      GChildWatchFunc function,
0964                                      gpointer        data);
0965 GLIB_AVAILABLE_IN_ALL
0966 guint    g_idle_add                 (GSourceFunc     function,
0967                                      gpointer        data);
0968 GLIB_AVAILABLE_IN_ALL
0969 guint    g_idle_add_full            (gint            priority,
0970                                      GSourceFunc     function,
0971                                      gpointer        data,
0972                                      GDestroyNotify  notify);
0973 GLIB_AVAILABLE_IN_2_74
0974 guint    g_idle_add_once            (GSourceOnceFunc function,
0975                                      gpointer        data);
0976 GLIB_AVAILABLE_IN_ALL
0977 gboolean g_idle_remove_by_data      (gpointer        data);
0978
0979 GLIB_AVAILABLE_IN_ALL
0980 void     g_main_context_invoke_full (GMainContext   *context,
0981                                      gint            priority,
0982                                      GSourceFunc     function,
0983                                      gpointer        data,
0984                                      GDestroyNotify  notify);
0985 GLIB_AVAILABLE_IN_ALL
0986 void     g_main_context_invoke      (GMainContext   *context,
0987                                      GSourceFunc     function,
0988                                      gpointer        data);
0989
0990 /**
0991  * g_steal_fd:
0992  * @fd_ptr: (not optional) (inout): A pointer to a file descriptor
0993  *
0994  * Sets @fd_ptr to `-1`, returning the value that was there before.
0995  *
0996  * Conceptually, this transfers the ownership of the file descriptor
0997  * from the referenced variable to the caller of the function (i.e.
0998  * ‘steals’ the reference). This is very similar to [func@GLib.steal_pointer],
0999  * but for file descriptors.
1000  *
1001  * On POSIX platforms, this function is async-signal safe
1002  * (see [`signal(7)`](man:signal(7)) and
1003  * [`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a
1004  * signal handler or a #GSpawnChildSetupFunc.
1005  *
1006  * This function preserves the value of `errno`.
1007  *
1008  * Returns: the value that @fd_ptr previously had
1009  * Since: 2.70
1010  */
1011 GLIB_AVAILABLE_STATIC_INLINE_IN_2_70
1012 static inline int g_steal_fd (int *fd_ptr);
1013
1014 GLIB_AVAILABLE_STATIC_INLINE_IN_2_70
1015 static inline int
1016 g_steal_fd (int *fd_ptr)
1017 {
1018   int fd = *fd_ptr;
1019   *fd_ptr = -1;
1020   return fd;
1021 }
1022
1023 /* Hook for GClosure / GSource integration. Don't touch */
1024 GLIB_VAR GSourceFuncs g_timeout_funcs;
1025 GLIB_VAR GSourceFuncs g_child_watch_funcs;
1026 GLIB_VAR GSourceFuncs g_idle_funcs;
1027 #ifdef G_OS_UNIX
1028 GLIB_VAR GSourceFuncs g_unix_signal_funcs;
1029 GLIB_VAR GSourceFuncs g_unix_fd_source_funcs;
1030 #endif
1031
1032 G_END_DECLS
1033
1034 #endif /* __G_MAIN_H__ */