1/* gmain.h - the GLib Main loop
2 * Copyright (C) 1998-2000 Red Hat, Inc.
3 *
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.
8 *
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.
13 *
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/>.
16 */
17
18#ifndef __G_MAIN_H__
19#define __G_MAIN_H__
20
21#if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
22#error "Only <glib.h> can be included directly."
23#endif
24
25#include <glib/gpoll.h>
26#include <glib/gslist.h>
27#include <glib/gthread.h>
28
29G_BEGIN_DECLS
30
31typedef enum /*< flags >*/
32{
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
39} GIOCondition;
40
41
42/**
43 * GMainContext:
44 *
45 * The `GMainContext` struct is an opaque data
46 * type representing a set of sources to be handled in a main loop.
47 */
48typedef struct _GMainContext GMainContext;
49
50/**
51 * GMainLoop:
52 *
53 * The `GMainLoop` struct is an opaque data type
54 * representing the main event loop of a GLib or GTK+ application.
55 */
56typedef struct _GMainLoop GMainLoop;
57
58/**
59 * GSource:
60 *
61 * The `GSource` struct is an opaque data type
62 * representing an event source.
63 */
64typedef struct _GSource GSource;
65typedef struct _GSourcePrivate GSourcePrivate;
66
67/**
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
72 * callback object.
73
74 * The `GSourceCallbackFuncs` struct contains
75 * functions for managing callback objects.
76 */
77typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs;
78
79/**
80 * GSourceFuncs:
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
97 * %FALSE.
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.
108 *
109 * The `GSourceFuncs` struct contains a table of
110 * functions used to handle event sources in a generic manner.
111 *
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).
117 *
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.
122 *
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.
129 */
130typedef struct _GSourceFuncs GSourceFuncs;
131
132/**
133 * GPid:
134 *
135 * A type which is used to hold a process identification.
136 *
137 * On UNIX, processes are identified by a process id (an integer),
138 * while Windows uses process handles (which are pointers).
139 *
140 * GPid is used in GLib only for descendant processes spawned with
141 * the g_spawn functions.
142 */
143
144/**
145 * GSourceFunc:
146 * @user_data: data passed to the function, set when the source was
147 * created with one of the above functions
148 *
149 * Specifies the type of function passed to g_timeout_add(),
150 * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
151 *
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.
154 */
155typedef gboolean (*GSourceFunc) (gpointer user_data);
156
157/**
158 * GChildWatchFunc:
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()
163 *
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().
167 */
168typedef void (*GChildWatchFunc) (GPid pid,
169 gint status,
170 gpointer user_data);
171struct _GSource
172{
173 /*< private >*/
174 gpointer callback_data;
175 GSourceCallbackFuncs *callback_funcs;
176
177 const GSourceFuncs *source_funcs;
178 guint ref_count;
179
180 GMainContext *context;
181
182 gint priority;
183 guint flags;
184 guint source_id;
185
186 GSList *poll_fds;
187
188 GSource *prev;
189 GSource *next;
190
191 char *name;
192
193 GSourcePrivate *priv;
194};
195
196struct _GSourceCallbackFuncs
197{
198 void (*ref) (gpointer cb_data);
199 void (*unref) (gpointer cb_data);
200 void (*get) (gpointer cb_data,
201 GSource *source,
202 GSourceFunc *func,
203 gpointer *data);
204};
205
206/**
207 * GSourceDummyMarshal:
208 *
209 * This is just a placeholder for #GClosureMarshal,
210 * which cannot be used here for dependency reasons.
211 */
212typedef void (*GSourceDummyMarshal) (void);
213
214struct _GSourceFuncs
215{
216 gboolean (*prepare) (GSource *source,
217 gint *timeout_);
218 gboolean (*check) (GSource *source);
219 gboolean (*dispatch) (GSource *source,
220 GSourceFunc callback,
221 gpointer user_data);
222 void (*finalize) (GSource *source); /* Can be NULL */
223
224 /*< private >*/
225 /* For use by g_source_set_closure */
226 GSourceFunc closure_callback;
227 GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
228};
229
230/* Standard priorities */
231
232/**
233 * G_PRIORITY_HIGH:
234 *
235 * Use this for high priority event sources.
236 *
237 * It is not used within GLib or GTK+.
238 */
239#define G_PRIORITY_HIGH -100
240
241/**
242 * G_PRIORITY_DEFAULT:
243 *
244 * Use this for default priority event sources.
245 *
246 * In GLib this priority is used when adding timeout functions
247 * with g_timeout_add(). In GDK this priority is used for events
248 * from the X server.
249 */
250#define G_PRIORITY_DEFAULT 0
251
252/**
253 * G_PRIORITY_HIGH_IDLE:
254 *
255 * Use this for high priority idle functions.
256 *
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.)
261 */
262#define G_PRIORITY_HIGH_IDLE 100
263
264/**
265 * G_PRIORITY_DEFAULT_IDLE:
266 *
267 * Use this for default priority idle functions.
268 *
269 * In GLib this priority is used when adding idle functions with
270 * g_idle_add().
271 */
272#define G_PRIORITY_DEFAULT_IDLE 200
273
274/**
275 * G_PRIORITY_LOW:
276 *
277 * Use this for very low priority background tasks.
278 *
279 * It is not used within GLib or GTK+.
280 */
281#define G_PRIORITY_LOW 300
282
283/**
284 * G_SOURCE_REMOVE:
285 *
286 * Use this macro as the return value of a #GSourceFunc to remove
287 * the #GSource from the main loop.
288 *
289 * Since: 2.32
290 */
291#define G_SOURCE_REMOVE FALSE
292
293/**
294 * G_SOURCE_CONTINUE:
295 *
296 * Use this macro as the return value of a #GSourceFunc to leave
297 * the #GSource in the main loop.
298 *
299 * Since: 2.32
300 */
301#define G_SOURCE_CONTINUE TRUE
302
303/* GMainContext: */
304
305GLIB_AVAILABLE_IN_ALL
306GMainContext *g_main_context_new (void);
307GLIB_AVAILABLE_IN_ALL
308GMainContext *g_main_context_ref (GMainContext *context);
309GLIB_AVAILABLE_IN_ALL
310void g_main_context_unref (GMainContext *context);
311GLIB_AVAILABLE_IN_ALL
312GMainContext *g_main_context_default (void);
313
314GLIB_AVAILABLE_IN_ALL
315gboolean g_main_context_iteration (GMainContext *context,
316 gboolean may_block);
317GLIB_AVAILABLE_IN_ALL
318gboolean g_main_context_pending (GMainContext *context);
319
320/* For implementation of legacy interfaces
321 */
322GLIB_AVAILABLE_IN_ALL
323GSource *g_main_context_find_source_by_id (GMainContext *context,
324 guint source_id);
325GLIB_AVAILABLE_IN_ALL
326GSource *g_main_context_find_source_by_user_data (GMainContext *context,
327 gpointer user_data);
328GLIB_AVAILABLE_IN_ALL
329GSource *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
330 GSourceFuncs *funcs,
331 gpointer user_data);
332
333/* Low level functions for implementing custom main loops.
334 */
335GLIB_AVAILABLE_IN_ALL
336void g_main_context_wakeup (GMainContext *context);
337GLIB_AVAILABLE_IN_ALL
338gboolean g_main_context_acquire (GMainContext *context);
339GLIB_AVAILABLE_IN_ALL
340void g_main_context_release (GMainContext *context);
341GLIB_AVAILABLE_IN_ALL
342gboolean g_main_context_is_owner (GMainContext *context);
343GLIB_AVAILABLE_IN_ALL
344gboolean g_main_context_wait (GMainContext *context,
345 GCond *cond,
346 GMutex *mutex);
347
348GLIB_AVAILABLE_IN_ALL
349gboolean g_main_context_prepare (GMainContext *context,
350 gint *priority);
351GLIB_AVAILABLE_IN_ALL
352gint g_main_context_query (GMainContext *context,
353 gint max_priority,
354 gint *timeout_,
355 GPollFD *fds,
356 gint n_fds);
357GLIB_AVAILABLE_IN_ALL
358gint g_main_context_check (GMainContext *context,
359 gint max_priority,
360 GPollFD *fds,
361 gint n_fds);
362GLIB_AVAILABLE_IN_ALL
363void g_main_context_dispatch (GMainContext *context);
364
365GLIB_AVAILABLE_IN_ALL
366void g_main_context_set_poll_func (GMainContext *context,
367 GPollFunc func);
368GLIB_AVAILABLE_IN_ALL
369GPollFunc g_main_context_get_poll_func (GMainContext *context);
370
371/* Low level functions for use by source implementations
372 */
373GLIB_AVAILABLE_IN_ALL
374void g_main_context_add_poll (GMainContext *context,
375 GPollFD *fd,
376 gint priority);
377GLIB_AVAILABLE_IN_ALL
378void g_main_context_remove_poll (GMainContext *context,
379 GPollFD *fd);
380
381GLIB_AVAILABLE_IN_ALL
382gint g_main_depth (void);
383GLIB_AVAILABLE_IN_ALL
384GSource *g_main_current_source (void);
385
386/* GMainContexts for other threads
387 */
388GLIB_AVAILABLE_IN_ALL
389void g_main_context_push_thread_default (GMainContext *context);
390GLIB_AVAILABLE_IN_ALL
391void g_main_context_pop_thread_default (GMainContext *context);
392GLIB_AVAILABLE_IN_ALL
393GMainContext *g_main_context_get_thread_default (void);
394GLIB_AVAILABLE_IN_ALL
395GMainContext *g_main_context_ref_thread_default (void);
396
397/* GMainLoop: */
398
399GLIB_AVAILABLE_IN_ALL
400GMainLoop *g_main_loop_new (GMainContext *context,
401 gboolean is_running);
402GLIB_AVAILABLE_IN_ALL
403void g_main_loop_run (GMainLoop *loop);
404GLIB_AVAILABLE_IN_ALL
405void g_main_loop_quit (GMainLoop *loop);
406GLIB_AVAILABLE_IN_ALL
407GMainLoop *g_main_loop_ref (GMainLoop *loop);
408GLIB_AVAILABLE_IN_ALL
409void g_main_loop_unref (GMainLoop *loop);
410GLIB_AVAILABLE_IN_ALL
411gboolean g_main_loop_is_running (GMainLoop *loop);
412GLIB_AVAILABLE_IN_ALL
413GMainContext *g_main_loop_get_context (GMainLoop *loop);
414
415/* GSource: */
416
417GLIB_AVAILABLE_IN_ALL
418GSource *g_source_new (GSourceFuncs *source_funcs,
419 guint struct_size);
420GLIB_AVAILABLE_IN_ALL
421GSource *g_source_ref (GSource *source);
422GLIB_AVAILABLE_IN_ALL
423void g_source_unref (GSource *source);
424
425GLIB_AVAILABLE_IN_ALL
426guint g_source_attach (GSource *source,
427 GMainContext *context);
428GLIB_AVAILABLE_IN_ALL
429void g_source_destroy (GSource *source);
430
431GLIB_AVAILABLE_IN_ALL
432void g_source_set_priority (GSource *source,
433 gint priority);
434GLIB_AVAILABLE_IN_ALL
435gint g_source_get_priority (GSource *source);
436GLIB_AVAILABLE_IN_ALL
437void g_source_set_can_recurse (GSource *source,
438 gboolean can_recurse);
439GLIB_AVAILABLE_IN_ALL
440gboolean g_source_get_can_recurse (GSource *source);
441GLIB_AVAILABLE_IN_ALL
442guint g_source_get_id (GSource *source);
443
444GLIB_AVAILABLE_IN_ALL
445GMainContext *g_source_get_context (GSource *source);
446
447GLIB_AVAILABLE_IN_ALL
448void g_source_set_callback (GSource *source,
449 GSourceFunc func,
450 gpointer data,
451 GDestroyNotify notify);
452
453GLIB_AVAILABLE_IN_ALL
454void g_source_set_funcs (GSource *source,
455 GSourceFuncs *funcs);
456GLIB_AVAILABLE_IN_ALL
457gboolean g_source_is_destroyed (GSource *source);
458
459GLIB_AVAILABLE_IN_ALL
460void g_source_set_name (GSource *source,
461 const char *name);
462GLIB_AVAILABLE_IN_ALL
463const char * g_source_get_name (GSource *source);
464GLIB_AVAILABLE_IN_ALL
465void g_source_set_name_by_id (guint tag,
466 const char *name);
467
468GLIB_AVAILABLE_IN_2_36
469void g_source_set_ready_time (GSource *source,
470 gint64 ready_time);
471GLIB_AVAILABLE_IN_2_36
472gint64 g_source_get_ready_time (GSource *source);
473
474#ifdef G_OS_UNIX
475GLIB_AVAILABLE_IN_2_36
476gpointer g_source_add_unix_fd (GSource *source,
477 gint fd,
478 GIOCondition events);
479GLIB_AVAILABLE_IN_2_36
480void g_source_modify_unix_fd (GSource *source,
481 gpointer tag,
482 GIOCondition new_events);
483GLIB_AVAILABLE_IN_2_36
484void g_source_remove_unix_fd (GSource *source,
485 gpointer tag);
486GLIB_AVAILABLE_IN_2_36
487GIOCondition g_source_query_unix_fd (GSource *source,
488 gpointer tag);
489#endif
490
491/* Used to implement g_source_connect_closure and internally*/
492GLIB_AVAILABLE_IN_ALL
493void g_source_set_callback_indirect (GSource *source,
494 gpointer callback_data,
495 GSourceCallbackFuncs *callback_funcs);
496
497GLIB_AVAILABLE_IN_ALL
498void g_source_add_poll (GSource *source,
499 GPollFD *fd);
500GLIB_AVAILABLE_IN_ALL
501void g_source_remove_poll (GSource *source,
502 GPollFD *fd);
503
504GLIB_AVAILABLE_IN_ALL
505void g_source_add_child_source (GSource *source,
506 GSource *child_source);
507GLIB_AVAILABLE_IN_ALL
508void g_source_remove_child_source (GSource *source,
509 GSource *child_source);
510
511GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time)
512void g_source_get_current_time (GSource *source,
513 GTimeVal *timeval);
514
515GLIB_AVAILABLE_IN_ALL
516gint64 g_source_get_time (GSource *source);
517
518 /* void g_source_connect_closure (GSource *source,
519 GClosure *closure);
520 */
521
522/* Specific source types
523 */
524GLIB_AVAILABLE_IN_ALL
525GSource *g_idle_source_new (void);
526GLIB_AVAILABLE_IN_ALL
527GSource *g_child_watch_source_new (GPid pid);
528GLIB_AVAILABLE_IN_ALL
529GSource *g_timeout_source_new (guint interval);
530GLIB_AVAILABLE_IN_ALL
531GSource *g_timeout_source_new_seconds (guint interval);
532
533/* Miscellaneous functions
534 */
535GLIB_AVAILABLE_IN_ALL
536void g_get_current_time (GTimeVal *result);
537GLIB_AVAILABLE_IN_ALL
538gint64 g_get_monotonic_time (void);
539GLIB_AVAILABLE_IN_ALL
540gint64 g_get_real_time (void);
541
542
543/* Source manipulation by ID */
544GLIB_AVAILABLE_IN_ALL
545gboolean g_source_remove (guint tag);
546GLIB_AVAILABLE_IN_ALL
547gboolean g_source_remove_by_user_data (gpointer user_data);
548GLIB_AVAILABLE_IN_ALL
549gboolean g_source_remove_by_funcs_user_data (GSourceFuncs *funcs,
550 gpointer user_data);
551
552/* Idles, child watchers and timeouts */
553GLIB_AVAILABLE_IN_ALL
554guint g_timeout_add_full (gint priority,
555 guint interval,
556 GSourceFunc function,
557 gpointer data,
558 GDestroyNotify notify);
559GLIB_AVAILABLE_IN_ALL
560guint g_timeout_add (guint interval,
561 GSourceFunc function,
562 gpointer data);
563GLIB_AVAILABLE_IN_ALL
564guint g_timeout_add_seconds_full (gint priority,
565 guint interval,
566 GSourceFunc function,
567 gpointer data,
568 GDestroyNotify notify);
569GLIB_AVAILABLE_IN_ALL
570guint g_timeout_add_seconds (guint interval,
571 GSourceFunc function,
572 gpointer data);
573GLIB_AVAILABLE_IN_ALL
574guint g_child_watch_add_full (gint priority,
575 GPid pid,
576 GChildWatchFunc function,
577 gpointer data,
578 GDestroyNotify notify);
579GLIB_AVAILABLE_IN_ALL
580guint g_child_watch_add (GPid pid,
581 GChildWatchFunc function,
582 gpointer data);
583GLIB_AVAILABLE_IN_ALL
584guint g_idle_add (GSourceFunc function,
585 gpointer data);
586GLIB_AVAILABLE_IN_ALL
587guint g_idle_add_full (gint priority,
588 GSourceFunc function,
589 gpointer data,
590 GDestroyNotify notify);
591GLIB_AVAILABLE_IN_ALL
592gboolean g_idle_remove_by_data (gpointer data);
593
594GLIB_AVAILABLE_IN_ALL
595void g_main_context_invoke_full (GMainContext *context,
596 gint priority,
597 GSourceFunc function,
598 gpointer data,
599 GDestroyNotify notify);
600GLIB_AVAILABLE_IN_ALL
601void g_main_context_invoke (GMainContext *context,
602 GSourceFunc function,
603 gpointer data);
604
605/* Hook for GClosure / GSource integration. Don't touch */
606GLIB_VAR GSourceFuncs g_timeout_funcs;
607GLIB_VAR GSourceFuncs g_child_watch_funcs;
608GLIB_VAR GSourceFuncs g_idle_funcs;
609#ifdef G_OS_UNIX
610GLIB_VAR GSourceFuncs g_unix_signal_funcs;
611GLIB_VAR GSourceFuncs g_unix_fd_source_funcs;
612#endif
613
614G_END_DECLS
615
616#endif /* __G_MAIN_H__ */
617