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 : : G_BEGIN_DECLS
32 : :
33 : : typedef enum /*< flags >*/
34 : : {
35 : : G_IO_IN GLIB_SYSDEF_POLLIN,
36 : : G_IO_OUT GLIB_SYSDEF_POLLOUT,
37 : : G_IO_PRI GLIB_SYSDEF_POLLPRI,
38 : : G_IO_ERR GLIB_SYSDEF_POLLERR,
39 : : G_IO_HUP GLIB_SYSDEF_POLLHUP,
40 : : G_IO_NVAL GLIB_SYSDEF_POLLNVAL
41 : : } GIOCondition;
42 : :
43 : : /**
44 : : * GMainContextFlags:
45 : : * @G_MAIN_CONTEXT_FLAGS_NONE: Default behaviour.
46 : : * @G_MAIN_CONTEXT_FLAGS_OWNERLESS_POLLING: Assume that polling for events will
47 : : * free the thread to process other jobs. That's useful if you're using
48 : : * `g_main_context_{prepare,query,check,dispatch}` to integrate GMainContext in
49 : : * other event loops.
50 : : *
51 : : * Flags to pass to [ctor@GLib.MainContext.new_with_flags] which affect the
52 : : * behaviour of a [struct@GLib.MainContext].
53 : : *
54 : : * Since: 2.72
55 : : */
56 : : GLIB_AVAILABLE_TYPE_IN_2_72
57 : : typedef enum /*< flags >*/
58 : : {
59 : : G_MAIN_CONTEXT_FLAGS_NONE = 0,
60 : : G_MAIN_CONTEXT_FLAGS_OWNERLESS_POLLING = 1
61 : : } GMainContextFlags;
62 : :
63 : :
64 : : /**
65 : : * GMainContext:
66 : : *
67 : : * The `GMainContext` struct is an opaque data
68 : : * type representing a set of sources to be handled in a main loop.
69 : : */
70 : : typedef struct _GMainContext GMainContext;
71 : :
72 : : /**
73 : : * GMainLoop:
74 : : *
75 : : * The `GMainLoop` struct is an opaque data type
76 : : * representing the main event loop of a GLib or GTK application.
77 : : */
78 : : typedef struct _GMainLoop GMainLoop;
79 : :
80 : : /**
81 : : * GSource:
82 : : *
83 : : * The `GSource` struct is an opaque data type
84 : : * representing an event source.
85 : : */
86 : : typedef struct _GSource GSource;
87 : : typedef struct _GSourcePrivate GSourcePrivate;
88 : :
89 : : /**
90 : : * GSourceCallbackFuncs:
91 : : * @ref: Called when a reference is added to the callback object
92 : : * @unref: Called when a reference to the callback object is dropped
93 : : * @get: Called to extract the callback function and data from the
94 : : * callback object.
95 : : *
96 : : * The `GSourceCallbackFuncs` struct contains
97 : : * functions for managing callback objects.
98 : : */
99 : : typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs;
100 : :
101 : : /**
102 : : * GSourceFuncs:
103 : : * @prepare: (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 : : */
158 : : typedef 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 : : */
200 : : typedef 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 : : */
214 : : typedef 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 : : */
250 : : typedef 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 : : */
264 : : GLIB_AVAILABLE_TYPE_IN_2_64
265 : : typedef void (*GSourceDisposeFunc) (GSource *source);
266 : :
267 : : struct _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 : :
292 : : struct _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 : : */
308 : : typedef 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 : : */
334 : : typedef 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 : : */
355 : : typedef 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 : : */
380 : : typedef 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 : : */
397 : : typedef void (*GSourceFuncsFinalizeFunc) (GSource *source);
398 : :
399 : : struct _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 : :
487 : : GLIB_AVAILABLE_IN_ALL
488 : : GMainContext *g_main_context_new (void);
489 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
490 : : GLIB_AVAILABLE_IN_2_72
491 : : GMainContext *g_main_context_new_with_flags (GMainContextFlags flags);
492 : : G_GNUC_END_IGNORE_DEPRECATIONS
493 : : GLIB_AVAILABLE_IN_ALL
494 : : GMainContext *g_main_context_ref (GMainContext *context);
495 : : GLIB_AVAILABLE_IN_ALL
496 : : void g_main_context_unref (GMainContext *context);
497 : : GLIB_AVAILABLE_IN_ALL
498 : : GMainContext *g_main_context_default (void);
499 : :
500 : : GLIB_AVAILABLE_IN_ALL
501 : : gboolean g_main_context_iteration (GMainContext *context,
502 : : gboolean may_block);
503 : : GLIB_AVAILABLE_IN_ALL
504 : : gboolean g_main_context_pending (GMainContext *context);
505 : :
506 : : /* For implementation of legacy interfaces
507 : : */
508 : : GLIB_AVAILABLE_IN_ALL
509 : : GSource *g_main_context_find_source_by_id (GMainContext *context,
510 : : guint source_id);
511 : : GLIB_AVAILABLE_IN_ALL
512 : : GSource *g_main_context_find_source_by_user_data (GMainContext *context,
513 : : gpointer user_data);
514 : : GLIB_AVAILABLE_IN_ALL
515 : : GSource *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 : : */
521 : : GLIB_AVAILABLE_IN_ALL
522 : : void g_main_context_wakeup (GMainContext *context);
523 : : GLIB_AVAILABLE_IN_ALL
524 : : gboolean g_main_context_acquire (GMainContext *context);
525 : : GLIB_AVAILABLE_IN_ALL
526 : : void g_main_context_release (GMainContext *context);
527 : : GLIB_AVAILABLE_IN_ALL
528 : : gboolean g_main_context_is_owner (GMainContext *context);
529 : : GLIB_DEPRECATED_IN_2_58_FOR(g_main_context_is_owner)
530 : : gboolean g_main_context_wait (GMainContext *context,
531 : : GCond *cond,
532 : : GMutex *mutex);
533 : :
534 : : GLIB_AVAILABLE_IN_ALL
535 : : gboolean g_main_context_prepare (GMainContext *context,
536 : : gint *priority);
537 : : GLIB_AVAILABLE_IN_ALL
538 : : gint g_main_context_query (GMainContext *context,
539 : : gint max_priority,
540 : : gint *timeout_,
541 : : GPollFD *fds,
542 : : gint n_fds);
543 : : GLIB_AVAILABLE_IN_ALL
544 : : gboolean g_main_context_check (GMainContext *context,
545 : : gint max_priority,
546 : : GPollFD *fds,
547 : : gint n_fds);
548 : : GLIB_AVAILABLE_IN_ALL
549 : : void g_main_context_dispatch (GMainContext *context);
550 : :
551 : : GLIB_AVAILABLE_IN_ALL
552 : : void g_main_context_set_poll_func (GMainContext *context,
553 : : GPollFunc func);
554 : : GLIB_AVAILABLE_IN_ALL
555 : : GPollFunc g_main_context_get_poll_func (GMainContext *context);
556 : :
557 : : /* Low level functions for use by source implementations
558 : : */
559 : : GLIB_AVAILABLE_IN_ALL
560 : : void g_main_context_add_poll (GMainContext *context,
561 : : GPollFD *fd,
562 : : gint priority);
563 : : GLIB_AVAILABLE_IN_ALL
564 : : void g_main_context_remove_poll (GMainContext *context,
565 : : GPollFD *fd);
566 : :
567 : : GLIB_AVAILABLE_IN_ALL
568 : : gint g_main_depth (void);
569 : : GLIB_AVAILABLE_IN_ALL
570 : : GSource *g_main_current_source (void);
571 : :
572 : : /* GMainContexts for other threads
573 : : */
574 : : GLIB_AVAILABLE_IN_ALL
575 : : void g_main_context_push_thread_default (GMainContext *context);
576 : : GLIB_AVAILABLE_IN_ALL
577 : : void g_main_context_pop_thread_default (GMainContext *context);
578 : : GLIB_AVAILABLE_IN_ALL
579 : : GMainContext *g_main_context_get_thread_default (void);
580 : : GLIB_AVAILABLE_IN_ALL
581 : : GMainContext *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 : : */
590 : : typedef 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 : : */
637 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
638 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
639 : : static inline GMainContextPusher *g_main_context_pusher_new (GMainContext *main_context);
640 : :
641 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
642 : : static inline GMainContextPusher *
643 : 1 : g_main_context_pusher_new (GMainContext *main_context)
644 : : {
645 : 1 : g_main_context_push_thread_default (main_context);
646 : 1 : return (GMainContextPusher *) main_context;
647 : : }
648 : : G_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 : : */
662 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
663 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
664 : : static inline void g_main_context_pusher_free (GMainContextPusher *pusher);
665 : :
666 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_64
667 : : static inline void
668 : 1 : g_main_context_pusher_free (GMainContextPusher *pusher)
669 : : {
670 : 1 : g_main_context_pop_thread_default ((GMainContext *) pusher);
671 : 1 : }
672 : : G_GNUC_END_IGNORE_DEPRECATIONS
673 : :
674 : : /* GMainLoop: */
675 : :
676 : : GLIB_AVAILABLE_IN_ALL
677 : : GMainLoop *g_main_loop_new (GMainContext *context,
678 : : gboolean is_running);
679 : : GLIB_AVAILABLE_IN_ALL
680 : : void g_main_loop_run (GMainLoop *loop);
681 : : GLIB_AVAILABLE_IN_ALL
682 : : void g_main_loop_quit (GMainLoop *loop);
683 : : GLIB_AVAILABLE_IN_ALL
684 : : GMainLoop *g_main_loop_ref (GMainLoop *loop);
685 : : GLIB_AVAILABLE_IN_ALL
686 : : void g_main_loop_unref (GMainLoop *loop);
687 : : GLIB_AVAILABLE_IN_ALL
688 : : gboolean g_main_loop_is_running (GMainLoop *loop);
689 : : GLIB_AVAILABLE_IN_ALL
690 : : GMainContext *g_main_loop_get_context (GMainLoop *loop);
691 : :
692 : : /* GSource: */
693 : :
694 : : GLIB_AVAILABLE_IN_ALL
695 : : GSource *g_source_new (GSourceFuncs *source_funcs,
696 : : guint struct_size);
697 : :
698 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
699 : : GLIB_AVAILABLE_IN_2_64
700 : : void g_source_set_dispose_function (GSource *source,
701 : : GSourceDisposeFunc dispose);
702 : : G_GNUC_END_IGNORE_DEPRECATIONS
703 : :
704 : : GLIB_AVAILABLE_IN_ALL
705 : : GSource *g_source_ref (GSource *source);
706 : : GLIB_AVAILABLE_IN_ALL
707 : : void g_source_unref (GSource *source);
708 : :
709 : : GLIB_AVAILABLE_IN_ALL
710 : : guint g_source_attach (GSource *source,
711 : : GMainContext *context);
712 : : GLIB_AVAILABLE_IN_ALL
713 : : void g_source_destroy (GSource *source);
714 : :
715 : : GLIB_AVAILABLE_IN_ALL
716 : : void g_source_set_priority (GSource *source,
717 : : gint priority);
718 : : GLIB_AVAILABLE_IN_ALL
719 : : gint g_source_get_priority (GSource *source);
720 : : GLIB_AVAILABLE_IN_ALL
721 : : void g_source_set_can_recurse (GSource *source,
722 : : gboolean can_recurse);
723 : : GLIB_AVAILABLE_IN_ALL
724 : : gboolean g_source_get_can_recurse (GSource *source);
725 : : GLIB_AVAILABLE_IN_ALL
726 : : guint g_source_get_id (GSource *source);
727 : :
728 : : GLIB_AVAILABLE_IN_ALL
729 : : GMainContext *g_source_get_context (GSource *source);
730 : : GLIB_AVAILABLE_IN_2_86
731 : : GMainContext *g_source_dup_context (GSource *source);
732 : :
733 : : GLIB_AVAILABLE_IN_ALL
734 : : void g_source_set_callback (GSource *source,
735 : : GSourceFunc func,
736 : : gpointer data,
737 : : GDestroyNotify notify);
738 : :
739 : : GLIB_AVAILABLE_IN_ALL
740 : : void g_source_set_funcs (GSource *source,
741 : : GSourceFuncs *funcs);
742 : : GLIB_AVAILABLE_IN_ALL
743 : : gboolean g_source_is_destroyed (GSource *source);
744 : :
745 : : GLIB_AVAILABLE_IN_ALL
746 : : void g_source_set_name (GSource *source,
747 : : const char *name);
748 : : GLIB_AVAILABLE_IN_2_70
749 : : void g_source_set_static_name (GSource *source,
750 : : const char *name);
751 : : GLIB_AVAILABLE_IN_ALL
752 : : const char * g_source_get_name (GSource *source);
753 : : GLIB_AVAILABLE_IN_ALL
754 : : void g_source_set_name_by_id (guint tag,
755 : : const char *name);
756 : :
757 : : GLIB_AVAILABLE_IN_2_36
758 : : void g_source_set_ready_time (GSource *source,
759 : : gint64 ready_time);
760 : : GLIB_AVAILABLE_IN_2_36
761 : : gint64 g_source_get_ready_time (GSource *source);
762 : :
763 : : #ifdef G_OS_UNIX
764 : : GLIB_AVAILABLE_IN_2_36
765 : : gpointer g_source_add_unix_fd (GSource *source,
766 : : gint fd,
767 : : GIOCondition events);
768 : : GLIB_AVAILABLE_IN_2_36
769 : : void g_source_modify_unix_fd (GSource *source,
770 : : gpointer tag,
771 : : GIOCondition new_events);
772 : : GLIB_AVAILABLE_IN_2_36
773 : : void g_source_remove_unix_fd (GSource *source,
774 : : gpointer tag);
775 : : GLIB_AVAILABLE_IN_2_36
776 : : GIOCondition g_source_query_unix_fd (GSource *source,
777 : : gpointer tag);
778 : : #endif
779 : :
780 : : /* Used to implement g_source_connect_closure and internally*/
781 : : GLIB_AVAILABLE_IN_ALL
782 : : void g_source_set_callback_indirect (GSource *source,
783 : : gpointer callback_data,
784 : : GSourceCallbackFuncs *callback_funcs);
785 : :
786 : : GLIB_AVAILABLE_IN_ALL
787 : : void g_source_add_poll (GSource *source,
788 : : GPollFD *fd);
789 : : GLIB_AVAILABLE_IN_ALL
790 : : void g_source_remove_poll (GSource *source,
791 : : GPollFD *fd);
792 : :
793 : : GLIB_AVAILABLE_IN_ALL
794 : : void g_source_add_child_source (GSource *source,
795 : : GSource *child_source);
796 : : GLIB_AVAILABLE_IN_ALL
797 : : void g_source_remove_child_source (GSource *source,
798 : : GSource *child_source);
799 : :
800 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
801 : : GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time)
802 : : void g_source_get_current_time (GSource *source,
803 : : GTimeVal *timeval);
804 : : G_GNUC_END_IGNORE_DEPRECATIONS
805 : :
806 : : GLIB_AVAILABLE_IN_ALL
807 : : gint64 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 : : */
815 : : GLIB_AVAILABLE_IN_ALL
816 : : GSource *g_idle_source_new (void);
817 : : GLIB_AVAILABLE_IN_ALL
818 : : GSource *g_child_watch_source_new (GPid pid);
819 : : GLIB_AVAILABLE_IN_ALL
820 : : GSource *g_timeout_source_new (guint interval);
821 : : GLIB_AVAILABLE_IN_ALL
822 : : GSource *g_timeout_source_new_seconds (guint interval);
823 : :
824 : : /* Miscellaneous functions
825 : : */
826 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
827 : : GLIB_DEPRECATED_IN_2_62_FOR(g_get_real_time)
828 : : void g_get_current_time (GTimeVal *result);
829 : : G_GNUC_END_IGNORE_DEPRECATIONS
830 : :
831 : : GLIB_AVAILABLE_IN_ALL
832 : : gint64 g_get_monotonic_time (void);
833 : : GLIB_AVAILABLE_IN_ALL
834 : : gint64 g_get_real_time (void);
835 : :
836 : :
837 : : /* Source manipulation by ID */
838 : : GLIB_AVAILABLE_IN_ALL
839 : : gboolean g_source_remove (guint tag);
840 : : GLIB_AVAILABLE_IN_ALL
841 : : gboolean g_source_remove_by_user_data (gpointer user_data);
842 : : GLIB_AVAILABLE_IN_ALL
843 : : gboolean 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 : : */
857 : : typedef void (* GClearHandleFunc) (guint handle_id);
858 : :
859 : : GLIB_AVAILABLE_IN_2_56
860 : : void 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 : : */
911 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
912 : : static inline unsigned int g_steal_handle_id (unsigned int *handle_pointer);
913 : :
914 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
915 : : static inline unsigned int
916 : 894 : g_steal_handle_id (unsigned int *handle_pointer)
917 : : {
918 : : unsigned int handle;
919 : :
920 : 894 : handle = *handle_pointer;
921 : 894 : *handle_pointer = 0;
922 : :
923 : 894 : return handle;
924 : : }
925 : :
926 : : /* Idles, child watchers and timeouts */
927 : : GLIB_AVAILABLE_IN_ALL
928 : : guint g_timeout_add_full (gint priority,
929 : : guint interval,
930 : : GSourceFunc function,
931 : : gpointer data,
932 : : GDestroyNotify notify);
933 : : GLIB_AVAILABLE_IN_ALL
934 : : guint g_timeout_add (guint interval,
935 : : GSourceFunc function,
936 : : gpointer data);
937 : : GLIB_AVAILABLE_IN_2_74
938 : : guint g_timeout_add_once (guint interval,
939 : : GSourceOnceFunc function,
940 : : gpointer data);
941 : : GLIB_AVAILABLE_IN_ALL
942 : : guint g_timeout_add_seconds_full (gint priority,
943 : : guint interval,
944 : : GSourceFunc function,
945 : : gpointer data,
946 : : GDestroyNotify notify);
947 : : GLIB_AVAILABLE_IN_ALL
948 : : guint g_timeout_add_seconds (guint interval,
949 : : GSourceFunc function,
950 : : gpointer data);
951 : : GLIB_AVAILABLE_IN_2_78
952 : : guint g_timeout_add_seconds_once (guint interval,
953 : : GSourceOnceFunc function,
954 : : gpointer data);
955 : : GLIB_AVAILABLE_IN_ALL
956 : : guint g_child_watch_add_full (gint priority,
957 : : GPid pid,
958 : : GChildWatchFunc function,
959 : : gpointer data,
960 : : GDestroyNotify notify);
961 : : GLIB_AVAILABLE_IN_ALL
962 : : guint g_child_watch_add (GPid pid,
963 : : GChildWatchFunc function,
964 : : gpointer data);
965 : : GLIB_AVAILABLE_IN_ALL
966 : : guint g_idle_add (GSourceFunc function,
967 : : gpointer data);
968 : : GLIB_AVAILABLE_IN_ALL
969 : : guint g_idle_add_full (gint priority,
970 : : GSourceFunc function,
971 : : gpointer data,
972 : : GDestroyNotify notify);
973 : : GLIB_AVAILABLE_IN_2_74
974 : : guint g_idle_add_once (GSourceOnceFunc function,
975 : : gpointer data);
976 : : GLIB_AVAILABLE_IN_ALL
977 : : gboolean g_idle_remove_by_data (gpointer data);
978 : :
979 : : GLIB_AVAILABLE_IN_ALL
980 : : void g_main_context_invoke_full (GMainContext *context,
981 : : gint priority,
982 : : GSourceFunc function,
983 : : gpointer data,
984 : : GDestroyNotify notify);
985 : : GLIB_AVAILABLE_IN_ALL
986 : : void 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 : : */
1011 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_70
1012 : : static inline int g_steal_fd (int *fd_ptr);
1013 : :
1014 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_70
1015 : : static inline int
1016 : 1928 : g_steal_fd (int *fd_ptr)
1017 : : {
1018 : 1928 : int fd = *fd_ptr;
1019 : 1928 : *fd_ptr = -1;
1020 : 1928 : return fd;
1021 : : }
1022 : :
1023 : : /* Hook for GClosure / GSource integration. Don't touch */
1024 : : GLIB_VAR GSourceFuncs g_timeout_funcs;
1025 : : GLIB_VAR GSourceFuncs g_child_watch_funcs;
1026 : : GLIB_VAR GSourceFuncs g_idle_funcs;
1027 : : #ifdef G_OS_UNIX
1028 : : GLIB_VAR GSourceFuncs g_unix_signal_funcs;
1029 : : GLIB_VAR GSourceFuncs g_unix_fd_source_funcs;
1030 : : #endif
1031 : :
1032 : : G_END_DECLS
1033 : :
1034 : : #endif /* __G_MAIN_H__ */
|
