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 <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);
  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 void       g_main_loop_destroy    (GMainLoop    *loop);
 178 gboolean   g_main_loop_is_running (GMainLoop    *loop);
 179
 180 /* GSource: */
 181
 182 GSource *g_source_new             (GSourceFuncs   *source_funcs,
 183                                    guint           struct_size);
 184 GSource *g_source_ref             (GSource        *source);
 185 void     g_source_unref           (GSource        *source);
 186
 187 guint    g_source_attach          (GSource        *source,
 188                                    GMainContext   *context);
 189 void     g_source_destroy         (GSource        *source);
 190
 191 void     g_source_set_priority    (GSource        *source,
 192                                    gint            priority);
 193 gint     g_source_get_priority    (GSource        *source);
 194 void     g_source_set_can_recurse (GSource        *source,
 195                                    gboolean        can_recurse);
 196 gboolean g_source_get_can_recurse (GSource        *source);
 197 guint    g_source_get_id          (GSource        *source);
 198
 199 GMainContext *g_source_get_context (GSource       *source);
 200
 201 void g_source_set_callback          (GSource              *source,
 202                                      GSourceFunc           func,
 203                                      gpointer              data,
 204                                      GDestroyNotify        notify);
 205
 206
 207 /* Used to implement g_source_connect_closure and internally*/
 208 void g_source_set_callback_indirect (GSource              *source,
 209                                      gpointer              callback_data,
 210                                      GSourceCallbackFuncs *callback_funcs);
 211
 212 void     g_source_add_poll         (GSource        *source,
 213                                     GPollFD        *fd);
 214 void     g_source_remove_poll      (GSource        *source,
 215                                     GPollFD        *fd);
 216
 217 void     g_source_get_current_time (GSource        *source,
 218                                     GTimeVal       *timeval);
 219
 220  /* void g_source_connect_closure (GSource        *source,
 221                                   GClosure       *closure);
 222  */
 223
 224 /* Specific source types
 225  */
 226 GSource *g_idle_source_new    (void);
 227 GSource *g_timeout_source_new (guint         interval);
 228
 229 /* Miscellaneous functions
 230  */
 231 void g_get_current_time                 (GTimeVal       *result);
 232
 233 /* ============== Compat main loop stuff ================== */
 234
 235 /* Legacy names for GMainLoop functions
 236  */
 237 #define         g_main_new(is_running)  g_main_loop_new (NULL, is_running);
 238 #define         g_main_run(loop)        g_main_loop_run(loop)
 239 #define         g_main_quit(loop)       g_main_loop_quit(loop)
 240 #define         g_main_destroy(loop)    g_main_loop_destroy(loop)
 241 #define         g_main_is_running(loop) g_main_loop_is_running(loop)
 242
 243 /* Source manipulation by ID */
 244 gboolean g_source_remove                     (guint          tag);
 245 gboolean g_source_remove_by_user_data        (gpointer       user_data);
 246 gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
 247                                               gpointer       user_data);
 248
 249 /* Functions to manipulate the default main loop
 250  */
 251
 252 #define g_main_iteration(may_block) g_main_context_iteration      (NULL, may_block)
 253 #define g_main_pending()            g_main_context_pending        (NULL)
 254
 255 #define g_main_set_poll_func(func)   g_main_context_set_poll_func (NULL, func)
 256
 257 /* Idles and timeouts */
 258 guint           g_timeout_add_full      (gint           priority,
 259                                          guint          interval,
 260                                          GSourceFunc    function,
 261                                          gpointer       data,
 262                                          GDestroyNotify notify);
 263 guint           g_timeout_add           (guint          interval,
 264                                          GSourceFunc    function,
 265                                          gpointer       data);
 266 guint           g_idle_add              (GSourceFunc    function,
 267                                          gpointer       data);
 268 guint           g_idle_add_full         (gint           priority,
 269                                          GSourceFunc    function,
 270                                          gpointer       data,
 271                                          GDestroyNotify notify);
 272 gboolean        g_idle_remove_by_data   (gpointer       data);
 273
 274 #ifdef G_OS_WIN32
 275
 276 /* This is used to add polling for Windows messages. GDK (GTK+) programs
 277  * should *not* use this.
 278  */
 279 void        g_main_poll_win32_msg_add (gint        priority,
 280                                        GPollFD    *fd,
 281                                        guint       hwnd);
 282 #endif G_OS_WIN32
 283
 284 G_END_DECLS
 285
 286 #endif /* __G_MAIN_H__ */