Branch data Line data Source code
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 : :
33 : : G_BEGIN_DECLS
34 : :
35 : : typedef 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 : : */
58 : : GLIB_AVAILABLE_TYPE_IN_2_72
59 : : typedef 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 : : */
72 : : typedef 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 : : */
80 : : typedef struct _GMainLoop GMainLoop;
81 : :
82 : : /**
83 : : * GSource:
84 : : *
85 : : * The `GSource` struct is an opaque data type
86 : : * representing an event source.
87 : : */
88 : : typedef struct _GSource GSource;
89 : : typedef 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 : : */
101 : : typedef 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 : : */
160 : : typedef 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 : : */
202 : : typedef 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 : : */
216 : : typedef 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 : : */
252 : : typedef 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 : : */
266 : : GLIB_AVAILABLE_TYPE_IN_2_64
267 : : typedef void (*GSourceDisposeFunc) (GSource *source);
268 : :
269 : : struct _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 : :
294 : : struct _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 : : */
310 : : typedef 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 : : */
336 : : typedef 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 : : */
357 : : typedef 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 : : */
382 : : typedef 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 : : */
399 : : typedef void (*GSourceFuncsFinalizeFunc) (GSource *source);
400 : :
401 : : struct _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 : :
489 : : GLIB_AVAILABLE_IN_ALL
490 : : GMainContext *g_main_context_new (void);
491 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
492 : : GLIB_AVAILABLE_IN_2_72
493 : : GMainContext *g_main_context_new_with_flags (GMainContextFlags flags);
494 : : G_GNUC_END_IGNORE_DEPRECATIONS
495 : : GLIB_AVAILABLE_IN_ALL
496 : : GMainContext *g_main_context_ref (GMainContext *context);
497 : : GLIB_AVAILABLE_IN_ALL
498 : : void g_main_context_unref (GMainContext *context);
499 : : GLIB_AVAILABLE_IN_ALL
500 : : GMainContext *g_main_context_default (void);
501 : :
502 : : GLIB_AVAILABLE_IN_ALL
503 : : gboolean g_main_context_iteration (GMainContext *context,
504 : : gboolean may_block);
505 : : GLIB_AVAILABLE_IN_ALL
506 : : gboolean g_main_context_pending (GMainContext *context);
507 : :
508 : : /* For implementation of legacy interfaces
509 : : */
510 : : GLIB_AVAILABLE_IN_ALL
511 : : GSource *g_main_context_find_source_by_id (GMainContext *context,
512 : : guint source_id);
513 : : GLIB_AVAILABLE_IN_ALL
514 : : GSource *g_main_context_find_source_by_user_data (GMainContext *context,
515 : : gpointer user_data);
516 : : GLIB_AVAILABLE_IN_ALL
517 : : GSource *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 : : */
523 : : GLIB_AVAILABLE_IN_ALL
524 : : void g_main_context_wakeup (GMainContext *context);
525 : : GLIB_AVAILABLE_IN_ALL
526 : : gboolean g_main_context_acquire (GMainContext *context);
527 : : GLIB_AVAILABLE_IN_ALL
528 : : void g_main_context_release (GMainContext *context);
529 : : GLIB_AVAILABLE_IN_ALL
530 : : gboolean g_main_context_is_owner (GMainContext *context);
531 : : GLIB_DEPRECATED_IN_2_58_FOR(g_main_context_is_owner)
532 : : gboolean g_main_context_wait (GMainContext *context,
533 : : GCond *cond,
534 : : GMutex *mutex);
535 : :
536 : : GLIB_AVAILABLE_IN_ALL
537 : : gboolean g_main_context_prepare (GMainContext *context,
538 : : gint *priority);
539 : : GLIB_AVAILABLE_IN_ALL
540 : : gint g_main_context_query (GMainContext *context,
541 : : gint max_priority,
542 : : gint *timeout_,
543 : : GPollFD *fds,
544 : : gint n_fds);
545 : : GLIB_AVAILABLE_IN_ALL
546 : : gboolean g_main_context_check (GMainContext *context,
547 : : gint max_priority,
548 : : GPollFD *fds,
549 : : gint n_fds);
550 : : GLIB_AVAILABLE_IN_ALL
551 : : void g_main_context_dispatch (GMainContext *context);
552 : :
553 : : GLIB_AVAILABLE_IN_ALL
554 : : void g_main_context_set_poll_func (GMainContext *context,
555 : : GPollFunc func);
556 : : GLIB_AVAILABLE_IN_ALL
557 : : GPollFunc g_main_context_get_poll_func (GMainContext *context);
558 : :
559 : : /* Low level functions for use by source implementations
560 : : */
561 : : GLIB_AVAILABLE_IN_ALL
562 : : void g_main_context_add_poll (GMainContext *context,
563 : : GPollFD *fd,
564 : : gint priority);
565 : : GLIB_AVAILABLE_IN_ALL
566 : : void g_main_context_remove_poll (GMainContext *context,
567 : : GPollFD *fd);
568 : :
569 : : GLIB_AVAILABLE_IN_ALL
570 : : gint g_main_depth (void);
571 : : GLIB_AVAILABLE_IN_ALL
572 : : GSource *g_main_current_source (void);
573 : :
574 : : /* GMainContexts for other threads
575 : : */
576 : : GLIB_AVAILABLE_IN_ALL
577 : : void g_main_context_push_thread_default (GMainContext *context);
578 : : GLIB_AVAILABLE_IN_ALL
579 : : void g_main_context_pop_thread_default (GMainContext *context);
580 : : GLIB_AVAILABLE_IN_ALL
581 : : GMainContext *g_main_context_get_thread_default (void);
582 : : GLIB_AVAILABLE_IN_ALL
583 : : GMainContext *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 : : */
592 : : typedef 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 : : */
639 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
640 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
641 : : static inline GMainContextPusher *g_main_context_pusher_new (GMainContext *main_context);
642 : :
643 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
644 : : static inline GMainContextPusher *
645 : 2 : g_main_context_pusher_new (GMainContext *main_context)
646 : : {
647 : 2 : g_main_context_push_thread_default (main_context);
648 : 2 : return (GMainContextPusher *) main_context;
649 : : }
650 : : G_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 : : */
664 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
665 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
666 : : static inline void g_main_context_pusher_free (GMainContextPusher *pusher);
667 : :
668 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
669 : : static inline void
670 : 2 : g_main_context_pusher_free (GMainContextPusher *pusher)
671 : : {
672 : 2 : g_main_context_pop_thread_default ((GMainContext *) pusher);
673 : 2 : }
674 : : G_GNUC_END_IGNORE_DEPRECATIONS
675 : :
676 : : /* GMainLoop: */
677 : :
678 : : GLIB_AVAILABLE_IN_ALL
679 : : GMainLoop *g_main_loop_new (GMainContext *context,
680 : : gboolean is_running);
681 : : GLIB_AVAILABLE_IN_ALL
682 : : void g_main_loop_run (GMainLoop *loop);
683 : : GLIB_AVAILABLE_IN_ALL
684 : : void g_main_loop_quit (GMainLoop *loop);
685 : : GLIB_AVAILABLE_IN_ALL
686 : : GMainLoop *g_main_loop_ref (GMainLoop *loop);
687 : : GLIB_AVAILABLE_IN_ALL
688 : : void g_main_loop_unref (GMainLoop *loop);
689 : : GLIB_AVAILABLE_IN_ALL
690 : : gboolean g_main_loop_is_running (GMainLoop *loop);
691 : : GLIB_AVAILABLE_IN_ALL
692 : : GMainContext *g_main_loop_get_context (GMainLoop *loop);
693 : :
694 : : /* GSource: */
695 : :
696 : : GLIB_AVAILABLE_IN_ALL
697 : : GSource *g_source_new (GSourceFuncs *source_funcs,
698 : : guint struct_size);
699 : :
700 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
701 : : GLIB_AVAILABLE_IN_2_64
702 : : void g_source_set_dispose_function (GSource *source,
703 : : GSourceDisposeFunc dispose);
704 : : G_GNUC_END_IGNORE_DEPRECATIONS
705 : :
706 : : GLIB_AVAILABLE_IN_ALL
707 : : GSource *g_source_ref (GSource *source);
708 : : GLIB_AVAILABLE_IN_ALL
709 : : void g_source_unref (GSource *source);
710 : :
711 : : GLIB_AVAILABLE_IN_ALL
712 : : guint g_source_attach (GSource *source,
713 : : GMainContext *context);
714 : : GLIB_AVAILABLE_IN_ALL
715 : : void g_source_destroy (GSource *source);
716 : :
717 : : GLIB_AVAILABLE_IN_ALL
718 : : void g_source_set_priority (GSource *source,
719 : : gint priority);
720 : : GLIB_AVAILABLE_IN_ALL
721 : : gint g_source_get_priority (GSource *source);
722 : : GLIB_AVAILABLE_IN_ALL
723 : : void g_source_set_can_recurse (GSource *source,
724 : : gboolean can_recurse);
725 : : GLIB_AVAILABLE_IN_ALL
726 : : gboolean g_source_get_can_recurse (GSource *source);
727 : : GLIB_AVAILABLE_IN_ALL
728 : : guint g_source_get_id (GSource *source);
729 : :
730 : : GLIB_AVAILABLE_IN_ALL
731 : : GMainContext *g_source_get_context (GSource *source);
732 : : GLIB_AVAILABLE_IN_2_86
733 : : GMainContext *g_source_dup_context (GSource *source);
734 : :
735 : : GLIB_AVAILABLE_IN_ALL
736 : : void g_source_set_callback (GSource *source,
737 : : GSourceFunc func,
738 : : gpointer data,
739 : : GDestroyNotify notify);
740 : :
741 : : GLIB_AVAILABLE_IN_ALL
742 : : void g_source_set_funcs (GSource *source,
743 : : GSourceFuncs *funcs);
744 : : GLIB_AVAILABLE_IN_ALL
745 : : gboolean g_source_is_destroyed (GSource *source);
746 : :
747 : : GLIB_AVAILABLE_IN_ALL
748 : : void g_source_set_name (GSource *source,
749 : : const char *name);
750 : : GLIB_AVAILABLE_IN_2_70
751 : : void g_source_set_static_name (GSource *source,
752 : : const char *name);
753 : : GLIB_AVAILABLE_IN_ALL
754 : : const char * g_source_get_name (GSource *source);
755 : : GLIB_AVAILABLE_IN_ALL
756 : : void g_source_set_name_by_id (guint tag,
757 : : const char *name);
758 : :
759 : : GLIB_AVAILABLE_IN_2_36
760 : : void g_source_set_ready_time (GSource *source,
761 : : gint64 ready_time);
762 : : GLIB_AVAILABLE_IN_2_36
763 : : gint64 g_source_get_ready_time (GSource *source);
764 : :
765 : : #ifdef G_OS_UNIX
766 : : GLIB_AVAILABLE_IN_2_36
767 : : gpointer g_source_add_unix_fd (GSource *source,
768 : : gint fd,
769 : : GIOCondition events);
770 : : GLIB_AVAILABLE_IN_2_36
771 : : void g_source_modify_unix_fd (GSource *source,
772 : : gpointer tag,
773 : : GIOCondition new_events);
774 : : GLIB_AVAILABLE_IN_2_36
775 : : void g_source_remove_unix_fd (GSource *source,
776 : : gpointer tag);
777 : : GLIB_AVAILABLE_IN_2_36
778 : : GIOCondition g_source_query_unix_fd (GSource *source,
779 : : gpointer tag);
780 : : #endif
781 : :
782 : : /* Used to implement g_source_connect_closure and internally*/
783 : : GLIB_AVAILABLE_IN_ALL
784 : : void g_source_set_callback_indirect (GSource *source,
785 : : gpointer callback_data,
786 : : GSourceCallbackFuncs *callback_funcs);
787 : :
788 : : GLIB_AVAILABLE_IN_ALL
789 : : void g_source_add_poll (GSource *source,
790 : : GPollFD *fd);
791 : : GLIB_AVAILABLE_IN_ALL
792 : : void g_source_remove_poll (GSource *source,
793 : : GPollFD *fd);
794 : :
795 : : GLIB_AVAILABLE_IN_ALL
796 : : void g_source_add_child_source (GSource *source,
797 : : GSource *child_source);
798 : : GLIB_AVAILABLE_IN_ALL
799 : : void g_source_remove_child_source (GSource *source,
800 : : GSource *child_source);
801 : :
802 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
803 : : GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time)
804 : : void g_source_get_current_time (GSource *source,
805 : : GTimeVal *timeval);
806 : : G_GNUC_END_IGNORE_DEPRECATIONS
807 : :
808 : : GLIB_AVAILABLE_IN_ALL
809 : : gint64 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 : : */
817 : : GLIB_AVAILABLE_IN_ALL
818 : : GSource *g_idle_source_new (void);
819 : : GLIB_AVAILABLE_IN_ALL
820 : : GSource *g_child_watch_source_new (GPid pid);
821 : : GLIB_AVAILABLE_IN_ALL
822 : : GSource *g_timeout_source_new (guint interval);
823 : : GLIB_AVAILABLE_IN_ALL
824 : : GSource *g_timeout_source_new_seconds (guint interval);
825 : :
826 : : /* Miscellaneous functions
827 : : */
828 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
829 : : GLIB_DEPRECATED_IN_2_62_FOR(g_get_real_time)
830 : : void g_get_current_time (GTimeVal *result);
831 : : G_GNUC_END_IGNORE_DEPRECATIONS
832 : :
833 : : GLIB_AVAILABLE_IN_ALL
834 : : gint64 g_get_monotonic_time (void);
835 : : GLIB_AVAILABLE_IN_2_88
836 : : uint64_t g_get_monotonic_time_ns (void);
837 : : GLIB_AVAILABLE_IN_ALL
838 : : gint64 g_get_real_time (void);
839 : :
840 : :
841 : : /* Source manipulation by ID */
842 : : GLIB_AVAILABLE_IN_ALL
843 : : gboolean g_source_remove (guint tag);
844 : : GLIB_AVAILABLE_IN_ALL
845 : : gboolean g_source_remove_by_user_data (gpointer user_data);
846 : : GLIB_AVAILABLE_IN_ALL
847 : : gboolean 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 : : */
861 : : typedef void (* GClearHandleFunc) (guint handle_id);
862 : :
863 : : GLIB_AVAILABLE_IN_2_56
864 : : void 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 : : */
915 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
916 : : static inline unsigned int g_steal_handle_id (unsigned int *handle_pointer);
917 : :
918 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
919 : : static inline unsigned int
920 : 912 : g_steal_handle_id (unsigned int *handle_pointer)
921 : : {
922 : : unsigned int handle;
923 : :
924 : 912 : handle = *handle_pointer;
925 : 912 : *handle_pointer = 0;
926 : :
927 : 912 : return handle;
928 : : }
929 : :
930 : : /* Idles, child watchers and timeouts */
931 : : GLIB_AVAILABLE_IN_ALL
932 : : guint g_timeout_add_full (gint priority,
933 : : guint interval,
934 : : GSourceFunc function,
935 : : gpointer data,
936 : : GDestroyNotify notify);
937 : : GLIB_AVAILABLE_IN_ALL
938 : : guint g_timeout_add (guint interval,
939 : : GSourceFunc function,
940 : : gpointer data);
941 : : GLIB_AVAILABLE_IN_2_74
942 : : guint g_timeout_add_once (guint interval,
943 : : GSourceOnceFunc function,
944 : : gpointer data);
945 : : GLIB_AVAILABLE_IN_ALL
946 : : guint g_timeout_add_seconds_full (gint priority,
947 : : guint interval,
948 : : GSourceFunc function,
949 : : gpointer data,
950 : : GDestroyNotify notify);
951 : : GLIB_AVAILABLE_IN_ALL
952 : : guint g_timeout_add_seconds (guint interval,
953 : : GSourceFunc function,
954 : : gpointer data);
955 : : GLIB_AVAILABLE_IN_2_78
956 : : guint g_timeout_add_seconds_once (guint interval,
957 : : GSourceOnceFunc function,
958 : : gpointer data);
959 : : GLIB_AVAILABLE_IN_ALL
960 : : guint g_child_watch_add_full (gint priority,
961 : : GPid pid,
962 : : GChildWatchFunc function,
963 : : gpointer data,
964 : : GDestroyNotify notify);
965 : : GLIB_AVAILABLE_IN_ALL
966 : : guint g_child_watch_add (GPid pid,
967 : : GChildWatchFunc function,
968 : : gpointer data);
969 : : GLIB_AVAILABLE_IN_ALL
970 : : guint g_idle_add (GSourceFunc function,
971 : : gpointer data);
972 : : GLIB_AVAILABLE_IN_ALL
973 : : guint g_idle_add_full (gint priority,
974 : : GSourceFunc function,
975 : : gpointer data,
976 : : GDestroyNotify notify);
977 : : GLIB_AVAILABLE_IN_2_74
978 : : guint g_idle_add_once (GSourceOnceFunc function,
979 : : gpointer data);
980 : : GLIB_AVAILABLE_IN_ALL
981 : : gboolean g_idle_remove_by_data (gpointer data);
982 : :
983 : : GLIB_AVAILABLE_IN_ALL
984 : : void g_main_context_invoke_full (GMainContext *context,
985 : : gint priority,
986 : : GSourceFunc function,
987 : : gpointer data,
988 : : GDestroyNotify notify);
989 : : GLIB_AVAILABLE_IN_ALL
990 : : void 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 : : */
1015 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_70
1016 : : static inline int g_steal_fd (int *fd_ptr);
1017 : :
1018 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_70
1019 : : static inline int
1020 : 2103 : g_steal_fd (int *fd_ptr)
1021 : : {
1022 : 2103 : int fd = *fd_ptr;
1023 : 2103 : *fd_ptr = -1;
1024 : 2103 : return fd;
1025 : : }
1026 : :
1027 : : /* Hook for GClosure / GSource integration. Don't touch */
1028 : : GLIB_VAR GSourceFuncs g_timeout_funcs;
1029 : : GLIB_VAR GSourceFuncs g_child_watch_funcs;
1030 : : GLIB_VAR GSourceFuncs g_idle_funcs;
1031 : : #ifdef G_OS_UNIX
1032 : : GLIB_VAR GSourceFuncs g_unix_signal_funcs;
1033 : : GLIB_VAR GSourceFuncs g_unix_fd_source_funcs;
1034 : : #endif
1035 : :
1036 : : G_END_DECLS
1037 : :
1038 : : #endif /* __G_MAIN_H__ */
|
