gmain.h 10.9 KB
Newer Older
1 2
/* gmain.h - the GLib Main loop
 * 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 7 8 9 10 11
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * 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 16 17 18 19 20 21 22
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#ifndef __G_MAIN_H__
#define __G_MAIN_H__

23 24
#include <glib/gslist.h>
#include <glib/gthread.h>
25 26 27

G_BEGIN_DECLS

28 29 30 31 32
typedef struct _GMainContext	        GMainContext;	/* Opaque */
typedef struct _GMainLoop	        GMainLoop;	/* Opaque */
typedef struct _GSource	                GSource;
typedef struct _GSourceCallbackFuncs	GSourceCallbackFuncs;
typedef struct _GSourceFuncs	        GSourceFuncs;
33

34
typedef gboolean (*GSourceFunc)       (gpointer data);
35 36 37
typedef void     (*GChildWatchFunc)   (GPid     pid,
				       gint     status,
				       gpointer data);
38 39 40 41 42
struct _GSource
{
  /*< private >*/
  gpointer callback_data;
  GSourceCallbackFuncs *callback_funcs;
43

44 45
  GSourceFuncs *source_funcs;
  guint ref_count;
46

47
  GMainContext *context;
48

49 50
  gint priority;
  guint flags;
51
  guint source_id;
52

53 54 55 56
  GSList *poll_fds;
  
  GSource *prev;
  GSource *next;
Owen Taylor's avatar
Owen Taylor committed
57 58 59

  gpointer reserved1;
  gpointer reserved2;
60
};
61

62 63 64 65 66
struct _GSourceCallbackFuncs
{
  void (*ref)   (gpointer     cb_data);
  void (*unref) (gpointer     cb_data);
  void (*get)   (gpointer     cb_data,
67
		 GSource     *source, 
68 69 70
		 GSourceFunc *func,
		 gpointer    *data);
};
71

72 73
typedef void (*GSourceDummyMarshal) (void);

74 75 76
struct _GSourceFuncs
{
  gboolean (*prepare)  (GSource    *source,
77
			gint       *timeout_);
78 79 80 81
  gboolean (*check)    (GSource    *source);
  gboolean (*dispatch) (GSource    *source,
			GSourceFunc callback,
			gpointer    user_data);
82
  void     (*finalize) (GSource    *source); /* Can be NULL */
83 84 85 86

  /* For use by g_source_set_closure */
  GSourceFunc     closure_callback;	   
  GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
87
};
88

89 90 91 92 93 94 95
/* Any definitions using GPollFD or GPollFunc are primarily
 * for Unix and not guaranteed to be the compatible on all
 * operating systems on which GLib runs. Right now, the
 * GLib does use these functions on Win32 as well, but interprets
 * them in a fairly different way than on Unix. If you use
 * these definitions, you are should be prepared to recode
 * for different operating systems.
96 97 98 99 100 101 102 103 104
 *
 *
 * On Win32, the fd in a GPollFD should be Win32 HANDLE (*not* a file
 * descriptor as provided by the C runtime) that can be used by
 * MsgWaitForMultipleObjects. This does *not* include file handles
 * from CreateFile, SOCKETs, nor pipe handles. (But you can use
 * WSAEventSelect to signal events when a SOCKET is readable).
 *
 * On Win32, fd can also be the special value G_WIN32_MSG_HANDLE to
105
 * indicate polling for messages.
106 107 108 109 110 111 112 113 114 115 116
 *
 * But note that G_WIN32_MSG_HANDLE GPollFDs should not be used by GDK
 * (GTK) programs, as GDK itself wants to read messages and convert them
 * to GDK events.
 *
 * So, unless you really know what you are doing, it's best not to try
 * to use the main loop polling stuff for your own needs on
 * Win32. It's really only written for the GIMP's needs so
 * far.
 */
typedef struct _GPollFD GPollFD;
117 118
typedef gint	(*GPollFunc)	(GPollFD *ufds,
				 guint	  nfsd,
119
				 gint     timeout_);
120

121 122
struct _GPollFD
{
123 124 125
  gint		fd;
  gushort 	events;
  gushort 	revents;
126 127
};

