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
31G_BEGIN_DECLS
32
33typedef 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 [ctor@GLib.MainContext.new_with_flags] which affect the
52 * behaviour of a [struct@GLib.MainContext].
53 *
54 * Since: 2.72
55 */
56GLIB_AVAILABLE_TYPE_IN_2_72
57typedef 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 */
70typedef 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 */
78typedef struct _GMainLoop GMainLoop;
79
80/**
81 * GSource:
82 *
83 * The `GSource` struct is an opaque data type
84 * representing an event source.
85 */
86typedef struct _GSource GSource;
87typedef 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 */
99typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs;
100
101/**
102 * GSourceFuncs:
103 * @prepare: (nullable): Called before all the file descriptors are polled. If
104 * the 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: (nullable): Called after all the file descriptors are polled. The
115 * source should return %TRUE if it is ready to be dispatched. Note that
116 * some 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 [method@GLib.Source.set_callback]. The
125 * @dispatch function should call the callback function with @user_data and
126 * whatever additional parameters are needed for this type of event source.
127 * The return value of the @dispatch function should be
128 * [const@GLib.SOURCE_REMOVE] if the source should be removed or
129 * [const@GLib.SOURCE_CONTINUE] to keep it.
130 * @finalize: (nullable): Called when the source is finalized. At this point,
131 * the source will have been destroyed, had its callback cleared, and have
132 * been removed from its [struct@GLib.MainContext], but it will still have
133 * its final reference count, so methods can be called on it from within
134 * this function. This may be %NULL, in which case the effect is as if the
135 * function does nothing and returns.
136 *
137 * The `GSourceFuncs` struct contains a table of
138 * functions used to handle event sources in a generic manner.
139 *
140 * For idle sources, the prepare and check functions always return %TRUE
141 * to indicate that the source is always ready to be processed. The prepare
142 * function also returns a timeout value of 0 to ensure that the poll() call
143 * doesn't block (since that would be time wasted which could have been spent
144 * running the idle function).
145 *
146 * For timeout sources, the prepare and check functions both return %TRUE
147 * if the timeout interval has expired. The prepare function also returns
148 * a timeout value to ensure that the poll() call doesn't block too long
149 * and miss the next timeout.
150 *
151 * For file descriptor sources, the prepare function typically returns %FALSE,
152 * since it must wait until poll() has been called before it knows whether
153 * any events need to be processed. It sets the returned timeout to -1 to
154 * indicate that it doesn't mind how long the poll() call blocks. In the
155 * check function, it tests the results of the poll() call to see if the
156 * required condition has been met, and returns %TRUE if so.
157 */
158typedef struct _GSourceFuncs GSourceFuncs;
159
160/**
161 * GPid:
162 *
163 * A type which is used to hold a process identification.
164 *
165 * On UNIX, processes are identified by a process id (an integer),
166 * while Windows uses process handles (which are pointers).
167 *
168 * GPid is used in GLib only for descendant processes spawned with
169 * the g_spawn functions.
170 */
171/* defined in glibconfig.h */
172
173/**
174 * G_PID_FORMAT:
175 *
176 * A format specifier that can be used in printf()-style format strings
177 * when printing a #GPid.
178 *
179 * Since: 2.50
180 */
181/* defined in glibconfig.h */
182
183/**
184 * GSourceFunc:
185 * @user_data: data passed to the function, set when the source was
186 * created with one of the above functions
187 *
188 * Specifies the type of function passed to [func@GLib.timeout_add],
189 * [func@GLib.timeout_add_full], [func@GLib.idle_add], and
190 * [func@GLib.idle_add_full].
191 *
192 * When calling [method@GLib.Source.set_callback], you may need to cast a
193 * function of a different type to this type. Use [func@GLib.SOURCE_FUNC] to
194 * avoid warnings about incompatible function types.
195 *
196 * Returns: %FALSE if the source should be removed.
197 * [const@GLib.SOURCE_CONTINUE] and [const@GLib.SOURCE_REMOVE] are more
198 * memorable names for the return value.
199 */
200typedef gboolean (*GSourceFunc) (gpointer user_data);
201
202/**
203 * GSourceOnceFunc:
204 * @user_data: data passed to the function, set when the source was
205 * created
206 *
207 * A source function that is only called once before being removed from the main
208 * context automatically.
209 *
210 * See: [func@GLib.idle_add_once], [func@GLib.timeout_add_once]
211 *
212 * Since: 2.74
213 */
214typedef void (* GSourceOnceFunc) (gpointer user_data);
215
216/**
217 * G_SOURCE_FUNC:
218 * @f: a function pointer.
219 *
220 * Cast a function pointer to a [callback@GLib.SourceFunc], suppressing
221 * warnings from GCC 8 onwards with `-Wextra` or `-Wcast-function-type` enabled
222 * about the function types being incompatible.
223 *
224 * For example, the correct type of callback for a source created by
225 * [func@GLib.child_watch_source_new] is #GChildWatchFunc, which accepts more
226 * arguments than [callback@GLib.SourceFunc]. Casting the function with
227 * `(GSourceFunc)` to call [method@GLib.Source.set_callback] will trigger a
228 * warning, even though it will be cast back to the correct type before it is
229 * called by the source.
230 *
231 * Since: 2.58
232 */
233#define G_SOURCE_FUNC(f) ((GSourceFunc) (void (*)(void)) (f)) GLIB_AVAILABLE_MACRO_IN_2_58
234
235/**
236 * GChildWatchFunc:
237 * @pid: the process id of the child process
238 * @wait_status: Status information about the child process, encoded
239 * in a platform-specific manner
240 * @user_data: user data passed to [func@GLib.child_watch_add]
241 *
242 * Prototype of a #GChildWatchSource callback, called when a child
243 * process has exited.
244 *
245 * To interpret @wait_status, see the documentation for
246 * [func@GLib.spawn_check_wait_status]. In particular,
247 * on Unix platforms, note that it is usually not equal
248 * to the integer passed to `exit()` or returned from `main()`.
249 */
250typedef void (*GChildWatchFunc) (GPid pid,
251 gint wait_status,
252 gpointer user_data);
253
254
255/**
256 * GSourceDisposeFunc:
257 * @source: #GSource that is currently being disposed
258 *
259 * Dispose function for @source. See [method@GLib.Source.set_dispose_function]
260 * for details.
261 *
262 * Since: 2.64
263 */
264GLIB_AVAILABLE_TYPE_IN_2_64
265typedef void (*GSourceDisposeFunc) (GSource *source);
266
267struct _GSource
268{
269 /*< private >*/
270 gpointer callback_data;
271 GSourceCallbackFuncs *callback_funcs;
272
273 const GSourceFuncs *source_funcs;
274 guint ref_count;
275
276 GMainContext *context;
277
278 gint priority;
279 guint flags; /* (atomic) */
280 guint source_id;
281
282 GSList *poll_fds;
283
284 GSource *prev;
285 GSource *next;
286
287 char *name;
288
289 GSourcePrivate *priv;
290};
291
292struct _GSourceCallbackFuncs
293{
294 void (*ref) (gpointer cb_data);
295 void (*unref) (gpointer cb_data);
296 void (*get) (gpointer cb_data,
297 GSource *source,
298 GSourceFunc *func,
299 gpointer *data);
300};
301
302/**
303 * GSourceDummyMarshal:
304 *
305 * This is just a placeholder for #GClosureMarshal,
306 * which cannot be used here for dependency reasons.
307 */
308typedef void (*GSourceDummyMarshal) (void);
309
310/**
311 * GSourceFuncsPrepareFunc:
312 * @source: The #GSource
313 * @timeout_: (out) (optional): the maximum timeout (in milliseconds) which should be passed to the poll call
314 *
315 * Checks the source for readiness.
316 *
317 * Called before all the file descriptors are polled. If the
318 * source can determine that it is ready here (without waiting for the
319 * results of the poll call) it should return %TRUE. It can also return
320 * a @timeout_ value which should be the maximum timeout (in milliseconds)
321 * which should be passed to the poll call. The actual timeout used will
322 * be `-1` if all sources returned `-1`, or it will be the minimum of all
323 * the @timeout_ values returned which were greater than or equal to `0`.
324 * If the prepare function returns a timeout and the source also has a
325 * ready time set, then the lower of the two will be used.
326 *
327 * Since 2.36 this may be `NULL`, in which case the effect is as if the
328 * function always returns `FALSE` with a timeout of `-1`.
329 *
330 * Returns: %TRUE if the source is ready, %FALSE otherwise
331 *
332 * Since: 2.82
333 */
334typedef gboolean (*GSourceFuncsPrepareFunc) (GSource *source,
335 gint *timeout_);
336
337/**
338 * GSourceFuncsCheckFunc:
339 * @source: The #GSource
340 *
341 * Checks if the source is ready to be dispatched.
342 *
343 * Called after all the file descriptors are polled. The source
344 * should return %TRUE if it is ready to be dispatched. Note that some
345 * time may have passed since the previous prepare function was called,
346 * so the source should be checked again here.
347 *
348 * Since 2.36 this may be `NULL`, in which case the effect is
349 * as if the function always returns `FALSE`.
350 *
351 * Returns: %TRUE if ready to be dispatched, %FALSE otherwise
352 *
353 * Since: 2.82
354 */
355typedef gboolean (*GSourceFuncsCheckFunc) (GSource *source);
356
357/**
358 * GSourceFuncsDispatchFunc:
359 * @source: The #GSource
360 * @callback: (nullable): The #GSourceFunc to call
361 * @user_data: (nullable): data to pass to @callback
362 *
363 * Dispatches the source callback.
364 *
365 * Called to dispatch the event source, after it has returned
366 * `TRUE` in either its prepare or its check function, or if a ready time
367 * has been reached. The dispatch function receives a callback function and
368 * user data. The callback function may be `NULL` if the source was never
369 * connected to a callback using [method@GLib.Source.set_callback]. The dispatch
370 * function should call the callback function with @user_data and whatever
371 * additional parameters are needed for this type of event source. The
372 * return value of the dispatch function should be [const@GLib.SOURCE_REMOVE]
373 * if the source should be removed or [const@GLib.SOURCE_CONTINUE] to keep it.
374 *
375 * Returns: [const@GLib.SOURCE_REMOVE] if the source should be removed,
376 * [const@GLib.SOURCE_CONTINUE] otherwise.
377 *
378 * Since: 2.82
379 */
380typedef gboolean (*GSourceFuncsDispatchFunc) (GSource *source,
381 GSourceFunc callback,
382 gpointer user_data);
383
384/**
385 * GSourceFuncsFinalizeFunc:
386 * @source: The #GSource
387 *
388 * Finalizes the source.
389 *
390 * Called when the source is finalized. At this point, the source
391 * will have been destroyed, had its callback cleared, and have been removed
392 * from its [type@GLib.MainContext], but it will still have its final reference
393 * count, so methods can be called on it from within this function.
394 *
395 * Since: 2.82
396 */
397typedef void (*GSourceFuncsFinalizeFunc) (GSource *source);
398
399struct _GSourceFuncs
400{
401 GSourceFuncsPrepareFunc prepare; /* Can be NULL */
402 GSourceFuncsCheckFunc check; /* Can be NULL */
403 GSourceFuncsDispatchFunc dispatch;
404 GSourceFuncsFinalizeFunc finalize; /* Can be NULL */
405
406 /*< private >*/
407 /* For use by g_source_set_closure */
408 GSourceFunc closure_callback;
409 GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
410};
411
412/* Standard priorities */
413
414/**
415 * G_PRIORITY_HIGH:
416 *
417 * Use this for high priority event sources.
418 *
419 * It is not used within GLib or GTK.
420 */
421#define G_PRIORITY_HIGH -100
422
423/**
424 * G_PRIORITY_DEFAULT:
425 *
426 * Use this for default priority event sources.
427 *
428 * In GLib this priority is used when adding timeout functions
429 * with [func@GLib.timeout_add]. In GDK this priority is used for events
430 * from the X server.
431 */
432#define G_PRIORITY_DEFAULT 0
433
434/**
435 * G_PRIORITY_HIGH_IDLE:
436 *
437 * Use this for high priority idle functions.
438 *
439 * GTK uses %G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
440 * and %G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
441 * done to ensure that any pending resizes are processed before any
442 * pending redraws, so that widgets are not redrawn twice unnecessarily.)
443 */
444#define G_PRIORITY_HIGH_IDLE 100
445
446/**
447 * G_PRIORITY_DEFAULT_IDLE:
448 *
449 * Use this for default priority idle functions.
450 *
451 * In GLib this priority is used when adding idle functions with
452 * [func@GLib.idle_add].
453 */
454#define G_PRIORITY_DEFAULT_IDLE 200
455
456/**
457 * G_PRIORITY_LOW:
458 *
459 * Use this for very low priority background tasks.
460 *
461 * It is not used within GLib or GTK.
462 */
463#define G_PRIORITY_LOW 300
464
465/**
466 * G_SOURCE_REMOVE:
467 *
468 * Use this macro as the return value of a [callback@GLib.SourceFunc] to remove
469 * the [struct@GLib.Source] from the main loop.
470 *
471 * Since: 2.32
472 */
473#define G_SOURCE_REMOVE FALSE
474
475/**
476 * G_SOURCE_CONTINUE:
477 *
478 * Use this macro as the return value of a [callback@GLib.SourceFunc] to leave
479 * the [struct@GLib.Source] in the main loop.
480 *
481 * Since: 2.32
482 */
483#define G_SOURCE_CONTINUE TRUE
484
485/* GMainContext: */
486
487GLIB_AVAILABLE_IN_ALL
488GMainContext *g_main_context_new (void);
489G_GNUC_BEGIN_IGNORE_DEPRECATIONS
490GLIB_AVAILABLE_IN_2_72
491GMainContext *g_main_context_new_with_flags (GMainContextFlags flags);
492G_GNUC_END_IGNORE_DEPRECATIONS
493GLIB_AVAILABLE_IN_ALL
494GMainContext *g_main_context_ref (GMainContext *context);
495GLIB_AVAILABLE_IN_ALL
496void g_main_context_unref (GMainContext *context);
497GLIB_AVAILABLE_IN_ALL
498GMainContext *g_main_context_default (void);
499
500GLIB_AVAILABLE_IN_ALL
501gboolean g_main_context_iteration (GMainContext *context,
502 gboolean may_block);
503GLIB_AVAILABLE_IN_ALL
504gboolean g_main_context_pending (GMainContext *context);
505
506/* For implementation of legacy interfaces
507 */
508GLIB_AVAILABLE_IN_ALL
509GSource *g_main_context_find_source_by_id (GMainContext *context,
510 guint source_id);
511GLIB_AVAILABLE_IN_ALL
512GSource *g_main_context_find_source_by_user_data (GMainContext *context,
513 gpointer user_data);
514GLIB_AVAILABLE_IN_ALL
515GSource *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
516 GSourceFuncs *funcs,
517 gpointer user_data);
518
519/* Low level functions for implementing custom main loops.
520 */
521GLIB_AVAILABLE_IN_ALL
522void g_main_context_wakeup (GMainContext *context);
523GLIB_AVAILABLE_IN_ALL
524gboolean g_main_context_acquire (GMainContext *context);
525GLIB_AVAILABLE_IN_ALL
526void g_main_context_release (GMainContext *context);
527GLIB_AVAILABLE_IN_ALL
528gboolean g_main_context_is_owner (GMainContext *context);
529GLIB_DEPRECATED_IN_2_58_FOR(g_main_context_is_owner)
530gboolean g_main_context_wait (GMainContext *context,
531 GCond *cond,
532 GMutex *mutex);
533
534GLIB_AVAILABLE_IN_ALL
535gboolean g_main_context_prepare (GMainContext *context,
536 gint *priority);
537GLIB_AVAILABLE_IN_ALL
538gint g_main_context_query (GMainContext *context,
539 gint max_priority,
540 gint *timeout_,
541 GPollFD *fds,
542 gint n_fds);
543GLIB_AVAILABLE_IN_ALL
544gboolean g_main_context_check (GMainContext *context,
545 gint max_priority,
546 GPollFD *fds,
547 gint n_fds);
548GLIB_AVAILABLE_IN_ALL
549void g_main_context_dispatch (GMainContext *context);
550
551GLIB_AVAILABLE_IN_ALL
552void g_main_context_set_poll_func (GMainContext *context,
553 GPollFunc func);
554GLIB_AVAILABLE_IN_ALL
555GPollFunc g_main_context_get_poll_func (GMainContext *context);
556
557/* Low level functions for use by source implementations
558 */
559GLIB_AVAILABLE_IN_ALL
560void g_main_context_add_poll (GMainContext *context,
561 GPollFD *fd,
562 gint priority);
563GLIB_AVAILABLE_IN_ALL
564void g_main_context_remove_poll (GMainContext *context,
565 GPollFD *fd);
566
567GLIB_AVAILABLE_IN_ALL
568gint g_main_depth (void);
569GLIB_AVAILABLE_IN_ALL
570GSource *g_main_current_source (void);
571
572/* GMainContexts for other threads
573 */
574GLIB_AVAILABLE_IN_ALL
575void g_main_context_push_thread_default (GMainContext *context);
576GLIB_AVAILABLE_IN_ALL
577void g_main_context_pop_thread_default (GMainContext *context);
578GLIB_AVAILABLE_IN_ALL
579GMainContext *g_main_context_get_thread_default (void);
580GLIB_AVAILABLE_IN_ALL
581GMainContext *g_main_context_ref_thread_default (void);
582
583/**
584 * GMainContextPusher:
585 *
586 * Opaque type. See g_main_context_pusher_new() for details.
587 *
588 * Since: 2.64
589 */
590typedef void GMainContextPusher GLIB_AVAILABLE_TYPE_IN_2_64;
591
592/**
593 * g_main_context_pusher_new:
594 * @main_context: (transfer none): a main context to push
595 *
596 * Push @main_context as the new thread-default main context for the current
597 * thread, using [method@GLib.MainContext.push_thread_default], and return a
598 * new [alias@GLib.MainContextPusher]. Pop with g_main_context_pusher_free().
599 * Using [method@GLib.MainContext.pop_thread_default] on @main_context while a
600 * [alias@GLib.MainContextPusher] exists for it can lead to undefined behaviour.
601 *
602 * Using two [alias@GLib.MainContextPusher]s in the same scope is not allowed,
603 * as it leads to an undefined pop order.
604 *
605 * This is intended to be used with g_autoptr(). Note that g_autoptr()
606 * is only available when using GCC or clang, so the following example
607 * will only work with those compilers:
608 * |[
609 * typedef struct
610 * {
611 * ...
612 * GMainContext *context;
613 * ...
614 * } MyObject;
615 *
616 * static void
617 * my_object_do_stuff (MyObject *self)
618 * {
619 * g_autoptr(GMainContextPusher) pusher = g_main_context_pusher_new (self->context);
620 *
621 * // Code with main context as the thread default here
622 *
623 * if (cond)
624 * // No need to pop
625 * return;
626 *
627 * // Optionally early pop
628 * g_clear_pointer (&pusher, g_main_context_pusher_free);
629 *
630 * // Code with main context no longer the thread default here
631 * }
632 * ]|
633 *
634 * Returns: (transfer full): a #GMainContextPusher
635 * Since: 2.64
636 */
637G_GNUC_BEGIN_IGNORE_DEPRECATIONS
638GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
639static inline GMainContextPusher *g_main_context_pusher_new (GMainContext *main_context);
640
641GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
642static inline GMainContextPusher *
643g_main_context_pusher_new (GMainContext *main_context)
644{
645 g_main_context_push_thread_default (context: main_context);
646 return (GMainContextPusher *) main_context;
647}
648G_GNUC_END_IGNORE_DEPRECATIONS
649
650/**
651 * g_main_context_pusher_free:
652 * @pusher: (transfer full): a #GMainContextPusher
653 *
654 * Pop @pusher’s main context as the thread default main context.
655 * See g_main_context_pusher_new() for details.
656 *
657 * This will pop the [struct@GLib.MainContext] as the current thread-default
658 * main context, but will not call [method@GLib.MainContext.unref] on it.
659 *
660 * Since: 2.64
661 */
662G_GNUC_BEGIN_IGNORE_DEPRECATIONS
663GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
664static inline void g_main_context_pusher_free (GMainContextPusher *pusher);
665
666GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
667static inline void
668g_main_context_pusher_free (GMainContextPusher *pusher)
669{
670 g_main_context_pop_thread_default (context: (GMainContext *) pusher);
671}
672G_GNUC_END_IGNORE_DEPRECATIONS
673
674/* GMainLoop: */
675
676GLIB_AVAILABLE_IN_ALL
677GMainLoop *g_main_loop_new (GMainContext *context,
678 gboolean is_running);
679GLIB_AVAILABLE_IN_ALL
680void g_main_loop_run (GMainLoop *loop);
681GLIB_AVAILABLE_IN_ALL
682void g_main_loop_quit (GMainLoop *loop);
683GLIB_AVAILABLE_IN_ALL
684GMainLoop *g_main_loop_ref (GMainLoop *loop);
685GLIB_AVAILABLE_IN_ALL
686void g_main_loop_unref (GMainLoop *loop);
687GLIB_AVAILABLE_IN_ALL
688gboolean g_main_loop_is_running (GMainLoop *loop);
689GLIB_AVAILABLE_IN_ALL
690GMainContext *g_main_loop_get_context (GMainLoop *loop);
691
692/* GSource: */
693
694GLIB_AVAILABLE_IN_ALL
695GSource *g_source_new (GSourceFuncs *source_funcs,
696 guint struct_size);
697
698G_GNUC_BEGIN_IGNORE_DEPRECATIONS
699GLIB_AVAILABLE_IN_2_64
700void g_source_set_dispose_function (GSource *source,
701 GSourceDisposeFunc dispose);
702G_GNUC_END_IGNORE_DEPRECATIONS
703
704GLIB_AVAILABLE_IN_ALL
705GSource *g_source_ref (GSource *source);
706GLIB_AVAILABLE_IN_ALL
707void g_source_unref (GSource *source);
708
709GLIB_AVAILABLE_IN_ALL
710guint g_source_attach (GSource *source,
711 GMainContext *context);
712GLIB_AVAILABLE_IN_ALL
713void g_source_destroy (GSource *source);
714
715GLIB_AVAILABLE_IN_ALL
716void g_source_set_priority (GSource *source,
717 gint priority);
718GLIB_AVAILABLE_IN_ALL
719gint g_source_get_priority (GSource *source);
720GLIB_AVAILABLE_IN_ALL
721void g_source_set_can_recurse (GSource *source,
722 gboolean can_recurse);
723GLIB_AVAILABLE_IN_ALL
724gboolean g_source_get_can_recurse (GSource *source);
725GLIB_AVAILABLE_IN_ALL
726guint g_source_get_id (GSource *source);
727
728GLIB_AVAILABLE_IN_ALL
729GMainContext *g_source_get_context (GSource *source);
730GLIB_AVAILABLE_IN_2_86
731GMainContext *g_source_dup_context (GSource *source);
732
733GLIB_AVAILABLE_IN_ALL
734void g_source_set_callback (GSource *source,
735 GSourceFunc func,
736 gpointer data,
737 GDestroyNotify notify);
738
739GLIB_AVAILABLE_IN_ALL
740void g_source_set_funcs (GSource *source,
741 GSourceFuncs *funcs);
742GLIB_AVAILABLE_IN_ALL
743gboolean g_source_is_destroyed (GSource *source);
744
745GLIB_AVAILABLE_IN_ALL
746void g_source_set_name (GSource *source,
747 const char *name);
748GLIB_AVAILABLE_IN_2_70
749void g_source_set_static_name (GSource *source,
750 const char *name);
751GLIB_AVAILABLE_IN_ALL
752const char * g_source_get_name (GSource *source);
753GLIB_AVAILABLE_IN_ALL
754void g_source_set_name_by_id (guint tag,
755 const char *name);
756
757GLIB_AVAILABLE_IN_2_36
758void g_source_set_ready_time (GSource *source,
759 gint64 ready_time);
760GLIB_AVAILABLE_IN_2_36
761gint64 g_source_get_ready_time (GSource *source);
762
763#ifdef G_OS_UNIX
764GLIB_AVAILABLE_IN_2_36
765gpointer g_source_add_unix_fd (GSource *source,
766 gint fd,
767 GIOCondition events);
768GLIB_AVAILABLE_IN_2_36
769void g_source_modify_unix_fd (GSource *source,
770 gpointer tag,
771 GIOCondition new_events);
772GLIB_AVAILABLE_IN_2_36
773void g_source_remove_unix_fd (GSource *source,
774 gpointer tag);
775GLIB_AVAILABLE_IN_2_36
776GIOCondition g_source_query_unix_fd (GSource *source,
777 gpointer tag);
778#endif
779
780/* Used to implement g_source_connect_closure and internally*/
781GLIB_AVAILABLE_IN_ALL
782void g_source_set_callback_indirect (GSource *source,
783 gpointer callback_data,
784 GSourceCallbackFuncs *callback_funcs);
785
786GLIB_AVAILABLE_IN_ALL
787void g_source_add_poll (GSource *source,
788 GPollFD *fd);
789GLIB_AVAILABLE_IN_ALL
790void g_source_remove_poll (GSource *source,
791 GPollFD *fd);
792
793GLIB_AVAILABLE_IN_ALL
794void g_source_add_child_source (GSource *source,
795 GSource *child_source);
796GLIB_AVAILABLE_IN_ALL
797void g_source_remove_child_source (GSource *source,
798 GSource *child_source);
799
800G_GNUC_BEGIN_IGNORE_DEPRECATIONS
801GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time)
802void g_source_get_current_time (GSource *source,
803 GTimeVal *timeval);
804G_GNUC_END_IGNORE_DEPRECATIONS
805
806GLIB_AVAILABLE_IN_ALL
807gint64 g_source_get_time (GSource *source);
808
809 /* void g_source_connect_closure (GSource *source,
810 GClosure *closure);
811 */
812
813/* Specific source types
814 */
815GLIB_AVAILABLE_IN_ALL
816GSource *g_idle_source_new (void);
817GLIB_AVAILABLE_IN_ALL
818GSource *g_child_watch_source_new (GPid pid);
819GLIB_AVAILABLE_IN_ALL
820GSource *g_timeout_source_new (guint interval);
821GLIB_AVAILABLE_IN_ALL
822GSource *g_timeout_source_new_seconds (guint interval);
823
824/* Miscellaneous functions
825 */
826G_GNUC_BEGIN_IGNORE_DEPRECATIONS
827GLIB_DEPRECATED_IN_2_62_FOR(g_get_real_time)
828void g_get_current_time (GTimeVal *result);
829G_GNUC_END_IGNORE_DEPRECATIONS
830
831GLIB_AVAILABLE_IN_ALL
832gint64 g_get_monotonic_time (void);
833GLIB_AVAILABLE_IN_ALL
834gint64 g_get_real_time (void);
835
836
837/* Source manipulation by ID */
838GLIB_AVAILABLE_IN_ALL
839gboolean g_source_remove (guint tag);
840GLIB_AVAILABLE_IN_ALL
841gboolean g_source_remove_by_user_data (gpointer user_data);
842GLIB_AVAILABLE_IN_ALL
843gboolean g_source_remove_by_funcs_user_data (GSourceFuncs *funcs,
844 gpointer user_data);
845
846/**
847 * GClearHandleFunc:
848 * @handle_id: the handle ID to clear
849 *
850 * Specifies the type of function passed to [func@GLib.clear_handle_id] The
851 * implementation is expected to free the resource identified by @handle_id;
852 * for instance, if @handle_id is a [struct@GLib.Source] ID,
853 * [func@GLib.Source.remove] can be used.
854 *
855 * Since: 2.56
856 */
857typedef void (* GClearHandleFunc) (guint handle_id);
858
859GLIB_AVAILABLE_IN_2_56
860void g_clear_handle_id (guint *tag_ptr,
861 GClearHandleFunc clear_func);
862
863#define g_clear_handle_id(tag_ptr, clear_func) \
864 G_STMT_START { \
865 G_STATIC_ASSERT (sizeof *(tag_ptr) == sizeof (guint)); \
866 guint *_tag_ptr = (guint *) (tag_ptr); \
867 guint _handle_id; \
868 \
869 _handle_id = *_tag_ptr; \
870 if (_handle_id > 0) \
871 { \
872 *_tag_ptr = 0; \
873 clear_func (_handle_id); \
874 } \
875 } G_STMT_END \
876 GLIB_AVAILABLE_MACRO_IN_2_56
877
878/**
879 * g_steal_handle_id:
880 * @handle_pointer: (inout) (not optional): a pointer to a handle ID
881 *
882 * Sets @handle_pointer to `0`, returning the value that was there before.
883 *
884 * Conceptually, this transfers the ownership of the handle ID from the
885 * referenced variable to the ‘caller’ of the macro (ie: ‘steals’ the
886 * handle ID).
887 *
888 * This can be very useful to make ownership transfer explicit, or to prevent
889 * a handle from being released multiple times. For example:
890 *
891 * ```c
892 * void
893 * maybe_unsubscribe_signal (ContextStruct *data)
894 * {
895 * if (some_complex_logic (data))
896 * {
897 * g_dbus_connection_signal_unsubscribe (data->connection,
898 * g_steal_handle_id (&data->subscription_id));
899 * // now data->subscription_id isn’t a dangling handle
900 * }
901 * }
902 * ```
903 *
904 * While [func@GLib.clear_handle_id] can be used in many of the same situations
905 * as `g_steal_handle_id()`, this is one situation where it cannot be used, as
906 * there is no way to pass the `GDBusConnection` to a
907 * [type@GLib.ClearHandleFunc].
908 *
909 * Since: 2.84
910 */
911GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
912static inline unsigned int g_steal_handle_id (unsigned int *handle_pointer);
913
914GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
915static inline unsigned int
916g_steal_handle_id (unsigned int *handle_pointer)
917{
918 unsigned int handle;
919
920 handle = *handle_pointer;
921 *handle_pointer = 0;
922
923 return handle;
924}
925
926/* Idles, child watchers and timeouts */
927GLIB_AVAILABLE_IN_ALL
928guint g_timeout_add_full (gint priority,
929 guint interval,
930 GSourceFunc function,
931 gpointer data,
932 GDestroyNotify notify);
933GLIB_AVAILABLE_IN_ALL
934guint g_timeout_add (guint interval,
935 GSourceFunc function,
936 gpointer data);
937GLIB_AVAILABLE_IN_2_74
938guint g_timeout_add_once (guint interval,
939 GSourceOnceFunc function,
940 gpointer data);
941GLIB_AVAILABLE_IN_ALL
942guint g_timeout_add_seconds_full (gint priority,
943 guint interval,
944 GSourceFunc function,
945 gpointer data,
946 GDestroyNotify notify);
947GLIB_AVAILABLE_IN_ALL
948guint g_timeout_add_seconds (guint interval,
949 GSourceFunc function,
950 gpointer data);
951GLIB_AVAILABLE_IN_2_78
952guint g_timeout_add_seconds_once (guint interval,
953 GSourceOnceFunc function,
954 gpointer data);
955GLIB_AVAILABLE_IN_ALL
956guint g_child_watch_add_full (gint priority,
957 GPid pid,
958 GChildWatchFunc function,
959 gpointer data,
960 GDestroyNotify notify);
961GLIB_AVAILABLE_IN_ALL
962guint g_child_watch_add (GPid pid,
963 GChildWatchFunc function,
964 gpointer data);
965GLIB_AVAILABLE_IN_ALL
966guint g_idle_add (GSourceFunc function,
967 gpointer data);
968GLIB_AVAILABLE_IN_ALL
969guint g_idle_add_full (gint priority,
970 GSourceFunc function,
971 gpointer data,
972 GDestroyNotify notify);
973GLIB_AVAILABLE_IN_2_74
974guint g_idle_add_once (GSourceOnceFunc function,
975 gpointer data);
976GLIB_AVAILABLE_IN_ALL
977gboolean g_idle_remove_by_data (gpointer data);
978
979GLIB_AVAILABLE_IN_ALL
980void g_main_context_invoke_full (GMainContext *context,
981 gint priority,
982 GSourceFunc function,
983 gpointer data,
984 GDestroyNotify notify);
985GLIB_AVAILABLE_IN_ALL
986void g_main_context_invoke (GMainContext *context,
987 GSourceFunc function,
988 gpointer data);
989
990/**
991 * g_steal_fd:
992 * @fd_ptr: (not optional) (inout): A pointer to a file descriptor
993 *
994 * Sets @fd_ptr to `-1`, returning the value that was there before.
995 *
996 * Conceptually, this transfers the ownership of the file descriptor
997 * from the referenced variable to the caller of the function (i.e.
998 * ‘steals’ the reference). This is very similar to [func@GLib.steal_pointer],
999 * 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 */
1011GLIB_AVAILABLE_STATIC_INLINE_IN_2_70
1012static inline int g_steal_fd (int *fd_ptr);
1013
1014GLIB_AVAILABLE_STATIC_INLINE_IN_2_70
1015static inline int
1016g_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 */
1024GLIB_VAR GSourceFuncs g_timeout_funcs;
1025GLIB_VAR GSourceFuncs g_child_watch_funcs;
1026GLIB_VAR GSourceFuncs g_idle_funcs;
1027#ifdef G_OS_UNIX
1028GLIB_VAR GSourceFuncs g_unix_signal_funcs;
1029GLIB_VAR GSourceFuncs g_unix_fd_source_funcs;
1030#endif
1031
1032G_END_DECLS
1033
1034#endif /* __G_MAIN_H__ */
1035