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, 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 <glib/gslist.h>
  24 #include <glib/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 typedef void     (*GChildWatchFunc)   (GPid     pid,
  36                                        gint     status,
  37                                        gpointer data);
  38 struct _GSource
  39 {
  40   /*< private >*/
  41   gpointer callback_data;
  42   GSourceCallbackFuncs *callback_funcs;
  43
  44   GSourceFuncs *source_funcs;
  45   guint ref_count;
  46
  47   GMainContext *context;
  48
  49   gint priority;
  50   guint flags;
  51   guint source_id;
  52
  53   GSList *poll_fds;
  54
  55   GSource *prev;
  56   GSource *next;
  57
  58   gpointer reserved1;
  59   gpointer reserved2;
  60 };
  61
  62 struct _GSourceCallbackFuncs
  63 {
  64   void (*ref)   (gpointer     cb_data);
  65   void (*unref) (gpointer     cb_data);
  66   void (*get)   (gpointer     cb_data,
  67                  GSource     *source,
  68                  GSourceFunc *func,
  69                  gpointer    *data);
  70 };
  71
  72 typedef void (*GSourceDummyMarshal) (void);
  73
  74 struct _GSourceFuncs
  75 {
  76   gboolean (*prepare)  (GSource    *source,
  77                         gint       *timeout_);
  78   gboolean (*check)    (GSource    *source);
  79   gboolean (*dispatch) (GSource    *source,
  80                         GSourceFunc callback,
  81                         gpointer    user_data);
  82   void     (*finalize) (GSource    *source); /* Can be NULL */
  83
  84   /* For use by g_source_set_closure */
  85   GSourceFunc     closure_callback;
  86   GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
  87 };
  88
  89 /* Any definitions using GPollFD or GPollFunc are primarily
  90  * for Unix and not guaranteed to be the compatible on all
  91  * operating systems on which GLib runs. Right now, the
  92  * GLib does use these functions on Win32 as well, but interprets
  93  * them in a fairly different way than on Unix. If you use
  94  * these definitions, you are should be prepared to recode
  95  * for different operating systems.
  96  *
  97  *
  98  * On Win32, the fd in a GPollFD should be Win32 HANDLE (*not* a file
  99  * descriptor as provided by the C runtime) that can be used by
 100  * MsgWaitForMultipleObjects. This does *not* include file handles
 101  * from CreateFile, SOCKETs, nor pipe handles. (But you can use
 102  * WSAEventSelect to signal events when a SOCKET is readable).
 103  *
 104  * On Win32, fd can also be the special value G_WIN32_MSG_HANDLE to
 105  * indicate polling for messages.
 106  *
 107  * But note that G_WIN32_MSG_HANDLE GPollFDs should not be used by GDK
 108  * (GTK) programs, as GDK itself wants to read messages and convert them
 109  * to GDK events.
 110  *
 111  * So, unless you really know what you are doing, it's best not to try
 112  * to use the main loop polling stuff for your own needs on
 113  * Win32. It's really only written for the GIMP's needs so
 114  * far.
 115  */
 116 typedef struct _GPollFD GPollFD;
 117 typedef gint    (*GPollFunc)    (GPollFD *ufds,
 118                                  guint    nfsd,
 119                                  gint     timeout_);
 120
 121 struct _GPollFD
 122 {
 123   gint          fd;
 124   gushort       events;
 125   gushort       revents;
 126 };
 127
 128 /* Standard priorities */
 129
 130 #define G_PRIORITY_HIGH            -100
 131 #define G_PRIORITY_DEFAULT          0
 132 #define G_PRIORITY_HIGH_IDLE        100
 133 #define G_PRIORITY_DEFAULT_IDLE     200
 134 #define G_PRIORITY_LOW              300
 135
 136 /* 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 gboolean      g_main_context_iteration (GMainContext *context,
 144                                         gboolean      may_block);
 145 gboolean      g_main_context_pending   (GMainContext *context);
 146
 147 /* For implementation of legacy interfaces
 148  */
 149 GSource      *g_main_context_find_source_by_id              (GMainContext *context,
 150                                                              guint         source_id);
 151 GSource      *g_main_context_find_source_by_user_data       (GMainContext *context,
 152                                                              gpointer      user_data);
 153 GSource      *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
 154                                                              GSourceFuncs *funcs,
 155                                                              gpointer      user_data);
 156
 157 /* Low level functions for implementing custom main loops.
 158  */
 159 void     g_main_context_wakeup  (GMainContext *context);
 160 gboolean g_main_context_acquire (GMainContext *context);
 161 void     g_main_context_release (GMainContext *context);
 162 gboolean g_main_context_is_owner (GMainContext *context);
 163 gboolean g_main_context_wait    (GMainContext *context,
 164                                  GCond        *cond,
 165                                  GMutex       *mutex);
 166
 167 gboolean g_main_context_prepare  (GMainContext *context,
 168                                   gint         *priority);
 169 gint     g_main_context_query    (GMainContext *context,
 170                                   gint          max_priority,
 171                                   gint         *timeout_,
 172                                   GPollFD      *fds,
 173                                   gint          n_fds);
 174 gint     g_main_context_check    (GMainContext *context,
 175                                   gint          max_priority,
 176                                   GPollFD      *fds,
 177                                   gint          n_fds);
 178 void     g_main_context_dispatch (GMainContext *context);
 179
 180 void      g_main_context_set_poll_func (GMainContext *context,
 181                                         GPollFunc     func);
 182 GPollFunc g_main_context_get_poll_func (GMainContext *context);
 183
 184 /* Low level functions for use by source implementations
 185  */
 186 void g_main_context_add_poll      (GMainContext *context,
 187                                    GPollFD      *fd,
 188                                    gint          priority);
 189 void g_main_context_remove_poll   (GMainContext *context,
 190                                    GPollFD      *fd);
 191
 192 int g_main_depth (void);
 193
 194 /* GMainLoop: */
 195
 196 GMainLoop *g_main_loop_new        (GMainContext *context,
 197                                    gboolean      is_running);
 198 void       g_main_loop_run        (GMainLoop    *loop);
 199 void       g_main_loop_quit       (GMainLoop    *loop);
 200 GMainLoop *g_main_loop_ref        (GMainLoop    *loop);
 201 void       g_main_loop_unref      (GMainLoop    *loop);
 202 gboolean   g_main_loop_is_running (GMainLoop    *loop);
 203 GMainContext *g_main_loop_get_context (GMainLoop    *loop);
 204
 205 /* GSource: */
 206
 207 GSource *g_source_new             (GSourceFuncs   *source_funcs,
 208                                    guint           struct_size);
 209 GSource *g_source_ref             (GSource        *source);
 210 void     g_source_unref           (GSource        *source);
 211
 212 guint    g_source_attach          (GSource        *source,
 213                                    GMainContext   *context);
 214 void     g_source_destroy         (GSource        *source);
 215
 216 void     g_source_set_priority    (GSource        *source,
 217                                    gint            priority);
 218 gint     g_source_get_priority    (GSource        *source);
 219 void     g_source_set_can_recurse (GSource        *source,
 220                                    gboolean        can_recurse);
 221 gboolean g_source_get_can_recurse (GSource        *source);
 222 guint    g_source_get_id          (GSource        *source);
 223
 224 GMainContext *g_source_get_context (GSource       *source);
 225
 226 void g_source_set_callback          (GSource              *source,
 227                                      GSourceFunc           func,
 228                                      gpointer              data,
 229                                      GDestroyNotify        notify);
 230
 231
 232 /* Used to implement g_source_connect_closure and internally*/
 233 void g_source_set_callback_indirect (GSource              *source,
 234                                      gpointer              callback_data,
 235                                      GSourceCallbackFuncs *callback_funcs);
 236
 237 void     g_source_add_poll         (GSource        *source,
 238                                     GPollFD        *fd);
 239 void     g_source_remove_poll      (GSource        *source,
 240                                     GPollFD        *fd);
 241
 242 void     g_source_get_current_time (GSource        *source,
 243                                     GTimeVal       *timeval);
 244
 245  /* void g_source_connect_closure (GSource        *source,
 246                                   GClosure       *closure);
 247  */
 248
 249 /* Specific source types
 250  */
 251 GSource *g_idle_source_new        (void);
 252 GSource *g_child_watch_source_new (GPid pid);
 253 GSource *g_timeout_source_new     (guint interval);
 254
 255 /* Miscellaneous functions
 256  */
 257 void g_get_current_time                 (GTimeVal       *result);
 258
 259 /* ============== Compat main loop stuff ================== */
 260
 261 #ifndef G_DISABLE_DEPRECATED
 262
 263 /* Legacy names for GMainLoop functions
 264  */
 265 #define         g_main_new(is_running)  g_main_loop_new (NULL, is_running);
 266 #define         g_main_run(loop)        g_main_loop_run(loop)
 267 #define         g_main_quit(loop)       g_main_loop_quit(loop)
 268 #define         g_main_destroy(loop)    g_main_loop_unref(loop)
 269 #define         g_main_is_running(loop) g_main_loop_is_running(loop)
 270
 271 /* Functions to manipulate the default main loop
 272  */
 273
 274 #define g_main_iteration(may_block) g_main_context_iteration      (NULL, may_block)
 275 #define g_main_pending()            g_main_context_pending        (NULL)
 276
 277 #define g_main_set_poll_func(func)   g_main_context_set_poll_func (NULL, func)
 278
 279 #endif /* G_DISABLE_DEPRECATED */
 280
 281 /* Source manipulation by ID */
 282 gboolean g_source_remove                     (guint          tag);
 283 gboolean g_source_remove_by_user_data        (gpointer       user_data);
 284 gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
 285                                               gpointer       user_data);
 286
 287 /* Idles, child watchers and timeouts */
 288 guint    g_timeout_add_full     (gint            priority,
 289                                  guint           interval,
 290                                  GSourceFunc     function,
 291                                  gpointer        data,
 292                                  GDestroyNotify  notify);
 293 guint    g_timeout_add          (guint           interval,
 294                                  GSourceFunc     function,
 295                                  gpointer        data);
 296 guint    g_child_watch_add_full (gint            priority,
 297                                  GPid            pid,
 298                                  GChildWatchFunc function,
 299                                  gpointer        data,
 300                                  GDestroyNotify  notify);
 301 guint    g_child_watch_add      (GPid            pid,
 302                                  GChildWatchFunc function,
 303                                  gpointer        data);
 304 guint    g_idle_add             (GSourceFunc     function,
 305                                  gpointer        data);
 306 guint    g_idle_add_full        (gint            priority,
 307                                  GSourceFunc     function,
 308                                  gpointer        data,
 309                                  GDestroyNotify  notify);
 310 gboolean g_idle_remove_by_data  (gpointer        data);
 311
 312 /* Hook for GClosure / GSource integration. Don't touch */
 313 GLIB_VAR GSourceFuncs g_timeout_funcs;
 314 GLIB_VAR GSourceFuncs g_child_watch_funcs;
 315 GLIB_VAR GSourceFuncs g_idle_funcs;
 316
 317 G_END_DECLS
 318
 319 #endif /* __G_MAIN_H__ */