[kdbus] KDBUS_ITEM_PAYLOAD_OFF items are (once again) relative to msg header
[platform/upstream/glib.git] / glib / gmain.h
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 GLIB_AVAILABLE_IN_ALL
529 GSource *g_timeout_source_new_seconds (guint interval);
530
531 /* Miscellaneous functions
532  */
533 GLIB_AVAILABLE_IN_ALL
534 void   g_get_current_time                 (GTimeVal       *result);
535 GLIB_AVAILABLE_IN_ALL
536 gint64 g_get_monotonic_time               (void);
537 GLIB_AVAILABLE_IN_ALL
538 gint64 g_get_real_time                    (void);
539
540
541 /* Source manipulation by ID */
542 GLIB_AVAILABLE_IN_ALL
543 gboolean g_source_remove                     (guint          tag);
544 GLIB_AVAILABLE_IN_ALL
545 gboolean g_source_remove_by_user_data        (gpointer       user_data);
546 GLIB_AVAILABLE_IN_ALL
547 gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
548                                               gpointer       user_data);
549
550 /* Idles, child watchers and timeouts */
551 GLIB_AVAILABLE_IN_ALL
552 guint    g_timeout_add_full         (gint            priority,
553                                      guint           interval,
554                                      GSourceFunc     function,
555                                      gpointer        data,
556                                      GDestroyNotify  notify);
557 GLIB_AVAILABLE_IN_ALL
558 guint    g_timeout_add              (guint           interval,
559                                      GSourceFunc     function,
560                                      gpointer        data);
561 GLIB_AVAILABLE_IN_ALL
562 guint    g_timeout_add_seconds_full (gint            priority,
563                                      guint           interval,
564                                      GSourceFunc     function,
565                                      gpointer        data,
566                                      GDestroyNotify  notify);
567 GLIB_AVAILABLE_IN_ALL
568 guint    g_timeout_add_seconds      (guint           interval,
569                                      GSourceFunc     function,
570                                      gpointer        data);
571 GLIB_AVAILABLE_IN_ALL
572 guint    g_child_watch_add_full     (gint            priority,
573                                      GPid            pid,
574                                      GChildWatchFunc function,
575                                      gpointer        data,
576                                      GDestroyNotify  notify);
577 GLIB_AVAILABLE_IN_ALL
578 guint    g_child_watch_add          (GPid            pid,
579                                      GChildWatchFunc function,
580                                      gpointer        data);
581 GLIB_AVAILABLE_IN_ALL
582 guint    g_idle_add                 (GSourceFunc     function,
583                                      gpointer        data);
584 GLIB_AVAILABLE_IN_ALL
585 guint    g_idle_add_full            (gint            priority,
586                                      GSourceFunc     function,
587                                      gpointer        data,
588                                      GDestroyNotify  notify);
589 GLIB_AVAILABLE_IN_ALL
590 gboolean g_idle_remove_by_data      (gpointer        data);
591
592 GLIB_AVAILABLE_IN_ALL
593 void     g_main_context_invoke_full (GMainContext   *context,
594                                      gint            priority,
595                                      GSourceFunc     function,
596                                      gpointer        data,
597                                      GDestroyNotify  notify);
598 GLIB_AVAILABLE_IN_ALL
599 void     g_main_context_invoke      (GMainContext   *context,
600                                      GSourceFunc     function,
601                                      gpointer        data);
602
603 /* Hook for GClosure / GSource integration. Don't touch */
604 GLIB_VAR GSourceFuncs g_timeout_funcs;
605 GLIB_VAR GSourceFuncs g_child_watch_funcs;
606 GLIB_VAR GSourceFuncs g_idle_funcs;
607 #ifdef G_OS_UNIX
608 GLIB_VAR GSourceFuncs g_unix_signal_funcs;
609 GLIB_VAR GSourceFuncs g_unix_fd_source_funcs;
610 #endif
611
612 G_END_DECLS
613
614 #endif /* __G_MAIN_H__ */