128
/* Standard priorities */
129

130 131 132 133 134 135 136
#define G_PRIORITY_HIGH            -100
#define G_PRIORITY_DEFAULT          0
#define G_PRIORITY_HIGH_IDLE        100
#define G_PRIORITY_DEFAULT_IDLE     200
#define G_PRIORITY_LOW	            300

/* GMainContext: */
137

138
GMainContext *g_main_context_new       (void);
139
GMainContext *g_main_context_ref       (GMainContext *context);
140
void          g_main_context_unref     (GMainContext *context);
141
GMainContext *g_main_context_default   (void);
142

143 144 145 146 147 148 149
gboolean      g_main_context_iteration (GMainContext *context,
					gboolean      may_block);
gboolean      g_main_context_pending   (GMainContext *context);

/* For implementation of legacy interfaces
 */
GSource      *g_main_context_find_source_by_id              (GMainContext *context,
150
							     guint         source_id);
151 152 153 154 155 156 157 158
GSource      *g_main_context_find_source_by_user_data       (GMainContext *context,
							     gpointer      user_data);
GSource      *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
 							     GSourceFuncs *funcs,
							     gpointer      user_data);

/* Low level functions for implementing custom main loops.
 */
159 160 161
void     g_main_context_wakeup  (GMainContext *context);
gboolean g_main_context_acquire (GMainContext *context);
void     g_main_context_release (GMainContext *context);
Matthias Clasen's avatar
Matthias Clasen committed
162
gboolean g_main_context_is_owner (GMainContext *context);
163 164 165 166
gboolean g_main_context_wait    (GMainContext *context,
				 GCond        *cond,
				 GMutex       *mutex);

167 168 169 170
gboolean g_main_context_prepare  (GMainContext *context,
				  gint         *priority);
gint     g_main_context_query    (GMainContext *context,
				  gint          max_priority,
171
				  gint         *timeout_,
172 173 174 175 176 177 178
				  GPollFD      *fds,
				  gint          n_fds);
gint     g_main_context_check    (GMainContext *context,
				  gint          max_priority,
				  GPollFD      *fds,
				  gint          n_fds);
void     g_main_context_dispatch (GMainContext *context);
179

180 181
void     g_main_context_set_poll_func (GMainContext *context,
				       GPollFunc     func);
182 183 184 185
GPollFunc g_main_context_get_poll_func (GMainContext *context);

/* Low level functions for use by source implementations
 */
186 187 188 189 190 191 192 193
void     g_main_context_add_poll    (GMainContext *context,
				     GPollFD      *fd,
				     gint          priority);
void     g_main_context_remove_poll (GMainContext *context,
				     GPollFD      *fd);

gint     g_main_depth               (void);
GSource *g_main_current_source      (void);
194

195

196 197 198 199 200 201
/* GMainLoop: */

GMainLoop *g_main_loop_new        (GMainContext *context,
			    	   gboolean      is_running);
void       g_main_loop_run        (GMainLoop    *loop);
void       g_main_loop_quit       (GMainLoop    *loop);
202 203
GMainLoop *g_main_loop_ref        (GMainLoop    *loop);
void       g_main_loop_unref      (GMainLoop    *loop);
204
gboolean   g_main_loop_is_running (GMainLoop    *loop);
205
GMainContext *g_main_loop_get_context (GMainLoop    *loop);
206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227

/* GSource: */

GSource *g_source_new             (GSourceFuncs   *source_funcs,
				   guint           struct_size);
GSource *g_source_ref             (GSource        *source);
void     g_source_unref           (GSource        *source);

guint    g_source_attach          (GSource        *source,
				   GMainContext   *context);
void     g_source_destroy         (GSource        *source);

void     g_source_set_priority    (GSource        *source,
				   gint            priority);
gint     g_source_get_priority    (GSource        *source);
void     g_source_set_can_recurse (GSource        *source,
				   gboolean        can_recurse);
gboolean g_source_get_can_recurse (GSource        *source);
guint    g_source_get_id          (GSource        *source);

