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.
23 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
24 #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;
56 typedef struct _GSourcePrivate GSourcePrivate;
59 * GSourceCallbackFuncs:
60 * @ref: Called when a reference is added to the callback object
61 * @unref: Called when a reference to the callback object is dropped
62 * @get: Called to extract the callback function and data from the
65 * The <structname>GSourceCallbackFuncs</structname> struct contains
66 * functions for managing callback objects.
68 typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs;
72 * @prepare: Called before all the file descriptors are polled. If the
73 * source can determine that it is ready here (without waiting for the
74 * results of the poll() call) it should return %TRUE. It can also return
75 * a @timeout_ value which should be the maximum timeout (in milliseconds)
76 * which should be passed to the poll() call. The actual timeout used will
77 * be -1 if all sources returned -1, or it will be the minimum of all the
78 * @timeout_ values returned which were >= 0.
79 * @check: Called after all the file descriptors are polled. The source
80 * should return %TRUE if it is ready to be dispatched. Note that some
81 * time may have passed since the previous prepare function was called,
82 * so the source should be checked again here.
83 * @dispatch: Called to dispatch the event source, after it has returned
84 * %TRUE in either its @prepare or its @check function. The @dispatch
85 * function is passed in a callback function and data. The callback
86 * function may be %NULL if the source was never connected to a callback
87 * using g_source_set_callback(). The @dispatch function should call the
88 * callback function with @user_data and whatever additional parameters
89 * are needed for this type of event source.
90 * @finalize: Called when the source is finalized.
92 * The <structname>GSourceFuncs</structname> struct contains a table of
93 * functions used to handle event sources in a generic manner.
95 * For idle sources, the prepare and check functions always return %TRUE
96 * to indicate that the source is always ready to be processed. The prepare
97 * function also returns a timeout value of 0 to ensure that the poll() call
98 * doesn't block (since that would be time wasted which could have been spent
99 * running the idle function).
101 * For timeout sources, the prepare and check functions both return %TRUE
102 * if the timeout interval has expired. The prepare function also returns
103 * a timeout value to ensure that the poll() call doesn't block too long
104 * and miss the next timeout.
106 * For file descriptor sources, the prepare function typically returns %FALSE,
107 * since it must wait until poll() has been called before it knows whether
108 * any events need to be processed. It sets the returned timeout to -1 to
109 * indicate that it doesn't mind how long the poll() call blocks. In the
110 * check function, it tests the results of the poll() call to see if the
111 * required condition has been met, and returns %TRUE if so.
113 typedef struct _GSourceFuncs GSourceFuncs;
118 * A type which is used to hold a process identification.
120 * On UNIX, processes are identified by a process id (an integer),
121 * while Windows uses process handles (which are pointers).
123 * GPid is used in GLib only for descendant processes spawned with
124 * the g_spawn functions.
129 * @user_data: data passed to the function, set when the source was
130 * created with one of the above functions
132 * Specifies the type of function passed to g_timeout_add(),
133 * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
135 * Returns: %FALSE if the source should be removed
137 typedef gboolean (*GSourceFunc) (gpointer user_data);
141 * @pid: the process id of the child process
142 * @status: Status information about the child process, encoded
143 * in a platform-specific manner
144 * @user_data: user data passed to g_child_watch_add()
146 * Prototype of a #GChildWatchSource callback, called when a child
147 * process has exited. To interpret @status, see the documentation
148 * for g_spawn_check_exit_status().
150 typedef void (*GChildWatchFunc) (GPid pid,
156 gpointer callback_data;
157 GSourceCallbackFuncs *callback_funcs;
159 const GSourceFuncs *source_funcs;
162 GMainContext *context;
175 GSourcePrivate *priv;
178 struct _GSourceCallbackFuncs
180 void (*ref) (gpointer cb_data);
181 void (*unref) (gpointer cb_data);
182 void (*get) (gpointer cb_data,
189 * GSourceDummyMarshal:
191 * This is just a placeholder for #GClosureMarshal,
192 * which cannot be used here for dependency reasons.
194 typedef void (*GSourceDummyMarshal) (void);
198 gboolean (*prepare) (GSource *source,
200 gboolean (*check) (GSource *source);
201 gboolean (*dispatch) (GSource *source,
202 GSourceFunc callback,
204 void (*finalize) (GSource *source); /* Can be NULL */
207 /* For use by g_source_set_closure */
208 GSourceFunc closure_callback;
209 GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
212 /* Standard priorities */
217 * Use this for high priority event sources.
219 * It is not used within GLib or GTK+.
221 #define G_PRIORITY_HIGH -100
224 * G_PRIORITY_DEFAULT:
226 * Use this for default priority event sources.
228 * In GLib this priority is used when adding timeout functions
229 * with g_timeout_add(). In GDK this priority is used for events
232 #define G_PRIORITY_DEFAULT 0
235 * G_PRIORITY_HIGH_IDLE:
237 * Use this for high priority idle functions.
239 * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
240 * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
241 * done to ensure that any pending resizes are processed before any
242 * pending redraws, so that widgets are not redrawn twice unnecessarily.)
244 #define G_PRIORITY_HIGH_IDLE 100
247 * G_PRIORITY_DEFAULT_IDLE:
249 * Use this for default priority idle functions.
251 * In GLib this priority is used when adding idle functions with
254 #define G_PRIORITY_DEFAULT_IDLE 200
259 * Use this for very low priority background tasks.
261 * It is not used within GLib or GTK+.
263 #define G_PRIORITY_LOW 300
268 * Use this macro as the return value of a #GSourceFunc to remove
269 * the #GSource from the main loop.
273 #define G_SOURCE_REMOVE FALSE
278 * Use this macro as the return value of a #GSourceFunc to leave
279 * the #GSource in the main loop.
283 #define G_SOURCE_CONTINUE TRUE
287 GLIB_AVAILABLE_IN_ALL
288 GMainContext *g_main_context_new (void);
289 GLIB_AVAILABLE_IN_ALL
290 GMainContext *g_main_context_ref (GMainContext *context);
291 GLIB_AVAILABLE_IN_ALL
292 void g_main_context_unref (GMainContext *context);
293 GLIB_AVAILABLE_IN_ALL
294 GMainContext *g_main_context_default (void);
296 GLIB_AVAILABLE_IN_ALL
297 gboolean g_main_context_iteration (GMainContext *context,
299 GLIB_AVAILABLE_IN_ALL
300 gboolean g_main_context_pending (GMainContext *context);
302 /* For implementation of legacy interfaces
304 GLIB_AVAILABLE_IN_ALL
305 GSource *g_main_context_find_source_by_id (GMainContext *context,
307 GLIB_AVAILABLE_IN_ALL
308 GSource *g_main_context_find_source_by_user_data (GMainContext *context,
310 GLIB_AVAILABLE_IN_ALL
311 GSource *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
315 /* Low level functions for implementing custom main loops.
317 GLIB_AVAILABLE_IN_ALL
318 void g_main_context_wakeup (GMainContext *context);
319 GLIB_AVAILABLE_IN_ALL
320 gboolean g_main_context_acquire (GMainContext *context);
321 GLIB_AVAILABLE_IN_ALL
322 void g_main_context_release (GMainContext *context);
323 GLIB_AVAILABLE_IN_ALL
324 gboolean g_main_context_is_owner (GMainContext *context);
325 GLIB_AVAILABLE_IN_ALL
326 gboolean g_main_context_wait (GMainContext *context,
330 GLIB_AVAILABLE_IN_ALL
331 gboolean g_main_context_prepare (GMainContext *context,
333 GLIB_AVAILABLE_IN_ALL
334 gint g_main_context_query (GMainContext *context,
339 GLIB_AVAILABLE_IN_ALL
340 gint g_main_context_check (GMainContext *context,
344 GLIB_AVAILABLE_IN_ALL
345 void g_main_context_dispatch (GMainContext *context);
347 GLIB_AVAILABLE_IN_ALL
348 void g_main_context_set_poll_func (GMainContext *context,
350 GLIB_AVAILABLE_IN_ALL
351 GPollFunc g_main_context_get_poll_func (GMainContext *context);
353 /* Low level functions for use by source implementations
355 GLIB_AVAILABLE_IN_ALL
356 void g_main_context_add_poll (GMainContext *context,
359 GLIB_AVAILABLE_IN_ALL
360 void g_main_context_remove_poll (GMainContext *context,
363 GLIB_AVAILABLE_IN_ALL
364 gint g_main_depth (void);
365 GLIB_AVAILABLE_IN_ALL
366 GSource *g_main_current_source (void);
368 /* GMainContexts for other threads
370 GLIB_AVAILABLE_IN_ALL
371 void g_main_context_push_thread_default (GMainContext *context);
372 GLIB_AVAILABLE_IN_ALL
373 void g_main_context_pop_thread_default (GMainContext *context);
374 GLIB_AVAILABLE_IN_ALL
375 GMainContext *g_main_context_get_thread_default (void);
376 GLIB_AVAILABLE_IN_ALL
377 GMainContext *g_main_context_ref_thread_default (void);
381 GLIB_AVAILABLE_IN_ALL
382 GMainLoop *g_main_loop_new (GMainContext *context,
383 gboolean is_running);
384 GLIB_AVAILABLE_IN_ALL
385 void g_main_loop_run (GMainLoop *loop);
386 GLIB_AVAILABLE_IN_ALL
387 void g_main_loop_quit (GMainLoop *loop);
388 GLIB_AVAILABLE_IN_ALL
389 GMainLoop *g_main_loop_ref (GMainLoop *loop);
390 GLIB_AVAILABLE_IN_ALL
391 void g_main_loop_unref (GMainLoop *loop);
392 GLIB_AVAILABLE_IN_ALL
393 gboolean g_main_loop_is_running (GMainLoop *loop);
394 GLIB_AVAILABLE_IN_ALL
395 GMainContext *g_main_loop_get_context (GMainLoop *loop);
399 GLIB_AVAILABLE_IN_ALL
400 GSource *g_source_new (GSourceFuncs *source_funcs,
402 GLIB_AVAILABLE_IN_ALL
403 GSource *g_source_ref (GSource *source);
404 GLIB_AVAILABLE_IN_ALL
405 void g_source_unref (GSource *source);
407 GLIB_AVAILABLE_IN_ALL
408 guint g_source_attach (GSource *source,
409 GMainContext *context);
410 GLIB_AVAILABLE_IN_ALL
411 void g_source_destroy (GSource *source);
413 GLIB_AVAILABLE_IN_ALL
414 void g_source_set_priority (GSource *source,
416 GLIB_AVAILABLE_IN_ALL
417 gint g_source_get_priority (GSource *source);
418 GLIB_AVAILABLE_IN_ALL
419 void g_source_set_can_recurse (GSource *source,
420 gboolean can_recurse);
421 GLIB_AVAILABLE_IN_ALL
422 gboolean g_source_get_can_recurse (GSource *source);
423 GLIB_AVAILABLE_IN_ALL
424 guint g_source_get_id (GSource *source);
426 GLIB_AVAILABLE_IN_ALL
427 GMainContext *g_source_get_context (GSource *source);
429 GLIB_AVAILABLE_IN_ALL
430 void g_source_set_callback (GSource *source,
433 GDestroyNotify notify);
435 GLIB_AVAILABLE_IN_ALL
436 void g_source_set_funcs (GSource *source,
437 GSourceFuncs *funcs);
438 GLIB_AVAILABLE_IN_ALL
439 gboolean g_source_is_destroyed (GSource *source);
441 GLIB_AVAILABLE_IN_ALL
442 void g_source_set_name (GSource *source,
444 GLIB_AVAILABLE_IN_ALL
445 const char * g_source_get_name (GSource *source);
446 GLIB_AVAILABLE_IN_ALL
447 void g_source_set_name_by_id (guint tag,
451 /* Used to implement g_source_connect_closure and internally*/
452 GLIB_AVAILABLE_IN_ALL
453 void g_source_set_callback_indirect (GSource *source,
454 gpointer callback_data,
455 GSourceCallbackFuncs *callback_funcs);
457 GLIB_AVAILABLE_IN_ALL
458 void g_source_add_poll (GSource *source,
460 GLIB_AVAILABLE_IN_ALL
461 void g_source_remove_poll (GSource *source,
464 GLIB_AVAILABLE_IN_ALL
465 void g_source_add_child_source (GSource *source,
466 GSource *child_source);
467 GLIB_AVAILABLE_IN_ALL
468 void g_source_remove_child_source (GSource *source,
469 GSource *child_source);
471 GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time)
472 void g_source_get_current_time (GSource *source,
475 GLIB_AVAILABLE_IN_ALL
476 gint64 g_source_get_time (GSource *source);
478 /* void g_source_connect_closure (GSource *source,
482 /* Specific source types
484 GLIB_AVAILABLE_IN_ALL
485 GSource *g_idle_source_new (void);
486 GLIB_AVAILABLE_IN_ALL
487 GSource *g_child_watch_source_new (GPid pid);
488 GLIB_AVAILABLE_IN_ALL
489 GSource *g_timeout_source_new (guint interval);
490 GLIB_AVAILABLE_IN_ALL
491 GSource *g_timeout_source_new_seconds (guint interval);
493 /* Miscellaneous functions
495 GLIB_AVAILABLE_IN_ALL
496 void g_get_current_time (GTimeVal *result);
497 GLIB_AVAILABLE_IN_ALL
498 gint64 g_get_monotonic_time (void);
499 GLIB_AVAILABLE_IN_ALL
500 gint64 g_get_real_time (void);
503 /* Source manipulation by ID */
504 GLIB_AVAILABLE_IN_ALL
505 gboolean g_source_remove (guint tag);
506 GLIB_AVAILABLE_IN_ALL
507 gboolean g_source_remove_by_user_data (gpointer user_data);
508 GLIB_AVAILABLE_IN_ALL
509 gboolean g_source_remove_by_funcs_user_data (GSourceFuncs *funcs,
512 /* Idles, child watchers and timeouts */
513 GLIB_AVAILABLE_IN_ALL
514 guint g_timeout_add_full (gint priority,
516 GSourceFunc function,
518 GDestroyNotify notify);
519 GLIB_AVAILABLE_IN_ALL
520 guint g_timeout_add (guint interval,
521 GSourceFunc function,
523 GLIB_AVAILABLE_IN_ALL
524 guint g_timeout_add_seconds_full (gint priority,
526 GSourceFunc function,
528 GDestroyNotify notify);
529 GLIB_AVAILABLE_IN_ALL
530 guint g_timeout_add_seconds (guint interval,
531 GSourceFunc function,
533 GLIB_AVAILABLE_IN_ALL
534 guint g_child_watch_add_full (gint priority,
536 GChildWatchFunc function,
538 GDestroyNotify notify);
539 GLIB_AVAILABLE_IN_ALL
540 guint g_child_watch_add (GPid pid,
541 GChildWatchFunc function,
543 GLIB_AVAILABLE_IN_ALL
544 guint g_idle_add (GSourceFunc function,
546 GLIB_AVAILABLE_IN_ALL
547 guint g_idle_add_full (gint priority,
548 GSourceFunc function,
550 GDestroyNotify notify);
551 GLIB_AVAILABLE_IN_ALL
552 gboolean g_idle_remove_by_data (gpointer data);
554 GLIB_AVAILABLE_IN_ALL
555 void g_main_context_invoke_full (GMainContext *context,
557 GSourceFunc function,
559 GDestroyNotify notify);
560 GLIB_AVAILABLE_IN_ALL
561 void g_main_context_invoke (GMainContext *context,
562 GSourceFunc function,
565 /* Hook for GClosure / GSource integration. Don't touch */
566 GLIB_VAR GSourceFuncs g_timeout_funcs;
567 GLIB_VAR GSourceFuncs g_child_watch_funcs;
568 GLIB_VAR GSourceFuncs g_idle_funcs;
572 #endif /* __G_MAIN_H__ */