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