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