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>
33 typedef enum /*< flags >*/
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
47 * The <structname>GMainContext</structname> struct is an opaque data
48 * type representing a set of sources to be handled in a main loop.
50 typedef struct _GMainContext GMainContext
;
55 * The <structname>GMainLoop</structname> struct is an opaque data type
56 * representing the main event loop of a GLib or GTK+ application.
58 typedef struct _GMainLoop GMainLoop
;
63 * The <structname>GSource</structname> struct is an opaque data type
64 * representing an event source.
66 typedef struct _GSource GSource
;
67 typedef struct _GSourcePrivate GSourcePrivate
;
70 * GSourceCallbackFuncs:
71 * @ref: Called when a reference is added to the callback object
72 * @unref: Called when a reference to the callback object is dropped
73 * @get: Called to extract the callback function and data from the
76 * The <structname>GSourceCallbackFuncs</structname> struct contains
77 * functions for managing callback objects.
79 typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs
;
83 * @prepare: Called before all the file descriptors are polled. If the
84 * source can determine that it is ready here (without waiting for the
85 * results of the poll() call) it should return %TRUE. It can also return
86 * a @timeout_ value which should be the maximum timeout (in milliseconds)
87 * which should be passed to the poll() call. The actual timeout used will
88 * be -1 if all sources returned -1, or it will be the minimum of all the
89 * @timeout_ values returned which were >= 0. Since 2.36 this may
90 * be %NULL, in which case the effect is as if the function always
91 * returns %FALSE with a timeout of -1. If @prepare returns a
92 * timeout and the source also has a 'ready time' set then the
93 * nearer of the two will be used.
94 * @check: Called after all the file descriptors are polled. The source
95 * should return %TRUE if it is ready to be dispatched. Note that some
96 * time may have passed since the previous prepare function was called,
97 * so the source should be checked again here. Since 2.36 this may
98 * be %NULL, in which case the effect is as if the function always
100 * @dispatch: Called to dispatch the event source, after it has returned
101 * %TRUE in either its @prepare or its @check function. The @dispatch
102 * function is passed in a callback function and data. The callback
103 * function may be %NULL if the source was never connected to a callback
104 * using g_source_set_callback(). The @dispatch function should call the
105 * callback function with @user_data and whatever additional parameters
106 * are needed for this type of event source.
107 * @finalize: Called when the source is finalized.
109 * The <structname>GSourceFuncs</structname> struct contains a table of
110 * functions used to handle event sources in a generic manner.
112 * For idle sources, the prepare and check functions always return %TRUE
113 * to indicate that the source is always ready to be processed. The prepare
114 * function also returns a timeout value of 0 to ensure that the poll() call
115 * doesn't block (since that would be time wasted which could have been spent
116 * running the idle function).
118 * For timeout sources, the prepare and check functions both return %TRUE
119 * if the timeout interval has expired. The prepare function also returns
120 * a timeout value to ensure that the poll() call doesn't block too long
121 * and miss the next timeout.
123 * For file descriptor sources, the prepare function typically returns %FALSE,
124 * since it must wait until poll() has been called before it knows whether
125 * any events need to be processed. It sets the returned timeout to -1 to
126 * indicate that it doesn't mind how long the poll() call blocks. In the
127 * check function, it tests the results of the poll() call to see if the
128 * required condition has been met, and returns %TRUE if so.
130 typedef struct _GSourceFuncs GSourceFuncs
;
135 * A type which is used to hold a process identification.
137 * On UNIX, processes are identified by a process id (an integer),
138 * while Windows uses process handles (which are pointers).
140 * GPid is used in GLib only for descendant processes spawned with
141 * the g_spawn functions.
146 * @user_data: data passed to the function, set when the source was
147 * created with one of the above functions
149 * Specifies the type of function passed to g_timeout_add(),
150 * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
152 * Returns: %FALSE if the source should be removed
154 typedef gboolean (*GSourceFunc
) (gpointer user_data
);
158 * @pid: the process id of the child process
159 * @status: Status information about the child process, encoded
160 * in a platform-specific manner
161 * @user_data: user data passed to g_child_watch_add()
163 * Prototype of a #GChildWatchSource callback, called when a child
164 * process has exited. To interpret @status, see the documentation
165 * for g_spawn_check_exit_status().
167 typedef void (*GChildWatchFunc
) (GPid pid
,
173 gpointer callback_data
;
174 GSourceCallbackFuncs
*callback_funcs
;
176 const GSourceFuncs
*source_funcs
;
179 GMainContext
*context
;
192 GSourcePrivate
*priv
;
195 struct _GSourceCallbackFuncs
197 void (*ref
) (gpointer cb_data
);
198 void (*unref
) (gpointer cb_data
);
199 void (*get
) (gpointer cb_data
,
206 * GSourceDummyMarshal:
208 * This is just a placeholder for #GClosureMarshal,
209 * which cannot be used here for dependency reasons.
211 typedef void (*GSourceDummyMarshal
) (void);
215 gboolean (*prepare
) (GSource
*source
,
217 gboolean (*check
) (GSource
*source
);
218 gboolean (*dispatch
) (GSource
*source
,
219 GSourceFunc callback
,
221 void (*finalize
) (GSource
*source
); /* Can be NULL */
224 /* For use by g_source_set_closure */
225 GSourceFunc closure_callback
;
226 GSourceDummyMarshal closure_marshal
; /* Really is of type GClosureMarshal */
229 /* Standard priorities */
234 * Use this for high priority event sources.
236 * It is not used within GLib or GTK+.
238 #define G_PRIORITY_HIGH -100
241 * G_PRIORITY_DEFAULT:
243 * Use this for default priority event sources.
245 * In GLib this priority is used when adding timeout functions
246 * with g_timeout_add(). In GDK this priority is used for events
249 #define G_PRIORITY_DEFAULT 0
252 * G_PRIORITY_HIGH_IDLE:
254 * Use this for high priority idle functions.
256 * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
257 * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
258 * done to ensure that any pending resizes are processed before any
259 * pending redraws, so that widgets are not redrawn twice unnecessarily.)
261 #define G_PRIORITY_HIGH_IDLE 100
264 * G_PRIORITY_DEFAULT_IDLE:
266 * Use this for default priority idle functions.
268 * In GLib this priority is used when adding idle functions with
271 #define G_PRIORITY_DEFAULT_IDLE 200
276 * Use this for very low priority background tasks.
278 * It is not used within GLib or GTK+.
280 #define G_PRIORITY_LOW 300
285 * Use this macro as the return value of a #GSourceFunc to remove
286 * the #GSource from the main loop.
290 #define G_SOURCE_REMOVE FALSE
295 * Use this macro as the return value of a #GSourceFunc to leave
296 * the #GSource in the main loop.
300 #define G_SOURCE_CONTINUE TRUE
304 GLIB_AVAILABLE_IN_ALL
305 GMainContext
*g_main_context_new (void);
306 GLIB_AVAILABLE_IN_ALL
307 GMainContext
*g_main_context_ref (GMainContext
*context
);
308 GLIB_AVAILABLE_IN_ALL
309 void g_main_context_unref (GMainContext
*context
);
310 GLIB_AVAILABLE_IN_ALL
311 GMainContext
*g_main_context_default (void);
313 GLIB_AVAILABLE_IN_ALL
314 gboolean
g_main_context_iteration (GMainContext
*context
,
316 GLIB_AVAILABLE_IN_ALL
317 gboolean
g_main_context_pending (GMainContext
*context
);
319 /* For implementation of legacy interfaces
321 GLIB_AVAILABLE_IN_ALL
322 GSource
*g_main_context_find_source_by_id (GMainContext
*context
,
324 GLIB_AVAILABLE_IN_ALL
325 GSource
*g_main_context_find_source_by_user_data (GMainContext
*context
,
327 GLIB_AVAILABLE_IN_ALL
328 GSource
*g_main_context_find_source_by_funcs_user_data (GMainContext
*context
,
332 /* Low level functions for implementing custom main loops.
334 GLIB_AVAILABLE_IN_ALL
335 void g_main_context_wakeup (GMainContext
*context
);
336 GLIB_AVAILABLE_IN_ALL
337 gboolean
g_main_context_acquire (GMainContext
*context
);
338 GLIB_AVAILABLE_IN_ALL
339 void g_main_context_release (GMainContext
*context
);
340 GLIB_AVAILABLE_IN_ALL
341 gboolean
g_main_context_is_owner (GMainContext
*context
);
342 GLIB_AVAILABLE_IN_ALL
343 gboolean
g_main_context_wait (GMainContext
*context
,
347 GLIB_AVAILABLE_IN_ALL
348 gboolean
g_main_context_prepare (GMainContext
*context
,
350 GLIB_AVAILABLE_IN_ALL
351 gint
g_main_context_query (GMainContext
*context
,
356 GLIB_AVAILABLE_IN_ALL
357 gint
g_main_context_check (GMainContext
*context
,
361 GLIB_AVAILABLE_IN_ALL
362 void g_main_context_dispatch (GMainContext
*context
);
364 GLIB_AVAILABLE_IN_ALL
365 void g_main_context_set_poll_func (GMainContext
*context
,
367 GLIB_AVAILABLE_IN_ALL
368 GPollFunc
g_main_context_get_poll_func (GMainContext
*context
);
370 /* Low level functions for use by source implementations
372 GLIB_AVAILABLE_IN_ALL
373 void g_main_context_add_poll (GMainContext
*context
,
376 GLIB_AVAILABLE_IN_ALL
377 void g_main_context_remove_poll (GMainContext
*context
,
380 GLIB_AVAILABLE_IN_ALL
381 gint
g_main_depth (void);
382 GLIB_AVAILABLE_IN_ALL
383 GSource
*g_main_current_source (void);
385 /* GMainContexts for other threads
387 GLIB_AVAILABLE_IN_ALL
388 void g_main_context_push_thread_default (GMainContext
*context
);
389 GLIB_AVAILABLE_IN_ALL
390 void g_main_context_pop_thread_default (GMainContext
*context
);
391 GLIB_AVAILABLE_IN_ALL
392 GMainContext
*g_main_context_get_thread_default (void);
393 GLIB_AVAILABLE_IN_ALL
394 GMainContext
*g_main_context_ref_thread_default (void);
398 GLIB_AVAILABLE_IN_ALL
399 GMainLoop
*g_main_loop_new (GMainContext
*context
,
400 gboolean is_running
);
401 GLIB_AVAILABLE_IN_ALL
402 void g_main_loop_run (GMainLoop
*loop
);
403 GLIB_AVAILABLE_IN_ALL
404 void g_main_loop_quit (GMainLoop
*loop
);
405 GLIB_AVAILABLE_IN_ALL
406 GMainLoop
*g_main_loop_ref (GMainLoop
*loop
);
407 GLIB_AVAILABLE_IN_ALL
408 void g_main_loop_unref (GMainLoop
*loop
);
409 GLIB_AVAILABLE_IN_ALL
410 gboolean
g_main_loop_is_running (GMainLoop
*loop
);
411 GLIB_AVAILABLE_IN_ALL
412 GMainContext
*g_main_loop_get_context (GMainLoop
*loop
);
416 GLIB_AVAILABLE_IN_ALL
417 GSource
*g_source_new (GSourceFuncs
*source_funcs
,
419 GLIB_AVAILABLE_IN_ALL
420 GSource
*g_source_ref (GSource
*source
);
421 GLIB_AVAILABLE_IN_ALL
422 void g_source_unref (GSource
*source
);
424 GLIB_AVAILABLE_IN_ALL
425 guint
g_source_attach (GSource
*source
,
426 GMainContext
*context
);
427 GLIB_AVAILABLE_IN_ALL
428 void g_source_destroy (GSource
*source
);
430 GLIB_AVAILABLE_IN_ALL
431 void g_source_set_priority (GSource
*source
,
433 GLIB_AVAILABLE_IN_ALL
434 gint
g_source_get_priority (GSource
*source
);
435 GLIB_AVAILABLE_IN_ALL
436 void g_source_set_can_recurse (GSource
*source
,
437 gboolean can_recurse
);
438 GLIB_AVAILABLE_IN_ALL
439 gboolean
g_source_get_can_recurse (GSource
*source
);
440 GLIB_AVAILABLE_IN_ALL
441 guint
g_source_get_id (GSource
*source
);
443 GLIB_AVAILABLE_IN_ALL
444 GMainContext
*g_source_get_context (GSource
*source
);
446 GLIB_AVAILABLE_IN_ALL
447 void g_source_set_callback (GSource
*source
,
450 GDestroyNotify notify
);
452 GLIB_AVAILABLE_IN_ALL
453 void g_source_set_funcs (GSource
*source
,
454 GSourceFuncs
*funcs
);
455 GLIB_AVAILABLE_IN_ALL
456 gboolean
g_source_is_destroyed (GSource
*source
);
458 GLIB_AVAILABLE_IN_ALL
459 void g_source_set_name (GSource
*source
,
461 GLIB_AVAILABLE_IN_ALL
462 const char * g_source_get_name (GSource
*source
);
463 GLIB_AVAILABLE_IN_ALL
464 void g_source_set_name_by_id (guint tag
,
467 GLIB_AVAILABLE_IN_2_36
468 void g_source_set_ready_time (GSource
*source
,
470 GLIB_AVAILABLE_IN_2_36
471 gint64
g_source_get_ready_time (GSource
*source
);
474 GLIB_AVAILABLE_IN_2_36
475 gpointer
g_source_add_unix_fd (GSource
*source
,
477 GIOCondition events
);
478 GLIB_AVAILABLE_IN_2_36
479 void g_source_modify_unix_fd (GSource
*source
,
481 GIOCondition new_events
);
482 GLIB_AVAILABLE_IN_2_36
483 void g_source_remove_unix_fd (GSource
*source
,
485 GLIB_AVAILABLE_IN_2_36
486 GIOCondition
g_source_query_unix_fd (GSource
*source
,
490 /* Used to implement g_source_connect_closure and internally*/
491 GLIB_AVAILABLE_IN_ALL
492 void g_source_set_callback_indirect (GSource
*source
,
493 gpointer callback_data
,
494 GSourceCallbackFuncs
*callback_funcs
);
496 GLIB_AVAILABLE_IN_ALL
497 void g_source_add_poll (GSource
*source
,
499 GLIB_AVAILABLE_IN_ALL
500 void g_source_remove_poll (GSource
*source
,
503 GLIB_AVAILABLE_IN_ALL
504 void g_source_add_child_source (GSource
*source
,
505 GSource
*child_source
);
506 GLIB_AVAILABLE_IN_ALL
507 void g_source_remove_child_source (GSource
*source
,
508 GSource
*child_source
);
510 GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time
)
511 void g_source_get_current_time (GSource
*source
,
514 GLIB_AVAILABLE_IN_ALL
515 gint64
g_source_get_time (GSource
*source
);
517 /* void g_source_connect_closure (GSource *source,
521 /* Specific source types
523 GLIB_AVAILABLE_IN_ALL
524 GSource
*g_idle_source_new (void);
525 GLIB_AVAILABLE_IN_ALL
526 GSource
*g_child_watch_source_new (GPid pid
);
527 GLIB_AVAILABLE_IN_ALL
528 GSource
*g_timeout_source_new (guint interval
);
529 GLIB_AVAILABLE_IN_ALL
530 GSource
*g_timeout_source_new_seconds (guint interval
);
532 /* Miscellaneous functions
534 GLIB_AVAILABLE_IN_ALL
535 void g_get_current_time (GTimeVal
*result
);
536 GLIB_AVAILABLE_IN_ALL
537 gint64
g_get_monotonic_time (void);
538 GLIB_AVAILABLE_IN_ALL
539 gint64
g_get_real_time (void);
542 /* Source manipulation by ID */
543 GLIB_AVAILABLE_IN_ALL
544 gboolean
g_source_remove (guint tag
);
545 GLIB_AVAILABLE_IN_ALL
546 gboolean
g_source_remove_by_user_data (gpointer user_data
);
547 GLIB_AVAILABLE_IN_ALL
548 gboolean
g_source_remove_by_funcs_user_data (GSourceFuncs
*funcs
,
551 /* Idles, child watchers and timeouts */
552 GLIB_AVAILABLE_IN_ALL
553 guint
g_timeout_add_full (gint priority
,
555 GSourceFunc function
,
557 GDestroyNotify notify
);
558 GLIB_AVAILABLE_IN_ALL
559 guint
g_timeout_add (guint interval
,
560 GSourceFunc function
,
562 GLIB_AVAILABLE_IN_ALL
563 guint
g_timeout_add_seconds_full (gint priority
,
565 GSourceFunc function
,
567 GDestroyNotify notify
);
568 GLIB_AVAILABLE_IN_ALL
569 guint
g_timeout_add_seconds (guint interval
,
570 GSourceFunc function
,
572 GLIB_AVAILABLE_IN_ALL
573 guint
g_child_watch_add_full (gint priority
,
575 GChildWatchFunc function
,
577 GDestroyNotify notify
);
578 GLIB_AVAILABLE_IN_ALL
579 guint
g_child_watch_add (GPid pid
,
580 GChildWatchFunc function
,
582 GLIB_AVAILABLE_IN_ALL
583 guint
g_idle_add (GSourceFunc function
,
585 GLIB_AVAILABLE_IN_ALL
586 guint
g_idle_add_full (gint priority
,
587 GSourceFunc function
,
589 GDestroyNotify notify
);
590 GLIB_AVAILABLE_IN_ALL
591 gboolean
g_idle_remove_by_data (gpointer data
);
593 GLIB_AVAILABLE_IN_ALL
594 void g_main_context_invoke_full (GMainContext
*context
,
596 GSourceFunc function
,
598 GDestroyNotify notify
);
599 GLIB_AVAILABLE_IN_ALL
600 void g_main_context_invoke (GMainContext
*context
,
601 GSourceFunc function
,
604 /* Hook for GClosure / GSource integration. Don't touch */
605 GLIB_VAR GSourceFuncs g_timeout_funcs
;
606 GLIB_VAR GSourceFuncs g_child_watch_funcs
;
607 GLIB_VAR GSourceFuncs g_idle_funcs
;
611 #endif /* __G_MAIN_H__ */