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