added g_list_nth_prev() which walks ->prev instead of ->next.
[platform/upstream/glib.git] / 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, write to the
16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17  * Boston, MA 02111-1307, USA.
18  */
19
20 #ifndef __G_MAIN_H__
21 #define __G_MAIN_H__
22
23 #include <gslist.h>
24 #include <gthread.h>
25
26 G_BEGIN_DECLS
27
28 typedef struct _GMainContext            GMainContext;   /* Opaque */
29 typedef struct _GMainLoop               GMainLoop;      /* Opaque */
30 typedef struct _GSource                 GSource;
31 typedef struct _GSourceCallbackFuncs    GSourceCallbackFuncs;
32 typedef struct _GSourceFuncs            GSourceFuncs;
33
34 typedef gboolean (*GSourceFunc)       (gpointer data);
35
36 struct _GSource
37 {
38   /*< private >*/
39   gpointer callback_data;
40   GSourceCallbackFuncs *callback_funcs;
41
42   GSourceFuncs *source_funcs;
43   guint ref_count;
44
45   GMainContext *context;
46
47   gint priority;
48   guint flags;
49   guint id;
50
51   GSList *poll_fds;
52   
53   GSource *prev;
54   GSource *next;
55 };
56
57 struct _GSourceCallbackFuncs
58 {
59   void (*ref)   (gpointer     cb_data);
60   void (*unref) (gpointer     cb_data);
61   void (*get)   (gpointer     cb_data,
62                  GSourceFunc *func,
63                  gpointer    *data);
64 };
65
66 struct _GSourceFuncs
67 {
68   gboolean (*prepare)  (GSource    *source,
69                         gint       *timeout);
70   gboolean (*check)    (GSource    *source);
71   gboolean (*dispatch) (GSource    *source,
72                         GSourceFunc callback,
73                         gpointer    user_data);
74   void     (*destroy)  (GSource    *source); /* Can be NULL */
75 };
76
77 /* Any definitions using GPollFD or GPollFunc are primarily
78  * for Unix and not guaranteed to be the compatible on all
79  * operating systems on which GLib runs. Right now, the
80  * GLib does use these functions on Win32 as well, but interprets
81  * them in a fairly different way than on Unix. If you use
82  * these definitions, you are should be prepared to recode
83  * for different operating systems.
84  *
85  *
86  * On Win32, the fd in a GPollFD should be Win32 HANDLE (*not* a file
87  * descriptor as provided by the C runtime) that can be used by
88  * MsgWaitForMultipleObjects. This does *not* include file handles
89  * from CreateFile, SOCKETs, nor pipe handles. (But you can use
90  * WSAEventSelect to signal events when a SOCKET is readable).
91  *
92  * On Win32, fd can also be the special value G_WIN32_MSG_HANDLE to
93  * indicate polling for messages. These message queue GPollFDs should
94  * be added with the g_main_poll_win32_msg_add function.
95  *
96  * But note that G_WIN32_MSG_HANDLE GPollFDs should not be used by GDK
97  * (GTK) programs, as GDK itself wants to read messages and convert them
98  * to GDK events.
99  *
100  * So, unless you really know what you are doing, it's best not to try
101  * to use the main loop polling stuff for your own needs on
102  * Win32. It's really only written for the GIMP's needs so
103  * far.
104  */
105 typedef struct _GPollFD GPollFD;
106 typedef gint    (*GPollFunc)    (GPollFD *ufds,
107                                  guint    nfsd,
108                                  gint     timeout);
109
110 struct _GPollFD
111 {
112   gint          fd;
113   gushort       events;
114   gushort       revents;
115 };
116
117 /* Standard priorities */
118
119 #define G_PRIORITY_HIGH            -100
120 #define G_PRIORITY_DEFAULT          0
121 #define G_PRIORITY_HIGH_IDLE        100
122 #define G_PRIORITY_DEFAULT_IDLE     200
123 #define G_PRIORITY_LOW              300
124
125 /* GMainContext: */
126
127 GMainContext *g_main_context_get       (GThread      *thread);
128 GMainContext *g_main_context_default   (void);
129
130 gboolean      g_main_context_iteration (GMainContext *context,
131                                         gboolean      may_block);
132 gboolean      g_main_context_pending   (GMainContext *context);
133
134 /* For implementation of legacy interfaces
135  */
136 GSource      *g_main_context_find_source_by_id              (GMainContext *context,
137                                                              guint         id);
138 GSource      *g_main_context_find_source_by_user_data       (GMainContext *context,
139                                                              gpointer      user_data);
140 GSource      *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
141                                                              GSourceFuncs *funcs,
142                                                              gpointer      user_data);
143
144 /* Low level functions for implementing custom main loops.
145  */
146 gboolean g_main_context_prepare  (GMainContext *context,
147                                   gint         *priority);
148 gint     g_main_context_query    (GMainContext *context,
149                                   gint          max_priority,
150                                   gint         *timeout,
151                                   GPollFD      *fds,
152                                   gint          n_fds);
153 gint     g_main_context_check    (GMainContext *context,
154                                   gint          max_priority,
155                                   GPollFD      *fds,
156                                   gint          n_fds);
157 void     g_main_context_dispatch (GMainContext *context);
158
159 void      g_main_context_set_poll_func (GMainContext *context,
160                                         GPollFunc     func);
161 GPollFunc g_main_context_get_poll_func (GMainContext *context);
162
163 /* Low level functions for use by source implementations
164  */
165 void g_main_context_add_poll      (GMainContext *context,
166                                    GPollFD      *fd,
167                                    gint          priority);
168 void g_main_context_remove_poll   (GMainContext *context,
169                                    GPollFD      *fd);
170
171 /* GMainLoop: */
172
173 GMainLoop *g_main_loop_new        (GMainContext *context,
174                                    gboolean      is_running);
175 void       g_main_loop_run        (GMainLoop    *loop);
176 void       g_main_loop_quit       (GMainLoop    *loop);
177 GMainLoop *g_main_loop_ref        (GMainLoop    *loop);
178 void       g_main_loop_unref      (GMainLoop    *loop);
179 gboolean   g_main_loop_is_running (GMainLoop    *loop);
180
181 /* GSource: */
182
183 GSource *g_source_new             (GSourceFuncs   *source_funcs,
184                                    guint           struct_size);
185 GSource *g_source_ref             (GSource        *source);
186 void     g_source_unref           (GSource        *source);
187
188 guint    g_source_attach          (GSource        *source,
189                                    GMainContext   *context);
190 void     g_source_destroy         (GSource        *source);
191
192 void     g_source_set_priority    (GSource        *source,
193                                    gint            priority);
194 gint     g_source_get_priority    (GSource        *source);
195 void     g_source_set_can_recurse (GSource        *source,
196                                    gboolean        can_recurse);
197 gboolean g_source_get_can_recurse (GSource        *source);
198 guint    g_source_get_id          (GSource        *source);
199
200 GMainContext *g_source_get_context (GSource       *source);
201
202 void g_source_set_callback          (GSource              *source,
203                                      GSourceFunc           func,
204                                      gpointer              data,
205                                      GDestroyNotify        notify);
206
207
208 /* Used to implement g_source_connect_closure and internally*/
209 void g_source_set_callback_indirect (GSource              *source,
210                                      gpointer              callback_data,
211                                      GSourceCallbackFuncs *callback_funcs);
212
213 void     g_source_add_poll         (GSource        *source,
214                                     GPollFD        *fd);
215 void     g_source_remove_poll      (GSource        *source,
216                                     GPollFD        *fd);
217
218 void     g_source_get_current_time (GSource        *source,
219                                     GTimeVal       *timeval);
220
221  /* void g_source_connect_closure (GSource        *source,
222                                   GClosure       *closure);
223  */
224
225 /* Specific source types
226  */
227 GSource *g_idle_source_new    (void);
228 GSource *g_timeout_source_new (guint         interval);
229
230 /* Miscellaneous functions
231  */
232 void g_get_current_time                 (GTimeVal       *result);
233
234 /* ============== Compat main loop stuff ================== */
235
236 #ifndef G_DISABLE_DEPRECATED
237
238 /* Legacy names for GMainLoop functions
239  */
240 #define         g_main_new(is_running)  g_main_loop_new (NULL, is_running);
241 #define         g_main_run(loop)        g_main_loop_run(loop)
242 #define         g_main_quit(loop)       g_main_loop_quit(loop)
243 #define         g_main_destroy(loop)    g_main_loop_unref(loop)
244 #define         g_main_is_running(loop) g_main_loop_is_running(loop)
245
246 /* Functions to manipulate the default main loop
247  */
248
249 #define g_main_iteration(may_block) g_main_context_iteration      (NULL, may_block)
250 #define g_main_pending()            g_main_context_pending        (NULL)
251
252 #define g_main_set_poll_func(func)   g_main_context_set_poll_func (NULL, func)
253
254 #endif /* G_DISABLE_DEPRECATED */
255
256 /* Source manipulation by ID */
257 gboolean g_source_remove                     (guint          tag);
258 gboolean g_source_remove_by_user_data        (gpointer       user_data);
259 gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
260                                               gpointer       user_data);
261
262 /* Idles and timeouts */
263 guint           g_timeout_add_full      (gint           priority,
264                                          guint          interval, 
265                                          GSourceFunc    function,
266                                          gpointer       data,
267                                          GDestroyNotify notify);
268 guint           g_timeout_add           (guint          interval,
269                                          GSourceFunc    function,
270                                          gpointer       data);
271 guint           g_idle_add              (GSourceFunc    function,
272                                          gpointer       data);
273 guint           g_idle_add_full         (gint           priority,
274                                          GSourceFunc    function,
275                                          gpointer       data,
276                                          GDestroyNotify notify);
277 gboolean        g_idle_remove_by_data   (gpointer       data);
278
279 #ifdef G_OS_WIN32
280
281 /* This is used to add polling for Windows messages. GDK (GTK+) programs
282  * should *not* use this.
283  */
284 void        g_main_poll_win32_msg_add (gint        priority,
285                                        GPollFD    *fd,
286                                        guint       hwnd);
287 #endif /* G_OS_WIN32 */
288
289 G_END_DECLS
290
291 #endif /* __G_MAIN_H__ */