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 Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 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 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * 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 * lower 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, or if a ready time
100 * has been reached. The @dispatch function receives a callback function and
101 * user data. The callback function may be %NULL if the source was never
102 * connected to a callback using g_source_set_callback(). The @dispatch
103 * function should call the callback function with @user_data and whatever
104 * additional parameters are needed for this type of event source. The
105 * return value of the @dispatch function should be #G_SOURCE_REMOVE if the
106 * source should be removed or #G_SOURCE_CONTINUE to keep it.
107 * @finalize: Called when the source is finalized. At this point, the source
108 * will have been destroyed, had its callback cleared, and have been removed
109 * from its #GMainContext, but it will still have its final reference count,
110 * so methods can be called on it from within this function.
111 *
112 * The `GSourceFuncs` struct contains a table of
113 * functions used to handle event sources in a generic manner.
114 *
115 * For idle sources, the prepare and check functions always return %TRUE
116 * to indicate that the source is always ready to be processed. The prepare
117 * function also returns a timeout value of 0 to ensure that the poll() call
118 * doesn't block (since that would be time wasted which could have been spent
119 * running the idle function).
120 *
121 * For timeout sources, the prepare and check functions both return %TRUE
122 * if the timeout interval has expired. The prepare function also returns
123 * a timeout value to ensure that the poll() call doesn't block too long
124 * and miss the next timeout.
125 *
126 * For file descriptor sources, the prepare function typically returns %FALSE,
127 * since it must wait until poll() has been called before it knows whether
128 * any events need to be processed. It sets the returned timeout to -1 to
129 * indicate that it doesn't mind how long the poll() call blocks. In the
130 * check function, it tests the results of the poll() call to see if the
131 * required condition has been met, and returns %TRUE if so.
132 */
133typedef struct _GSourceFuncs GSourceFuncs;
134
135/**
136 * GPid:
137 *
138 * A type which is used to hold a process identification.
139 *
140 * On UNIX, processes are identified by a process id (an integer),
141 * while Windows uses process handles (which are pointers).
142 *
143 * GPid is used in GLib only for descendant processes spawned with
144 * the g_spawn functions.
145 */
146/* defined in glibconfig.h */
147
148/**
149 * G_PID_FORMAT:
150 *
151 * A format specifier that can be used in printf()-style format strings
152 * when printing a #GPid.
153 *
154 * Since: 2.50
155 */
156/* defined in glibconfig.h */
157
158/**
159 * GSourceFunc:
160 * @user_data: data passed to the function, set when the source was
161 * created with one of the above functions
162 *
163 * Specifies the type of function passed to g_timeout_add(),
164 * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
165 *
166 * Returns: %FALSE if the source should be removed. #G_SOURCE_CONTINUE and
167 * #G_SOURCE_REMOVE are more memorable names for the return value.
168 */
169typedef gboolean (*GSourceFunc) (gpointer user_data);
170
171/**
172 * GChildWatchFunc:
173 * @pid: the process id of the child process
174 * @status: Status information about the child process, encoded
175 * in a platform-specific manner
176 * @user_data: user data passed to g_child_watch_add()
177 *
178 * Prototype of a #GChildWatchSource callback, called when a child
179 * process has exited. To interpret @status, see the documentation
180 * for g_spawn_check_exit_status().
181 */
182typedef void (*GChildWatchFunc) (GPid pid,
183 gint status,
184 gpointer user_data);
185struct _GSource
186{
187 /*< private >*/
188 gpointer callback_data;
189 GSourceCallbackFuncs *callback_funcs;
190
191 const GSourceFuncs *source_funcs;
192 guint ref_count;
193
194 GMainContext *context;
195
196 gint priority;
197 guint flags;
198 guint source_id;
199
200 GSList *poll_fds;
201
202 GSource *prev;
203 GSource *next;
204
205 char *name;
206
207 GSourcePrivate *priv;
208};
209
210struct _GSourceCallbackFuncs
211{
212 void (*ref) (gpointer cb_data);
213 void (*unref) (gpointer cb_data);
214 void (*get) (gpointer cb_data,
215 GSource *source,
216 GSourceFunc *func,
217 gpointer *data);
218};
219
220/**
221 * GSourceDummyMarshal:
222 *
223 * This is just a placeholder for #GClosureMarshal,
224 * which cannot be used here for dependency reasons.
225 */
226typedef void (*GSourceDummyMarshal) (void);
227
228struct _GSourceFuncs
229{
230 gboolean (*prepare) (GSource *source,
231 gint *timeout_);
232 gboolean (*check) (GSource *source);
233 gboolean (*dispatch) (GSource *source,
234 GSourceFunc callback,
235 gpointer user_data);
236 void (*finalize) (GSource *source); /* Can be NULL */
237
238 /*< private >*/
239 /* For use by g_source_set_closure */
240 GSourceFunc closure_callback;
241 GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
242};
243
244/* Standard priorities */
245
246/**
247 * G_PRIORITY_HIGH:
248 *
249 * Use this for high priority event sources.
250 *
251 * It is not used within GLib or GTK+.
252 */
253#define G_PRIORITY_HIGH -100
254
255/**
256 * G_PRIORITY_DEFAULT:
257 *
258 * Use this for default priority event sources.
259 *
260 * In GLib this priority is used when adding timeout functions
261 * with g_timeout_add(). In GDK this priority is used for events
262 * from the X server.
263 */
264#define G_PRIORITY_DEFAULT 0
265
266/**
267 * G_PRIORITY_HIGH_IDLE:
268 *
269 * Use this for high priority idle functions.
270 *
271 * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
272 * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
273 * done to ensure that any pending resizes are processed before any
274 * pending redraws, so that widgets are not redrawn twice unnecessarily.)
275 */
276#define G_PRIORITY_HIGH_IDLE 100
277
278/**
279 * G_PRIORITY_DEFAULT_IDLE:
280 *
281 * Use this for default priority idle functions.
282 *
283 * In GLib this priority is used when adding idle functions with
284 * g_idle_add().
285 */
286#define G_PRIORITY_DEFAULT_IDLE 200
287
288/**
289 * G_PRIORITY_LOW:
290 *
291 * Use this for very low priority background tasks.
292 *
293 * It is not used within GLib or GTK+.
294 */
295#define G_PRIORITY_LOW 300
296
297/**
298 * G_SOURCE_REMOVE:
299 *
300 * Use this macro as the return value of a #GSourceFunc to remove
301 * the #GSource from the main loop.
302 *
303 * Since: 2.32
304 */
305#define G_SOURCE_REMOVE FALSE
306
307/**
308 * G_SOURCE_CONTINUE:
309 *
310 * Use this macro as the return value of a #GSourceFunc to leave
311 * the #GSource in the main loop.
312 *
313 * Since: 2.32
314 */
315#define G_SOURCE_CONTINUE TRUE
316
317/* GMainContext: */
318
319GLIB_AVAILABLE_IN_ALL
320GMainContext *g_main_context_new (void);
321GLIB_AVAILABLE_IN_ALL
322GMainContext *g_main_context_ref (GMainContext *context);
323GLIB_AVAILABLE_IN_ALL
324void g_main_context_unref (GMainContext *context);
325GLIB_AVAILABLE_IN_ALL
326GMainContext *g_main_context_default (void);
327
328GLIB_AVAILABLE_IN_ALL
329gboolean g_main_context_iteration (GMainContext *context,
330 gboolean may_block);
331GLIB_AVAILABLE_IN_ALL
332gboolean g_main_context_pending (GMainContext *context);
333
334/* For implementation of legacy interfaces
335 */
336GLIB_AVAILABLE_IN_ALL
337GSource *g_main_context_find_source_by_id (GMainContext *context,
338 guint source_id);
339GLIB_AVAILABLE_IN_ALL
340GSource *g_main_context_find_source_by_user_data (GMainContext *context,
341 gpointer user_data);
342GLIB_AVAILABLE_IN_ALL
343GSource *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
344 GSourceFuncs *funcs,
345 gpointer user_data);
346
347/* Low level functions for implementing custom main loops.
348 */
349GLIB_AVAILABLE_IN_ALL
350void g_main_context_wakeup (GMainContext *context);
351GLIB_AVAILABLE_IN_ALL
352gboolean g_main_context_acquire (GMainContext *context);
353GLIB_AVAILABLE_IN_ALL
354void g_main_context_release (GMainContext *context);
355GLIB_AVAILABLE_IN_ALL
356gboolean g_main_context_is_owner (GMainContext *context);
357GLIB_AVAILABLE_IN_ALL
358gboolean g_main_context_wait (GMainContext *context,
359 GCond *cond,
360 GMutex *mutex);
361
362GLIB_AVAILABLE_IN_ALL
363gboolean g_main_context_prepare (GMainContext *context,
364 gint *priority);
365GLIB_AVAILABLE_IN_ALL
366gint g_main_context_query (GMainContext *context,
367 gint max_priority,
368 gint *timeout_,
369 GPollFD *fds,
370 gint n_fds);
371GLIB_AVAILABLE_IN_ALL
372gboolean g_main_context_check (GMainContext *context,
373 gint max_priority,
374 GPollFD *fds,
375 gint n_fds);
376GLIB_AVAILABLE_IN_ALL
377void g_main_context_dispatch (GMainContext *context);
378
379GLIB_AVAILABLE_IN_ALL
380void g_main_context_set_poll_func (GMainContext *context,
381 GPollFunc func);
382GLIB_AVAILABLE_IN_ALL
383GPollFunc g_main_context_get_poll_func (GMainContext *context);
384
385/* Low level functions for use by source implementations
386 */
387GLIB_AVAILABLE_IN_ALL
388void g_main_context_add_poll (GMainContext *context,
389 GPollFD *fd,
390 gint priority);
391GLIB_AVAILABLE_IN_ALL
392void g_main_context_remove_poll (GMainContext *context,
393 GPollFD *fd);
394
395GLIB_AVAILABLE_IN_ALL
396gint g_main_depth (void);
397GLIB_AVAILABLE_IN_ALL
398GSource *g_main_current_source (void);
399
400/* GMainContexts for other threads
401 */
402GLIB_AVAILABLE_IN_ALL
403void g_main_context_push_thread_default (GMainContext *context);
404GLIB_AVAILABLE_IN_ALL
405void g_main_context_pop_thread_default (GMainContext *context);
406GLIB_AVAILABLE_IN_ALL
407GMainContext *g_main_context_get_thread_default (void);
408GLIB_AVAILABLE_IN_ALL
409GMainContext *g_main_context_ref_thread_default (void);
410
411/* GMainLoop: */
412
413GLIB_AVAILABLE_IN_ALL
414GMainLoop *g_main_loop_new (GMainContext *context,
415 gboolean is_running);
416GLIB_AVAILABLE_IN_ALL
417void g_main_loop_run (GMainLoop *loop);
418GLIB_AVAILABLE_IN_ALL
419void g_main_loop_quit (GMainLoop *loop);
420GLIB_AVAILABLE_IN_ALL
421GMainLoop *g_main_loop_ref (GMainLoop *loop);
422GLIB_AVAILABLE_IN_ALL
423void g_main_loop_unref (GMainLoop *loop);
424GLIB_AVAILABLE_IN_ALL
425gboolean g_main_loop_is_running (GMainLoop *loop);
426GLIB_AVAILABLE_IN_ALL
427GMainContext *g_main_loop_get_context (GMainLoop *loop);
428
429/* GSource: */
430
431GLIB_AVAILABLE_IN_ALL
432GSource *g_source_new (GSourceFuncs *source_funcs,
433 guint struct_size);
434GLIB_AVAILABLE_IN_ALL
435GSource *g_source_ref (GSource *source);
436GLIB_AVAILABLE_IN_ALL
437void g_source_unref (GSource *source);
438
439GLIB_AVAILABLE_IN_ALL
440guint g_source_attach (GSource *source,
441 GMainContext *context);
442GLIB_AVAILABLE_IN_ALL
443void g_source_destroy (GSource *source);
444
445GLIB_AVAILABLE_IN_ALL
446void g_source_set_priority (GSource *source,
447 gint priority);
448GLIB_AVAILABLE_IN_ALL
449gint g_source_get_priority (GSource *source);
450GLIB_AVAILABLE_IN_ALL
451void g_source_set_can_recurse (GSource *source,
452 gboolean can_recurse);
453GLIB_AVAILABLE_IN_ALL
454gboolean g_source_get_can_recurse (GSource *source);
455GLIB_AVAILABLE_IN_ALL
456guint g_source_get_id (GSource *source);
457
458GLIB_AVAILABLE_IN_ALL
459GMainContext *g_source_get_context (GSource *source);
460
461GLIB_AVAILABLE_IN_ALL
462void g_source_set_callback (GSource *source,
463 GSourceFunc func,
464 gpointer data,
465 GDestroyNotify notify);
466
467GLIB_AVAILABLE_IN_ALL
468void g_source_set_funcs (GSource *source,
469 GSourceFuncs *funcs);
470GLIB_AVAILABLE_IN_ALL
471gboolean g_source_is_destroyed (GSource *source);
472
473GLIB_AVAILABLE_IN_ALL
474void g_source_set_name (GSource *source,
475 const char *name);
476GLIB_AVAILABLE_IN_ALL
477const char * g_source_get_name (GSource *source);
478GLIB_AVAILABLE_IN_ALL
479void g_source_set_name_by_id (guint tag,
480 const char *name);
481
482GLIB_AVAILABLE_IN_2_36
483void g_source_set_ready_time (GSource *source,
484 gint64 ready_time);
485GLIB_AVAILABLE_IN_2_36
486gint64 g_source_get_ready_time (GSource *source);
487
488#ifdef G_OS_UNIX
489GLIB_AVAILABLE_IN_2_36
490gpointer g_source_add_unix_fd (GSource *source,
491 gint fd,
492 GIOCondition events);
493GLIB_AVAILABLE_IN_2_36
494void g_source_modify_unix_fd (GSource *source,
495 gpointer tag,
496 GIOCondition new_events);
497GLIB_AVAILABLE_IN_2_36
498void g_source_remove_unix_fd (GSource *source,
499 gpointer tag);
500GLIB_AVAILABLE_IN_2_36
501GIOCondition g_source_query_unix_fd (GSource *source,
502 gpointer tag);
503#endif
504
505/* Used to implement g_source_connect_closure and internally*/
506GLIB_AVAILABLE_IN_ALL
507void g_source_set_callback_indirect (GSource *source,
508 gpointer callback_data,
509 GSourceCallbackFuncs *callback_funcs);
510
511GLIB_AVAILABLE_IN_ALL
512void g_source_add_poll (GSource *source,
513 GPollFD *fd);
514GLIB_AVAILABLE_IN_ALL
515void g_source_remove_poll (GSource *source,
516 GPollFD *fd);
517
518GLIB_AVAILABLE_IN_ALL
519void g_source_add_child_source (GSource *source,
520 GSource *child_source);
521GLIB_AVAILABLE_IN_ALL
522void g_source_remove_child_source (GSource *source,
523 GSource *child_source);
524
525GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time)
526void g_source_get_current_time (GSource *source,
527 GTimeVal *timeval);
528
529GLIB_AVAILABLE_IN_ALL
530gint64 g_source_get_time (GSource *source);
531
532 /* void g_source_connect_closure (GSource *source,
533 GClosure *closure);
534 */
535
536/* Specific source types
537 */
538GLIB_AVAILABLE_IN_ALL
539GSource *g_idle_source_new (void);
540GLIB_AVAILABLE_IN_ALL
541GSource *g_child_watch_source_new (GPid pid);
542GLIB_AVAILABLE_IN_ALL
543GSource *g_timeout_source_new (guint interval);
544GLIB_AVAILABLE_IN_ALL
545GSource *g_timeout_source_new_seconds (guint interval);
546
547/* Miscellaneous functions
548 */
549GLIB_AVAILABLE_IN_ALL
550void g_get_current_time (GTimeVal *result);
551GLIB_AVAILABLE_IN_ALL
552gint64 g_get_monotonic_time (void);
553GLIB_AVAILABLE_IN_ALL
554gint64 g_get_real_time (void);
555
556
557/* Source manipulation by ID */
558GLIB_AVAILABLE_IN_ALL
559gboolean g_source_remove (guint tag);
560GLIB_AVAILABLE_IN_ALL
561gboolean g_source_remove_by_user_data (gpointer user_data);
562GLIB_AVAILABLE_IN_ALL
563gboolean g_source_remove_by_funcs_user_data (GSourceFuncs *funcs,
564 gpointer user_data);
565
566/**
567 * GClearHandleFunc:
568 * @handle_id: the handle ID to clear
569 *
570 * Specifies the type of function passed to g_clear_handle_id().
571 * The implementation is expected to free the resource identified
572 * by @handle_id; for instance, if @handle_id is a #GSource ID,
573 * g_source_remove() can be used.
574 *
575 * Since: 2.56
576 */
577typedef void (* GClearHandleFunc) (guint handle_id);
578
579GLIB_AVAILABLE_IN_2_56
580void g_clear_handle_id (guint *tag_ptr,
581 GClearHandleFunc clear_func);
582
583#define g_clear_handle_id(tag_ptr, clear_func) \
584 G_STMT_START { \
585 G_STATIC_ASSERT (sizeof *(tag_ptr) == sizeof (guint)); \
586 guint *_tag_ptr = (guint *) (tag_ptr); \
587 guint _handle_id; \
588 \
589 _handle_id = *_tag_ptr; \
590 if (_handle_id > 0) \
591 { \
592 *_tag_ptr = 0; \
593 clear_func (_handle_id); \
594 } \
595 } G_STMT_END
596
597/* Idles, child watchers and timeouts */
598GLIB_AVAILABLE_IN_ALL
599guint g_timeout_add_full (gint priority,
600 guint interval,
601 GSourceFunc function,
602 gpointer data,
603 GDestroyNotify notify);
604GLIB_AVAILABLE_IN_ALL
605guint g_timeout_add (guint interval,
606 GSourceFunc function,
607 gpointer data);
608GLIB_AVAILABLE_IN_ALL
609guint g_timeout_add_seconds_full (gint priority,
610 guint interval,
611 GSourceFunc function,
612 gpointer data,
613 GDestroyNotify notify);
614GLIB_AVAILABLE_IN_ALL
615guint g_timeout_add_seconds (guint interval,
616 GSourceFunc function,
617 gpointer data);
618GLIB_AVAILABLE_IN_ALL
619guint g_child_watch_add_full (gint priority,
620 GPid pid,
621 GChildWatchFunc function,
622 gpointer data,
623 GDestroyNotify notify);
624GLIB_AVAILABLE_IN_ALL
625guint g_child_watch_add (GPid pid,
626 GChildWatchFunc function,
627 gpointer data);
628GLIB_AVAILABLE_IN_ALL
629guint g_idle_add (GSourceFunc function,
630 gpointer data);
631GLIB_AVAILABLE_IN_ALL
632guint g_idle_add_full (gint priority,
633 GSourceFunc function,
634 gpointer data,
635 GDestroyNotify notify);
636GLIB_AVAILABLE_IN_ALL
637gboolean g_idle_remove_by_data (gpointer data);
638
639GLIB_AVAILABLE_IN_ALL
640void g_main_context_invoke_full (GMainContext *context,
641 gint priority,
642 GSourceFunc function,
643 gpointer data,
644 GDestroyNotify notify);
645GLIB_AVAILABLE_IN_ALL
646void g_main_context_invoke (GMainContext *context,
647 GSourceFunc function,
648 gpointer data);
649
650/* Hook for GClosure / GSource integration. Don't touch */
651GLIB_VAR GSourceFuncs g_timeout_funcs;
652GLIB_VAR GSourceFuncs g_child_watch_funcs;
653GLIB_VAR GSourceFuncs g_idle_funcs;
654#ifdef G_OS_UNIX
655GLIB_VAR GSourceFuncs g_unix_signal_funcs;
656GLIB_VAR GSourceFuncs g_unix_fd_source_funcs;
657#endif
658
659G_END_DECLS
660
661#endif /* __G_MAIN_H__ */
662