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.
109 * The `GSourceFuncs` 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. #G_SOURCE_CONTINUE and
153 * #G_SOURCE_REMOVE are more memorable names for the return value.
155 typedef gboolean (*GSourceFunc
) (gpointer user_data
);
159 * @pid: the process id of the child process
160 * @status: Status information about the child process, encoded
161 * in a platform-specific manner
162 * @user_data: user data passed to g_child_watch_add()
164 * Prototype of a #GChildWatchSource callback, called when a child
165 * process has exited. To interpret @status, see the documentation
166 * for g_spawn_check_exit_status().
168 typedef void (*GChildWatchFunc
) (GPid pid
,
174 gpointer callback_data
;
175 GSourceCallbackFuncs
*callback_funcs
;
177 const GSourceFuncs
*source_funcs
;
180 GMainContext
*context
;
193 GSourcePrivate
*priv
;
196 struct _GSourceCallbackFuncs
198 void (*ref
) (gpointer cb_data
);
199 void (*unref
) (gpointer cb_data
);
200 void (*get
) (gpointer cb_data
,
207 * GSourceDummyMarshal:
209 * This is just a placeholder for #GClosureMarshal,
210 * which cannot be used here for dependency reasons.
212 typedef void (*GSourceDummyMarshal
) (void);
216 gboolean (*prepare
) (GSource
*source
,
218 gboolean (*check
) (GSource
*source
);
219 gboolean (*dispatch
) (GSource
*source
,
220 GSourceFunc callback
,
222 void (*finalize
) (GSource
*source
); /* Can be NULL */
225 /* For use by g_source_set_closure */
226 GSourceFunc closure_callback
;
227 GSourceDummyMarshal closure_marshal
; /* Really is of type GClosureMarshal */
230 /* Standard priorities */
235 * Use this for high priority event sources.
237 * It is not used within GLib or GTK+.
239 #define G_PRIORITY_HIGH -100
242 * G_PRIORITY_DEFAULT:
244 * Use this for default priority event sources.
246 * In GLib this priority is used when adding timeout functions
247 * with g_timeout_add(). In GDK this priority is used for events
250 #define G_PRIORITY_DEFAULT 0
253 * G_PRIORITY_HIGH_IDLE:
255 * Use this for high priority idle functions.
257 * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
258 * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
259 * done to ensure that any pending resizes are processed before any
260 * pending redraws, so that widgets are not redrawn twice unnecessarily.)
262 #define G_PRIORITY_HIGH_IDLE 100
265 * G_PRIORITY_DEFAULT_IDLE:
267 * Use this for default priority idle functions.
269 * In GLib this priority is used when adding idle functions with
272 #define G_PRIORITY_DEFAULT_IDLE 200
277 * Use this for very low priority background tasks.
279 * It is not used within GLib or GTK+.
281 #define G_PRIORITY_LOW 300
286 * Use this macro as the return value of a #GSourceFunc to remove
287 * the #GSource from the main loop.
291 #define G_SOURCE_REMOVE FALSE
296 * Use this macro as the return value of a #GSourceFunc to leave
297 * the #GSource in the main loop.
301 #define G_SOURCE_CONTINUE TRUE
305 GLIB_AVAILABLE_IN_ALL
306 GMainContext
*g_main_context_new (void);
307 GLIB_AVAILABLE_IN_ALL
308 GMainContext
*g_main_context_ref (GMainContext
*context
);
309 GLIB_AVAILABLE_IN_ALL
310 void g_main_context_unref (GMainContext
*context
);
311 GLIB_AVAILABLE_IN_ALL
312 GMainContext
*g_main_context_default (void);
314 GLIB_AVAILABLE_IN_ALL
315 gboolean
g_main_context_iteration (GMainContext
*context
,
317 GLIB_AVAILABLE_IN_ALL
318 gboolean
g_main_context_pending (GMainContext
*context
);
320 /* For implementation of legacy interfaces
322 GLIB_AVAILABLE_IN_ALL
323 GSource
*g_main_context_find_source_by_id (GMainContext
*context
,
325 GLIB_AVAILABLE_IN_ALL
326 GSource
*g_main_context_find_source_by_user_data (GMainContext
*context
,
328 GLIB_AVAILABLE_IN_ALL
329 GSource
*g_main_context_find_source_by_funcs_user_data (GMainContext
*context
,
333 /* Low level functions for implementing custom main loops.
335 GLIB_AVAILABLE_IN_ALL
336 void g_main_context_wakeup (GMainContext
*context
);
337 GLIB_AVAILABLE_IN_ALL
338 gboolean
g_main_context_acquire (GMainContext
*context
);
339 GLIB_AVAILABLE_IN_ALL
340 void g_main_context_release (GMainContext
*context
);
341 GLIB_AVAILABLE_IN_ALL
342 gboolean
g_main_context_is_owner (GMainContext
*context
);
343 GLIB_AVAILABLE_IN_ALL
344 gboolean
g_main_context_wait (GMainContext
*context
,
348 GLIB_AVAILABLE_IN_ALL
349 gboolean
g_main_context_prepare (GMainContext
*context
,
351 GLIB_AVAILABLE_IN_ALL
352 gint
g_main_context_query (GMainContext
*context
,
357 GLIB_AVAILABLE_IN_ALL
358 gint
g_main_context_check (GMainContext
*context
,
362 GLIB_AVAILABLE_IN_ALL
363 void g_main_context_dispatch (GMainContext
*context
);
365 GLIB_AVAILABLE_IN_ALL
366 void g_main_context_set_poll_func (GMainContext
*context
,
368 GLIB_AVAILABLE_IN_ALL
369 GPollFunc
g_main_context_get_poll_func (GMainContext
*context
);
371 /* Low level functions for use by source implementations
373 GLIB_AVAILABLE_IN_ALL
374 void g_main_context_add_poll (GMainContext
*context
,
377 GLIB_AVAILABLE_IN_ALL
378 void g_main_context_remove_poll (GMainContext
*context
,
381 GLIB_AVAILABLE_IN_ALL
382 gint
g_main_depth (void);
383 GLIB_AVAILABLE_IN_ALL
384 GSource
*g_main_current_source (void);
386 /* GMainContexts for other threads
388 GLIB_AVAILABLE_IN_ALL
389 void g_main_context_push_thread_default (GMainContext
*context
);
390 GLIB_AVAILABLE_IN_ALL
391 void g_main_context_pop_thread_default (GMainContext
*context
);
392 GLIB_AVAILABLE_IN_ALL
393 GMainContext
*g_main_context_get_thread_default (void);
394 GLIB_AVAILABLE_IN_ALL
395 GMainContext
*g_main_context_ref_thread_default (void);
399 GLIB_AVAILABLE_IN_ALL
400 GMainLoop
*g_main_loop_new (GMainContext
*context
,
401 gboolean is_running
);
402 GLIB_AVAILABLE_IN_ALL
403 void g_main_loop_run (GMainLoop
*loop
);
404 GLIB_AVAILABLE_IN_ALL
405 void g_main_loop_quit (GMainLoop
*loop
);
406 GLIB_AVAILABLE_IN_ALL
407 GMainLoop
*g_main_loop_ref (GMainLoop
*loop
);
408 GLIB_AVAILABLE_IN_ALL
409 void g_main_loop_unref (GMainLoop
*loop
);
410 GLIB_AVAILABLE_IN_ALL
411 gboolean
g_main_loop_is_running (GMainLoop
*loop
);
412 GLIB_AVAILABLE_IN_ALL
413 GMainContext
*g_main_loop_get_context (GMainLoop
*loop
);
417 GLIB_AVAILABLE_IN_ALL
418 GSource
*g_source_new (GSourceFuncs
*source_funcs
,
420 GLIB_AVAILABLE_IN_ALL
421 GSource
*g_source_ref (GSource
*source
);
422 GLIB_AVAILABLE_IN_ALL
423 void g_source_unref (GSource
*source
);
425 GLIB_AVAILABLE_IN_ALL
426 guint
g_source_attach (GSource
*source
,
427 GMainContext
*context
);
428 GLIB_AVAILABLE_IN_ALL
429 void g_source_destroy (GSource
*source
);
431 GLIB_AVAILABLE_IN_ALL
432 void g_source_set_priority (GSource
*source
,
434 GLIB_AVAILABLE_IN_ALL
435 gint
g_source_get_priority (GSource
*source
);
436 GLIB_AVAILABLE_IN_ALL
437 void g_source_set_can_recurse (GSource
*source
,
438 gboolean can_recurse
);
439 GLIB_AVAILABLE_IN_ALL
440 gboolean
g_source_get_can_recurse (GSource
*source
);
441 GLIB_AVAILABLE_IN_ALL
442 guint
g_source_get_id (GSource
*source
);
444 GLIB_AVAILABLE_IN_ALL
445 GMainContext
*g_source_get_context (GSource
*source
);
447 GLIB_AVAILABLE_IN_ALL
448 void g_source_set_callback (GSource
*source
,
451 GDestroyNotify notify
);
453 GLIB_AVAILABLE_IN_ALL
454 void g_source_set_funcs (GSource
*source
,
455 GSourceFuncs
*funcs
);
456 GLIB_AVAILABLE_IN_ALL
457 gboolean
g_source_is_destroyed (GSource
*source
);
459 GLIB_AVAILABLE_IN_ALL
460 void g_source_set_name (GSource
*source
,
462 GLIB_AVAILABLE_IN_ALL
463 const char * g_source_get_name (GSource
*source
);
464 GLIB_AVAILABLE_IN_ALL
465 void g_source_set_name_by_id (guint tag
,
468 GLIB_AVAILABLE_IN_2_36
469 void g_source_set_ready_time (GSource
*source
,
471 GLIB_AVAILABLE_IN_2_36
472 gint64
g_source_get_ready_time (GSource
*source
);
475 GLIB_AVAILABLE_IN_2_36
476 gpointer
g_source_add_unix_fd (GSource
*source
,
478 GIOCondition events
);
479 GLIB_AVAILABLE_IN_2_36
480 void g_source_modify_unix_fd (GSource
*source
,
482 GIOCondition new_events
);
483 GLIB_AVAILABLE_IN_2_36
484 void g_source_remove_unix_fd (GSource
*source
,
486 GLIB_AVAILABLE_IN_2_36
487 GIOCondition
g_source_query_unix_fd (GSource
*source
,
491 /* Used to implement g_source_connect_closure and internally*/
492 GLIB_AVAILABLE_IN_ALL
493 void g_source_set_callback_indirect (GSource
*source
,
494 gpointer callback_data
,
495 GSourceCallbackFuncs
*callback_funcs
);
497 GLIB_AVAILABLE_IN_ALL
498 void g_source_add_poll (GSource
*source
,
500 GLIB_AVAILABLE_IN_ALL
501 void g_source_remove_poll (GSource
*source
,
504 GLIB_AVAILABLE_IN_ALL
505 void g_source_add_child_source (GSource
*source
,
506 GSource
*child_source
);
507 GLIB_AVAILABLE_IN_ALL
508 void g_source_remove_child_source (GSource
*source
,
509 GSource
*child_source
);
511 GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time
)
512 void g_source_get_current_time (GSource
*source
,
515 GLIB_AVAILABLE_IN_ALL
516 gint64
g_source_get_time (GSource
*source
);
518 /* void g_source_connect_closure (GSource *source,
522 /* Specific source types
524 GLIB_AVAILABLE_IN_ALL
525 GSource
*g_idle_source_new (void);
526 GLIB_AVAILABLE_IN_ALL
527 GSource
*g_child_watch_source_new (GPid pid
);
528 GLIB_AVAILABLE_IN_ALL
529 GSource
*g_timeout_source_new (guint interval
);
530 GLIB_AVAILABLE_IN_ALL
531 GSource
*g_timeout_source_new_seconds (guint interval
);
533 /* Miscellaneous functions
535 GLIB_AVAILABLE_IN_ALL
536 void g_get_current_time (GTimeVal
*result
);
537 GLIB_AVAILABLE_IN_ALL
538 gint64
g_get_monotonic_time (void);
539 GLIB_AVAILABLE_IN_ALL
540 gint64
g_get_real_time (void);
543 /* Source manipulation by ID */
544 GLIB_AVAILABLE_IN_ALL
545 gboolean
g_source_remove (guint tag
);
546 GLIB_AVAILABLE_IN_ALL
547 gboolean
g_source_remove_by_user_data (gpointer user_data
);
548 GLIB_AVAILABLE_IN_ALL
549 gboolean
g_source_remove_by_funcs_user_data (GSourceFuncs
*funcs
,
552 /* Idles, child watchers and timeouts */
553 GLIB_AVAILABLE_IN_ALL
554 guint
g_timeout_add_full (gint priority
,
556 GSourceFunc function
,
558 GDestroyNotify notify
);
559 GLIB_AVAILABLE_IN_ALL
560 guint
g_timeout_add (guint interval
,
561 GSourceFunc function
,
563 GLIB_AVAILABLE_IN_ALL
564 guint
g_timeout_add_seconds_full (gint priority
,
566 GSourceFunc function
,
568 GDestroyNotify notify
);
569 GLIB_AVAILABLE_IN_ALL
570 guint
g_timeout_add_seconds (guint interval
,
571 GSourceFunc function
,
573 GLIB_AVAILABLE_IN_ALL
574 guint
g_child_watch_add_full (gint priority
,
576 GChildWatchFunc function
,
578 GDestroyNotify notify
);
579 GLIB_AVAILABLE_IN_ALL
580 guint
g_child_watch_add (GPid pid
,
581 GChildWatchFunc function
,
583 GLIB_AVAILABLE_IN_ALL
584 guint
g_idle_add (GSourceFunc function
,
586 GLIB_AVAILABLE_IN_ALL
587 guint
g_idle_add_full (gint priority
,
588 GSourceFunc function
,
590 GDestroyNotify notify
);
591 GLIB_AVAILABLE_IN_ALL
592 gboolean
g_idle_remove_by_data (gpointer data
);
594 GLIB_AVAILABLE_IN_ALL
595 void g_main_context_invoke_full (GMainContext
*context
,
597 GSourceFunc function
,
599 GDestroyNotify notify
);
600 GLIB_AVAILABLE_IN_ALL
601 void g_main_context_invoke (GMainContext
*context
,
602 GSourceFunc function
,
605 /* Hook for GClosure / GSource integration. Don't touch */
606 GLIB_VAR GSourceFuncs g_timeout_funcs
;
607 GLIB_VAR GSourceFuncs g_child_watch_funcs
;
608 GLIB_VAR GSourceFuncs g_idle_funcs
;
610 GLIB_VAR GSourceFuncs g_unix_signal_funcs
;
611 GLIB_VAR GSourceFuncs g_unix_fd_source_funcs
;
616 #endif /* __G_MAIN_H__ */