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, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
20 #if defined(G_DISABLE_SINGLE_INCLUDES) && !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
21 #error "Only <glib.h> can be included directly."
27 #include <glib/gpoll.h>
28 #include <glib/gslist.h>
29 #include <glib/gthread.h>
36 * The <structname>GMainContext</structname> struct is an opaque data
37 * type representing a set of sources to be handled in a main loop.
39 typedef struct _GMainContext GMainContext;
44 * The <structname>GMainLoop</structname> struct is an opaque data type
45 * representing the main event loop of a GLib or GTK+ application.
47 typedef struct _GMainLoop GMainLoop;
52 * The <structname>GSource</structname> struct is an opaque data type
53 * representing an event source.
55 typedef struct _GSource GSource;
58 * GSourceCallbackFuncs:
59 * @ref: Called when a reference is added to the callback object
60 * @unref: Called when a reference to the callback object is dropped
61 * @get: Called to extract the callback function and data from the
64 * The <structname>GSourceCallbackFuncs</structname> struct contains
65 * functions for managing callback objects.
67 typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs;
71 * @prepare: Called before all the file descriptors are polled. If the
72 * source can determine that it is ready here (without waiting for the
73 * results of the poll() call) it should return %TRUE. It can also return
74 * a @timeout_ value which should be the maximum timeout (in milliseconds)
75 * which should be passed to the poll() call. The actual timeout used will
76 * be -1 if all sources returned -1, or it will be the minimum of all the
77 * @timeout_ values returned which were >= 0.
78 * @check: Called after all the file descriptors are polled. The source
79 * should return %TRUE if it is ready to be dispatched. Note that some
80 * time may have passed since the previous prepare function was called,
81 * so the source should be checked again here.
82 * @dispatch: Called to dispatch the event source, after it has returned
83 * %TRUE in either its @prepare or its @check function. The @dispatch
84 * function is passed in a callback function and data. The callback
85 * function may be %NULL if the source was never connected to a callback
86 * using g_source_set_callback(). The @dispatch function should call the
87 * callback function with @user_data and whatever additional parameters
88 * are needed for this type of event source.
89 * @finalize: Called when the source is finalized.
93 * The <structname>GSourceFuncs</structname> struct contains a table of
94 * functions used to handle event sources in a generic manner.
96 * For idle sources, the prepare and check functions always return %TRUE
97 * to indicate that the source is always ready to be processed. The prepare
98 * function also returns a timeout value of 0 to ensure that the poll() call
99 * doesn't block (since that would be time wasted which could have been spent
100 * running the idle function).
102 * For timeout sources, the prepare and check functions both return %TRUE
103 * if the timeout interval has expired. The prepare function also returns
104 * a timeout value to ensure that the poll() call doesn't block too long
105 * and miss the next timeout.
107 * For file descriptor sources, the prepare function typically returns %FALSE,
108 * since it must wait until poll() has been called before it knows whether
109 * any events need to be processed. It sets the returned timeout to -1 to
110 * indicate that it doesn't mind how long the poll() call blocks. In the
111 * check function, it tests the results of the poll() call to see if the
112 * required condition has been met, and returns %TRUE if so.
114 typedef struct _GSourceFuncs GSourceFuncs;
119 * A type which is used to hold a process identification.
121 * On UNIX, processes are identified by a process id (an integer),
122 * while Windows uses process handles (which are pointers).
125 typedef gboolean (*GSourceFunc) (gpointer data);
129 * @pid: the process id of the child process
130 * @status: Status information about the child process,
131 * see waitpid(2) for more information about this field
132 * @data: user data passed to g_child_watch_add()
134 * The type of functions to be called when a child exists.
136 typedef void (*GChildWatchFunc) (GPid pid,
142 gpointer callback_data;
143 GSourceCallbackFuncs *callback_funcs;
145 GSourceFuncs *source_funcs;
148 GMainContext *context;
163 struct _GSourceCallbackFuncs
165 void (*ref) (gpointer cb_data);
166 void (*unref) (gpointer cb_data);
167 void (*get) (gpointer cb_data,
173 typedef void (*GSourceDummyMarshal) (void);
177 gboolean (*prepare) (GSource *source,
179 gboolean (*check) (GSource *source);
180 gboolean (*dispatch) (GSource *source,
181 GSourceFunc callback,
183 void (*finalize) (GSource *source); /* Can be NULL */
185 /* For use by g_source_set_closure */
186 GSourceFunc closure_callback;
187 GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
190 /* Standard priorities */
195 * Use this for high priority event sources.
197 * It is not used within GLib or GTK+.
199 #define G_PRIORITY_HIGH -100
202 * G_PRIORITY_DEFAULT:
204 * Use this for default priority event sources.
206 * In GLib this priority is used when adding timeout functions
207 * with g_timeout_add(). In GDK this priority is used for events
210 #define G_PRIORITY_DEFAULT 0
213 * G_PRIORITY_HIGH_IDLE:
215 * Use this for high priority idle functions.
217 * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
218 * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
219 * done to ensure that any pending resizes are processed before any
220 * pending redraws, so that widgets are not redrawn twice unnecessarily.)
222 #define G_PRIORITY_HIGH_IDLE 100
225 * G_PRIORITY_DEFAULT_IDLE:
227 * Use this for default priority idle functions.
229 * In GLib this priority is used when adding idle functions with
232 #define G_PRIORITY_DEFAULT_IDLE 200
237 * Use this for very low priority background tasks.
239 * It is not used within GLib or GTK+.
241 #define G_PRIORITY_LOW 300
245 GMainContext *g_main_context_new (void);
246 GMainContext *g_main_context_ref (GMainContext *context);
247 void g_main_context_unref (GMainContext *context);
248 GMainContext *g_main_context_default (void);
250 gboolean g_main_context_iteration (GMainContext *context,
252 gboolean g_main_context_pending (GMainContext *context);
254 /* For implementation of legacy interfaces
256 GSource *g_main_context_find_source_by_id (GMainContext *context,
258 GSource *g_main_context_find_source_by_user_data (GMainContext *context,
260 GSource *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
264 /* Low level functions for implementing custom main loops.
266 void g_main_context_wakeup (GMainContext *context);
267 gboolean g_main_context_acquire (GMainContext *context);
268 void g_main_context_release (GMainContext *context);
269 gboolean g_main_context_is_owner (GMainContext *context);
270 gboolean g_main_context_wait (GMainContext *context,
274 gboolean g_main_context_prepare (GMainContext *context,
276 gint g_main_context_query (GMainContext *context,
281 gint g_main_context_check (GMainContext *context,
285 void g_main_context_dispatch (GMainContext *context);
287 void g_main_context_set_poll_func (GMainContext *context,
289 GPollFunc g_main_context_get_poll_func (GMainContext *context);
291 /* Low level functions for use by source implementations
293 void g_main_context_add_poll (GMainContext *context,
296 void g_main_context_remove_poll (GMainContext *context,
299 gint g_main_depth (void);
300 GSource *g_main_current_source (void);
302 /* GMainContexts for other threads
304 void g_main_context_push_thread_default (GMainContext *context);
305 void g_main_context_pop_thread_default (GMainContext *context);
306 GMainContext *g_main_context_get_thread_default (void);
310 GMainLoop *g_main_loop_new (GMainContext *context,
311 gboolean is_running);
312 void g_main_loop_run (GMainLoop *loop);
313 void g_main_loop_quit (GMainLoop *loop);
314 GMainLoop *g_main_loop_ref (GMainLoop *loop);
315 void g_main_loop_unref (GMainLoop *loop);
316 gboolean g_main_loop_is_running (GMainLoop *loop);
317 GMainContext *g_main_loop_get_context (GMainLoop *loop);
321 GSource *g_source_new (GSourceFuncs *source_funcs,
323 GSource *g_source_ref (GSource *source);
324 void g_source_unref (GSource *source);
326 guint g_source_attach (GSource *source,
327 GMainContext *context);
328 void g_source_destroy (GSource *source);
330 void g_source_set_priority (GSource *source,
332 gint g_source_get_priority (GSource *source);
333 void g_source_set_can_recurse (GSource *source,
334 gboolean can_recurse);
335 gboolean g_source_get_can_recurse (GSource *source);
336 guint g_source_get_id (GSource *source);
338 GMainContext *g_source_get_context (GSource *source);
340 void g_source_set_callback (GSource *source,
343 GDestroyNotify notify);
345 void g_source_set_funcs (GSource *source,
346 GSourceFuncs *funcs);
347 gboolean g_source_is_destroyed (GSource *source);
349 void g_source_set_name (GSource *source,
351 G_CONST_RETURN char* g_source_get_name (GSource *source);
352 void g_source_set_name_by_id (guint tag,
356 /* Used to implement g_source_connect_closure and internally*/
357 void g_source_set_callback_indirect (GSource *source,
358 gpointer callback_data,
359 GSourceCallbackFuncs *callback_funcs);
361 void g_source_add_poll (GSource *source,
363 void g_source_remove_poll (GSource *source,
366 #ifndef G_DISABLE_DEPRECATED
367 void g_source_get_current_time (GSource *source,
370 gint64 g_source_get_time (GSource *source);
372 /* void g_source_connect_closure (GSource *source,
376 /* Specific source types
378 GSource *g_idle_source_new (void);
379 GSource *g_child_watch_source_new (GPid pid);
380 GSource *g_timeout_source_new (guint interval);
381 GSource *g_timeout_source_new_seconds (guint interval);
383 /* Miscellaneous functions
385 void g_get_current_time (GTimeVal *result);
386 gint64 g_get_monotonic_time (void);
387 gint64 g_get_real_time (void);
389 /* ============== Compat main loop stuff ================== */
391 #ifndef G_DISABLE_DEPRECATED
395 * @is_running: set to %TRUE to indicate that the loop is running. This
396 * is not very important since calling g_main_run() will set this
399 * Creates a new #GMainLoop for th default main context.
401 * Returns: a new #GMainLoop
403 * Deprecated: 2.2: Use g_main_loop_new() instead
405 #define g_main_new(is_running) g_main_loop_new (NULL, is_running)
409 * @loop: a #GMainLoop
411 * Runs a main loop until it stops running.
413 * Deprecated: 2.2: Use g_main_loop_run() instead
415 #define g_main_run(loop) g_main_loop_run(loop)
419 * @loop: a #GMainLoop
421 * Stops the #GMainLoop.
422 * If g_main_run() was called to run the #GMainLoop, it will now return.
424 * Deprecated: 2.2: Use g_main_loop_quit() instead
426 #define g_main_quit(loop) g_main_loop_quit(loop)
430 * @loop: a #GMainLoop
432 * Frees the memory allocated for the #GMainLoop.
434 * Deprecated: 2.2: Use g_main_loop_unref() instead
436 #define g_main_destroy(loop) g_main_loop_unref(loop)
440 * @loop: a #GMainLoop
442 * Checks if the main loop is running.
444 * Returns: %TRUE if the main loop is running
446 * Deprecated: 2.2: Use g_main_loop_is_running() instead
448 #define g_main_is_running(loop) g_main_loop_is_running(loop)
452 * @may_block: set to %TRUE if it should block (i.e. wait) until an event
453 * source becomes ready. It will return after an event source has been
454 * processed. If set to %FALSE it will return immediately if no event
455 * source is ready to be processed.
457 * Runs a single iteration for the default #GMainContext.
459 * Returns: %TRUE if more events are pending.
461 * Deprecated: 2.2: Use g_main_context_iteration() instead.
463 #define g_main_iteration(may_block) g_main_context_iteration (NULL, may_block)
468 * Checks if any events are pending for the default #GMainContext
469 * (i.e. ready to be processed).
471 * Returns: %TRUE if any events are pending.
473 * Deprected: 2.2: Use g_main_context_pending() instead.
475 #define g_main_pending() g_main_context_pending (NULL)
478 * g_main_set_poll_func:
479 * @func: the function to call to poll all file descriptors
481 * Sets the function to use for the handle polling of file descriptors
482 * for the default main context.
484 * Deprecated: 2.2: Use g_main_context_set_poll_func() again
486 #define g_main_set_poll_func(func) g_main_context_set_poll_func (NULL, func)
488 #endif /* G_DISABLE_DEPRECATED */
490 /* Source manipulation by ID */
491 gboolean g_source_remove (guint tag);
492 gboolean g_source_remove_by_user_data (gpointer user_data);
493 gboolean g_source_remove_by_funcs_user_data (GSourceFuncs *funcs,
496 /* Idles, child watchers and timeouts */
497 guint g_timeout_add_full (gint priority,
499 GSourceFunc function,
501 GDestroyNotify notify);
502 guint g_timeout_add (guint interval,
503 GSourceFunc function,
505 guint g_timeout_add_seconds_full (gint priority,
507 GSourceFunc function,
509 GDestroyNotify notify);
510 guint g_timeout_add_seconds (guint interval,
511 GSourceFunc function,
513 guint g_child_watch_add_full (gint priority,
515 GChildWatchFunc function,
517 GDestroyNotify notify);
518 guint g_child_watch_add (GPid pid,
519 GChildWatchFunc function,
521 guint g_idle_add (GSourceFunc function,
523 guint g_idle_add_full (gint priority,
524 GSourceFunc function,
526 GDestroyNotify notify);
527 gboolean g_idle_remove_by_data (gpointer data);
529 void g_main_context_invoke_full (GMainContext *context,
531 GSourceFunc function,
533 GDestroyNotify notify);
534 void g_main_context_invoke (GMainContext *context,
535 GSourceFunc function,
538 /* Hook for GClosure / GSource integration. Don't touch */
539 GLIB_VAR GSourceFuncs g_timeout_funcs;
540 GLIB_VAR GSourceFuncs g_child_watch_funcs;
541 GLIB_VAR GSourceFuncs g_idle_funcs;
545 #endif /* __G_MAIN_H__ */