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