1 /* gmain.h - the GLib Main loop
2 * Copyright (C) 1998-2000 Red Hat, Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
21 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
22 #error "Only <glib.h> can be included directly."
25 #include <glib/gpoll.h>
26 #include <glib/gslist.h>
27 #include <glib/gthread.h>
31 typedef enum /*< flags >*/
33 G_IO_IN GLIB_SYSDEF_POLLIN,
34 G_IO_OUT GLIB_SYSDEF_POLLOUT,
35 G_IO_PRI GLIB_SYSDEF_POLLPRI,
36 G_IO_ERR GLIB_SYSDEF_POLLERR,
37 G_IO_HUP GLIB_SYSDEF_POLLHUP,
38 G_IO_NVAL GLIB_SYSDEF_POLLNVAL
45 * The `GMainContext` struct is an opaque data
46 * type representing a set of sources to be handled in a main loop.
48 typedef struct _GMainContext GMainContext;
53 * The `GMainLoop` struct is an opaque data type
54 * representing the main event loop of a GLib or GTK+ application.
56 typedef struct _GMainLoop GMainLoop;
61 * The `GSource` struct is an opaque data type
62 * representing an event source.
64 typedef struct _GSource GSource;
65 typedef struct _GSourcePrivate GSourcePrivate;
68 * GSourceCallbackFuncs:
69 * @ref: Called when a reference is added to the callback object
70 * @unref: Called when a reference to the callback object is dropped
71 * @get: Called to extract the callback function and data from the
74 * The `GSourceCallbackFuncs` struct contains
75 * functions for managing callback objects.
77 typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs;
81 * @prepare: Called before all the file descriptors are polled. If the
82 * source can determine that it is ready here (without waiting for the
83 * results of the poll() call) it should return %TRUE. It can also return
84 * a @timeout_ value which should be the maximum timeout (in milliseconds)
85 * which should be passed to the poll() call. The actual timeout used will
86 * be -1 if all sources returned -1, or it will be the minimum of all
87 * the @timeout_ values returned which were >= 0. Since 2.36 this may
88 * be %NULL, in which case the effect is as if the function always returns
89 * %FALSE with a timeout of -1. If @prepare returns a
90 * timeout and the source also has a 'ready time' set then the
91 * nearer of the two will be used.
92 * @check: Called after all the file descriptors are polled. The source
93 * should return %TRUE if it is ready to be dispatched. Note that some
94 * time may have passed since the previous prepare function was called,
95 * so the source should be checked again here. Since 2.36 this may
96 * be %NULL, in which case the effect is as if the function always returns
98 * @dispatch: Called to dispatch the event source, after it has returned
99 * %TRUE in either its @prepare or its @check function. The @dispatch
100 * function is passed in a callback function and data. The callback
101 * function may be %NULL if the source was never connected to a callback
102 * using g_source_set_callback(). The @dispatch function should call the
103 * callback function with @user_data and whatever additional parameters
104 * are needed for this type of event source. The return value of the
105 * @dispatch function should be #G_SOURCE_REMOVE if the source should be
106 * removed or #G_SOURCE_CONTINUE to keep it.
107 * @finalize: Called when the source is finalized. At this point, the source
108 * will have been destroyed, had its callback cleared, and have been removed
109 * from its #GMainContext, but it will still have its final reference count;
110 * so methods can be called on it from within this function.
112 * The `GSourceFuncs` struct contains a table of
113 * functions used to handle event sources in a generic manner.
115 * For idle sources, the prepare and check functions always return %TRUE
116 * to indicate that the source is always ready to be processed. The prepare
117 * function also returns a timeout value of 0 to ensure that the poll() call
118 * doesn't block (since that would be time wasted which could have been spent
119 * running the idle function).
121 * For timeout sources, the prepare and check functions both return %TRUE
122 * if the timeout interval has expired. The prepare function also returns
123 * a timeout value to ensure that the poll() call doesn't block too long
124 * and miss the next timeout.
126 * For file descriptor sources, the prepare function typically returns %FALSE,
127 * since it must wait until poll() has been called before it knows whether
128 * any events need to be processed. It sets the returned timeout to -1 to
129 * indicate that it doesn't mind how long the poll() call blocks. In the
130 * check function, it tests the results of the poll() call to see if the
131 * required condition has been met, and returns %TRUE if so.
133 typedef struct _GSourceFuncs GSourceFuncs;
138 * A type which is used to hold a process identification.
140 * On UNIX, processes are identified by a process id (an integer),
141 * while Windows uses process handles (which are pointers).
143 * GPid is used in GLib only for descendant processes spawned with
144 * the g_spawn functions.
146 /* defined in glibconfig.h */
151 * A format specifier that can be used in printf()-style format strings
152 * when printing a #GPid.
156 /* defined in glibconfig.h */
160 * @user_data: data passed to the function, set when the source was
161 * created with one of the above functions
163 * Specifies the type of function passed to g_timeout_add(),
164 * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
166 * Returns: %FALSE if the source should be removed. #G_SOURCE_CONTINUE and
167 * #G_SOURCE_REMOVE are more memorable names for the return value.
169 typedef gboolean (*GSourceFunc) (gpointer user_data);
173 * @pid: the process id of the child process
174 * @status: Status information about the child process, encoded
175 * in a platform-specific manner
176 * @user_data: user data passed to g_child_watch_add()
178 * Prototype of a #GChildWatchSource callback, called when a child
179 * process has exited. To interpret @status, see the documentation
180 * for g_spawn_check_exit_status().
182 typedef void (*GChildWatchFunc) (GPid pid,
188 gpointer callback_data;
189 GSourceCallbackFuncs *callback_funcs;
191 const GSourceFuncs *source_funcs;
194 GMainContext *context;
207 GSourcePrivate *priv;
210 struct _GSourceCallbackFuncs
212 void (*ref) (gpointer cb_data);
213 void (*unref) (gpointer cb_data);
214 void (*get) (gpointer cb_data,
221 * GSourceDummyMarshal:
223 * This is just a placeholder for #GClosureMarshal,
224 * which cannot be used here for dependency reasons.
226 typedef void (*GSourceDummyMarshal) (void);
230 gboolean (*prepare) (GSource *source,
232 gboolean (*check) (GSource *source);
233 gboolean (*dispatch) (GSource *source,
234 GSourceFunc callback,
236 void (*finalize) (GSource *source); /* Can be NULL */
239 /* For use by g_source_set_closure */
240 GSourceFunc closure_callback;
241 GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
244 /* Standard priorities */
249 * Use this for high priority event sources.
251 * It is not used within GLib or GTK+.
253 #define G_PRIORITY_HIGH -100
256 * G_PRIORITY_DEFAULT:
258 * Use this for default priority event sources.
260 * In GLib this priority is used when adding timeout functions
261 * with g_timeout_add(). In GDK this priority is used for events
264 #define G_PRIORITY_DEFAULT 0
267 * G_PRIORITY_HIGH_IDLE:
269 * Use this for high priority idle functions.
271 * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
272 * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
273 * done to ensure that any pending resizes are processed before any
274 * pending redraws, so that widgets are not redrawn twice unnecessarily.)
276 #define G_PRIORITY_HIGH_IDLE 100
279 * G_PRIORITY_DEFAULT_IDLE:
281 * Use this for default priority idle functions.
283 * In GLib this priority is used when adding idle functions with
286 #define G_PRIORITY_DEFAULT_IDLE 200
291 * Use this for very low priority background tasks.
293 * It is not used within GLib or GTK+.
295 #define G_PRIORITY_LOW 300
300 * Use this macro as the return value of a #GSourceFunc to remove
301 * the #GSource from the main loop.
305 #define G_SOURCE_REMOVE FALSE
310 * Use this macro as the return value of a #GSourceFunc to leave
311 * the #GSource in the main loop.
315 #define G_SOURCE_CONTINUE TRUE
319 GLIB_AVAILABLE_IN_ALL
320 GMainContext *g_main_context_new (void);
321 GLIB_AVAILABLE_IN_ALL
322 GMainContext *g_main_context_ref (GMainContext *context);
323 GLIB_AVAILABLE_IN_ALL
324 void g_main_context_unref (GMainContext *context);
325 GLIB_AVAILABLE_IN_ALL
326 GMainContext *g_main_context_default (void);
328 GLIB_AVAILABLE_IN_ALL
329 gboolean g_main_context_iteration (GMainContext *context,
331 GLIB_AVAILABLE_IN_ALL
332 gboolean g_main_context_pending (GMainContext *context);
334 /* For implementation of legacy interfaces
336 GLIB_AVAILABLE_IN_ALL
337 GSource *g_main_context_find_source_by_id (GMainContext *context,
339 GLIB_AVAILABLE_IN_ALL
340 GSource *g_main_context_find_source_by_user_data (GMainContext *context,
342 GLIB_AVAILABLE_IN_ALL
343 GSource *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
347 /* Low level functions for implementing custom main loops.
349 GLIB_AVAILABLE_IN_ALL
350 void g_main_context_wakeup (GMainContext *context);
351 GLIB_AVAILABLE_IN_ALL
352 gboolean g_main_context_acquire (GMainContext *context);
353 GLIB_AVAILABLE_IN_ALL
354 void g_main_context_release (GMainContext *context);
355 GLIB_AVAILABLE_IN_ALL
356 gboolean g_main_context_is_owner (GMainContext *context);
357 GLIB_AVAILABLE_IN_ALL
358 gboolean g_main_context_wait (GMainContext *context,
362 GLIB_AVAILABLE_IN_ALL
363 gboolean g_main_context_prepare (GMainContext *context,
365 GLIB_AVAILABLE_IN_ALL
366 gint g_main_context_query (GMainContext *context,
371 GLIB_AVAILABLE_IN_ALL
372 gboolean g_main_context_check (GMainContext *context,
376 GLIB_AVAILABLE_IN_ALL
377 void g_main_context_dispatch (GMainContext *context);
379 GLIB_AVAILABLE_IN_ALL
380 void g_main_context_set_poll_func (GMainContext *context,
382 GLIB_AVAILABLE_IN_ALL
383 GPollFunc g_main_context_get_poll_func (GMainContext *context);
385 /* Low level functions for use by source implementations
387 GLIB_AVAILABLE_IN_ALL
388 void g_main_context_add_poll (GMainContext *context,
391 GLIB_AVAILABLE_IN_ALL
392 void g_main_context_remove_poll (GMainContext *context,
395 GLIB_AVAILABLE_IN_ALL
396 gint g_main_depth (void);
397 GLIB_AVAILABLE_IN_ALL
398 GSource *g_main_current_source (void);
400 /* GMainContexts for other threads
402 GLIB_AVAILABLE_IN_ALL
403 void g_main_context_push_thread_default (GMainContext *context);
404 GLIB_AVAILABLE_IN_ALL
405 void g_main_context_pop_thread_default (GMainContext *context);
406 GLIB_AVAILABLE_IN_ALL
407 GMainContext *g_main_context_get_thread_default (void);
408 GLIB_AVAILABLE_IN_ALL
409 GMainContext *g_main_context_ref_thread_default (void);
413 GLIB_AVAILABLE_IN_ALL
414 GMainLoop *g_main_loop_new (GMainContext *context,
415 gboolean is_running);
416 GLIB_AVAILABLE_IN_ALL
417 void g_main_loop_run (GMainLoop *loop);
418 GLIB_AVAILABLE_IN_ALL
419 void g_main_loop_quit (GMainLoop *loop);
420 GLIB_AVAILABLE_IN_ALL
421 GMainLoop *g_main_loop_ref (GMainLoop *loop);
422 GLIB_AVAILABLE_IN_ALL
423 void g_main_loop_unref (GMainLoop *loop);
424 GLIB_AVAILABLE_IN_ALL
425 gboolean g_main_loop_is_running (GMainLoop *loop);
426 GLIB_AVAILABLE_IN_ALL
427 GMainContext *g_main_loop_get_context (GMainLoop *loop);
431 GLIB_AVAILABLE_IN_ALL
432 GSource *g_source_new (GSourceFuncs *source_funcs,
434 GLIB_AVAILABLE_IN_ALL
435 GSource *g_source_ref (GSource *source);
436 GLIB_AVAILABLE_IN_ALL
437 void g_source_unref (GSource *source);
439 GLIB_AVAILABLE_IN_ALL
440 guint g_source_attach (GSource *source,
441 GMainContext *context);
442 GLIB_AVAILABLE_IN_ALL
443 void g_source_destroy (GSource *source);
445 GLIB_AVAILABLE_IN_ALL
446 void g_source_set_priority (GSource *source,
448 GLIB_AVAILABLE_IN_ALL
449 gint g_source_get_priority (GSource *source);
450 GLIB_AVAILABLE_IN_ALL
451 void g_source_set_can_recurse (GSource *source,
452 gboolean can_recurse);
453 GLIB_AVAILABLE_IN_ALL
454 gboolean g_source_get_can_recurse (GSource *source);
455 GLIB_AVAILABLE_IN_ALL
456 guint g_source_get_id (GSource *source);
458 GLIB_AVAILABLE_IN_ALL
459 GMainContext *g_source_get_context (GSource *source);
461 GLIB_AVAILABLE_IN_ALL
462 void g_source_set_callback (GSource *source,
465 GDestroyNotify notify);
467 GLIB_AVAILABLE_IN_ALL
468 void g_source_set_funcs (GSource *source,
469 GSourceFuncs *funcs);
470 GLIB_AVAILABLE_IN_ALL
471 gboolean g_source_is_destroyed (GSource *source);
473 GLIB_AVAILABLE_IN_ALL
474 void g_source_set_name (GSource *source,
476 GLIB_AVAILABLE_IN_ALL
477 const char * g_source_get_name (GSource *source);
478 GLIB_AVAILABLE_IN_ALL
479 void g_source_set_name_by_id (guint tag,
482 GLIB_AVAILABLE_IN_2_36
483 void g_source_set_ready_time (GSource *source,
485 GLIB_AVAILABLE_IN_2_36
486 gint64 g_source_get_ready_time (GSource *source);
489 GLIB_AVAILABLE_IN_2_36
490 gpointer g_source_add_unix_fd (GSource *source,
492 GIOCondition events);
493 GLIB_AVAILABLE_IN_2_36
494 void g_source_modify_unix_fd (GSource *source,
496 GIOCondition new_events);
497 GLIB_AVAILABLE_IN_2_36
498 void g_source_remove_unix_fd (GSource *source,
500 GLIB_AVAILABLE_IN_2_36
501 GIOCondition g_source_query_unix_fd (GSource *source,
505 /* Used to implement g_source_connect_closure and internally*/
506 GLIB_AVAILABLE_IN_ALL
507 void g_source_set_callback_indirect (GSource *source,
508 gpointer callback_data,
509 GSourceCallbackFuncs *callback_funcs);
511 GLIB_AVAILABLE_IN_ALL
512 void g_source_add_poll (GSource *source,
514 GLIB_AVAILABLE_IN_ALL
515 void g_source_remove_poll (GSource *source,
518 GLIB_AVAILABLE_IN_ALL
519 void g_source_add_child_source (GSource *source,
520 GSource *child_source);
521 GLIB_AVAILABLE_IN_ALL
522 void g_source_remove_child_source (GSource *source,
523 GSource *child_source);
525 GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time)
526 void g_source_get_current_time (GSource *source,
529 GLIB_AVAILABLE_IN_ALL
530 gint64 g_source_get_time (GSource *source);
532 /* void g_source_connect_closure (GSource *source,
536 /* Specific source types
538 GLIB_AVAILABLE_IN_ALL
539 GSource *g_idle_source_new (void);
540 GLIB_AVAILABLE_IN_ALL
541 GSource *g_child_watch_source_new (GPid pid);
542 GLIB_AVAILABLE_IN_ALL
543 GSource *g_timeout_source_new (guint interval);
544 GLIB_AVAILABLE_IN_ALL
545 GSource *g_timeout_source_new_seconds (guint interval);
547 /* Miscellaneous functions
549 GLIB_AVAILABLE_IN_ALL
550 void g_get_current_time (GTimeVal *result);
551 GLIB_AVAILABLE_IN_ALL
552 gint64 g_get_monotonic_time (void);
553 GLIB_AVAILABLE_IN_ALL
554 gint64 g_get_real_time (void);
557 /* Source manipulation by ID */
558 GLIB_AVAILABLE_IN_ALL
559 gboolean g_source_remove (guint tag);
560 GLIB_AVAILABLE_IN_ALL
561 gboolean g_source_remove_by_user_data (gpointer user_data);
562 GLIB_AVAILABLE_IN_ALL
563 gboolean g_source_remove_by_funcs_user_data (GSourceFuncs *funcs,
566 /* Idles, child watchers and timeouts */
567 GLIB_AVAILABLE_IN_ALL
568 guint g_timeout_add_full (gint priority,
570 GSourceFunc function,
572 GDestroyNotify notify);
573 GLIB_AVAILABLE_IN_ALL
574 guint g_timeout_add (guint interval,
575 GSourceFunc function,
577 GLIB_AVAILABLE_IN_ALL
578 guint g_timeout_add_seconds_full (gint priority,
580 GSourceFunc function,
582 GDestroyNotify notify);
583 GLIB_AVAILABLE_IN_ALL
584 guint g_timeout_add_seconds (guint interval,
585 GSourceFunc function,
587 GLIB_AVAILABLE_IN_ALL
588 guint g_child_watch_add_full (gint priority,
590 GChildWatchFunc function,
592 GDestroyNotify notify);
593 GLIB_AVAILABLE_IN_ALL
594 guint g_child_watch_add (GPid pid,
595 GChildWatchFunc function,
597 GLIB_AVAILABLE_IN_ALL
598 guint g_idle_add (GSourceFunc function,
600 GLIB_AVAILABLE_IN_ALL
601 guint g_idle_add_full (gint priority,
602 GSourceFunc function,
604 GDestroyNotify notify);
605 GLIB_AVAILABLE_IN_ALL
606 gboolean g_idle_remove_by_data (gpointer data);
608 GLIB_AVAILABLE_IN_ALL
609 void g_main_context_invoke_full (GMainContext *context,
611 GSourceFunc function,
613 GDestroyNotify notify);
614 GLIB_AVAILABLE_IN_ALL
615 void g_main_context_invoke (GMainContext *context,
616 GSourceFunc function,
619 /* Hook for GClosure / GSource integration. Don't touch */
620 GLIB_VAR GSourceFuncs g_timeout_funcs;
621 GLIB_VAR GSourceFuncs g_child_watch_funcs;
622 GLIB_VAR GSourceFuncs g_idle_funcs;
624 GLIB_VAR GSourceFuncs g_unix_signal_funcs;
625 GLIB_VAR GSourceFuncs g_unix_fd_source_funcs;
630 #endif /* __G_MAIN_H__ */