GMainContext *g_source_get_context (GSource       *source);

228 229 230 231
void     g_source_set_callback    (GSource        *source,
				   GSourceFunc     func,
				   gpointer        data,
				   GDestroyNotify  notify);
232

233 234 235
void     g_source_set_funcs       (GSource        *source,
                                   GSourceFuncs   *funcs);
gboolean g_source_is_destroyed    (GSource        *source);
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255

/* Used to implement g_source_connect_closure and internally*/
void g_source_set_callback_indirect (GSource              *source,
				     gpointer              callback_data,
				     GSourceCallbackFuncs *callback_funcs);

void     g_source_add_poll         (GSource        *source,
				    GPollFD        *fd);
void     g_source_remove_poll      (GSource        *source,
				    GPollFD        *fd);

void     g_source_get_current_time (GSource        *source,
				    GTimeVal       *timeval);

 /* void g_source_connect_closure (GSource        *source,
                                  GClosure       *closure);
 */

/* Specific source types
 */
256 257 258
GSource *g_idle_source_new        (void);
GSource *g_child_watch_source_new (GPid pid);
GSource *g_timeout_source_new     (guint interval);
259
GSource *g_timeout_source_new_seconds (guint interval);
260 261 262 263 264 265 266

/* Miscellaneous functions
 */
void g_get_current_time		        (GTimeVal	*result);

/* ============== Compat main loop stuff ================== */

Owen Taylor's avatar
Owen Taylor committed
267 268
#ifndef G_DISABLE_DEPRECATED

269 270 271 272 273
/* Legacy names for GMainLoop functions
 */
#define 	g_main_new(is_running)	g_main_loop_new (NULL, is_running);
#define         g_main_run(loop)        g_main_loop_run(loop)
#define         g_main_quit(loop)       g_main_loop_quit(loop)
274
#define         g_main_destroy(loop)    g_main_loop_unref(loop)
275 276 277 278 279 280 281 282 283 284
#define         g_main_is_running(loop) g_main_loop_is_running(loop)

/* Functions to manipulate the default main loop
 */

#define	g_main_iteration(may_block) g_main_context_iteration      (NULL, may_block)
#define g_main_pending()            g_main_context_pending        (NULL)

#define g_main_set_poll_func(func)   g_main_context_set_poll_func (NULL, func)

Owen Taylor's avatar
Owen Taylor committed
285 286 287 288 289 290 291 292
#endif /* G_DISABLE_DEPRECATED */

/* Source manipulation by ID */
gboolean g_source_remove                     (guint          tag);
gboolean g_source_remove_by_user_data        (gpointer       user_data);
gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
					      gpointer       user_data);

293 294 295 296 297 298 299 300 301
/* Idles, child watchers and timeouts */
guint    g_timeout_add_full     (gint            priority,
				 guint           interval,
				 GSourceFunc     function,
				 gpointer        data,
				 GDestroyNotify  notify);
guint    g_timeout_add          (guint           interval,
				 GSourceFunc     function,
				 gpointer        data);
302 303 304
guint    g_timeout_add_seconds  (guint           interval,
				 GSourceFunc     function,
				 gpointer        data);
305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
guint    g_child_watch_add_full (gint            priority,
				 GPid            pid,
				 GChildWatchFunc function,
				 gpointer        data,
				 GDestroyNotify  notify);
guint    g_child_watch_add      (GPid            pid,
				 GChildWatchFunc function,
				 gpointer        data);
guint    g_idle_add             (GSourceFunc     function,
				 gpointer        data);
guint    g_idle_add_full        (gint            priority,
				 GSourceFunc     function,
				 gpointer        data,
				 GDestroyNotify  notify);
gboolean g_idle_remove_by_data  (gpointer        data);
320

321 322
/* Hook for GClosure / GSource integration. Don't touch */
GLIB_VAR GSourceFuncs g_timeout_funcs;
323
GLIB_VAR GSourceFuncs g_child_watch_funcs;
324 325
GLIB_VAR GSourceFuncs g_idle_funcs;

326 327 328
G_END_DECLS

#endif /* __G_MAIN_H__ */