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 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  24 #error "Only <glib.h> can be included directly."
  25 #endif
  26
  27 #include <glib/gpoll.h>
  28 #include <glib/gslist.h>
  29 #include <glib/gthread.h>
  30
  31 G_BEGIN_DECLS
  32
  33 /**
  34  * GMainContext:
  35  *
  36  * The <structname>GMainContext</structname> struct is an opaque data
  37  * type representing a set of sources to be handled in a main loop.
  38  */
  39 typedef struct _GMainContext            GMainContext;
  40
  41 /**
  42  * GMainLoop:
  43  *
  44  * The <structname>GMainLoop</structname> struct is an opaque data type
  45  * representing the main event loop of a GLib or GTK+ application.
  46  */
  47 typedef struct _GMainLoop               GMainLoop;
  48
  49 /**
  50  * GSource:
  51  *
  52  * The <structname>GSource</structname> struct is an opaque data type
  53  * representing an event source.
  54  */
  55 typedef struct _GSource                 GSource;
  56 typedef struct _GSourcePrivate          GSourcePrivate;
  57
  58 /**
  59  * GSourceCallbackFuncs:
  60  * @ref: Called when a reference is added to the callback object
  61  * @unref: Called when a reference to the callback object is dropped
  62  * @get: Called to extract the callback function and data from the
  63  *     callback object.
  64
  65  * The <structname>GSourceCallbackFuncs</structname> struct contains
  66  * functions for managing callback objects.
  67  */
  68 typedef struct _GSourceCallbackFuncs    GSourceCallbackFuncs;
  69
  70 /**
  71  * GSourceFuncs:
  72  * @prepare: Called before all the file descriptors are polled. If the
  73  *     source can determine that it is ready here (without waiting for the
  74  *     results of the poll() call) it should return %TRUE. It can also return
  75  *     a @timeout_ value which should be the maximum timeout (in milliseconds)
  76  *     which should be passed to the poll() call. The actual timeout used will
  77  *     be -1 if all sources returned -1, or it will be the minimum of all the
  78  *     @timeout_ values returned which were >= 0.
  79  * @check: Called after all the file descriptors are polled. The source
  80  *     should return %TRUE if it is ready to be dispatched. Note that some
  81  *     time may have passed since the previous prepare function was called,
  82  *     so the source should be checked again here.
  83  * @dispatch: Called to dispatch the event source, after it has returned
  84  *     %TRUE in either its @prepare or its @check function. The @dispatch
  85  *     function is passed in a callback function and data. The callback
  86  *     function may be %NULL if the source was never connected to a callback
  87  *     using g_source_set_callback(). The @dispatch function should call the
  88  *     callback function with @user_data and whatever additional parameters
  89  *     are needed for this type of event source.
  90  * @finalize: Called when the source is finalized.
  91  *
  92  * The <structname>GSourceFuncs</structname> struct contains a table of
  93  * functions used to handle event sources in a generic manner.
  94  *
  95  * For idle sources, the prepare and check functions always return %TRUE
  96  * to indicate that the source is always ready to be processed. The prepare
  97  * function also returns a timeout value of 0 to ensure that the poll() call
  98  * doesn't block (since that would be time wasted which could have been spent
  99  * running the idle function).
 100  *
 101  * For timeout sources, the prepare and check functions both return %TRUE
 102  * if the timeout interval has expired. The prepare function also returns
 103  * a timeout value to ensure that the poll() call doesn't block too long
 104  * and miss the next timeout.
 105  *
 106  * For file descriptor sources, the prepare function typically returns %FALSE,
 107  * since it must wait until poll() has been called before it knows whether
 108  * any events need to be processed. It sets the returned timeout to -1 to
 109  * indicate that it doesn't mind how long the poll() call blocks. In the
 110  * check function, it tests the results of the poll() call to see if the
 111  * required condition has been met, and returns %TRUE if so.
 112  */
 113 typedef struct _GSourceFuncs            GSourceFuncs;
 114
 115 /**
 116  * GPid:
 117  *
 118  * A type which is used to hold a process identification.
 119  *
 120  * On UNIX, processes are identified by a process id (an integer),
 121  * while Windows uses process handles (which are pointers).
 122  *
 123  * GPid is used in GLib only for descendant processes spawned with
 124  * the g_spawn functions.
 125  */
 126
 127 /**
 128  * GSourceFunc:
 129  * @user_data: data passed to the function, set when the source was
 130  *     created with one of the above functions
 131  *
 132  * Specifies the type of function passed to g_timeout_add(),
 133  * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
 134  *
 135  * Returns: %FALSE if the source should be removed
 136  */
 137 typedef gboolean (*GSourceFunc)       (gpointer user_data);
 138
 139 /**
 140  * GChildWatchFunc:
 141  * @pid: the process id of the child process
 142  * @status: Status information about the child process, encoded
 143  *     in a platform-specific manner
 144  * @user_data: user data passed to g_child_watch_add()
 145  *
 146  * Prototype of a #GChildWatchSource callback, called when a child
 147  * process has exited.  To interpret @status, see the documentation
 148  * for g_spawn_check_exit_status().
 149  */
 150 typedef void     (*GChildWatchFunc)   (GPid     pid,
 151                                        gint     status,
 152                                        gpointer user_data);
 153 struct _GSource
 154 {
 155   /*< private >*/
 156   gpointer callback_data;
 157   GSourceCallbackFuncs *callback_funcs;
 158
 159   GSourceFuncs *source_funcs;
 160   guint ref_count;
 161
 162   GMainContext *context;
 163
 164   gint priority;
 165   guint flags;
 166   guint source_id;
 167
 168   GSList *poll_fds;
 169
 170   GSource *prev;
 171   GSource *next;
 172
 173   char    *name;
 174
 175   GSourcePrivate *priv;
 176 };
 177
 178 struct _GSourceCallbackFuncs
 179 {
 180   void (*ref)   (gpointer     cb_data);
 181   void (*unref) (gpointer     cb_data);
 182   void (*get)   (gpointer     cb_data,
 183                  GSource     *source,
 184                  GSourceFunc *func,
 185                  gpointer    *data);
 186 };
 187
 188 /**
 189  * GSourceDummyMarshal:
 190  *
 191  * This is just a placeholder for #GClosureMarshal,
 192  * which cannot be used here for dependency reasons.
 193  */
 194 typedef void (*GSourceDummyMarshal) (void);
 195
 196 struct _GSourceFuncs
 197 {
 198   gboolean (*prepare)  (GSource    *source,
 199                         gint       *timeout_);
 200   gboolean (*check)    (GSource    *source);
 201   gboolean (*dispatch) (GSource    *source,
 202                         GSourceFunc callback,
 203                         gpointer    user_data);
 204   void     (*finalize) (GSource    *source); /* Can be NULL */
 205
 206   /*< private >*/
 207   /* For use by g_source_set_closure */
 208   GSourceFunc     closure_callback;
 209   GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
 210 };
 211
 212 /* Standard priorities */
 213
 214 /**
 215  * G_PRIORITY_HIGH:
 216  *
 217  * Use this for high priority event sources.
 218  *
 219  * It is not used within GLib or GTK+.
 220  */
 221 #define G_PRIORITY_HIGH            -100
 222
 223 /**
 224  * G_PRIORITY_DEFAULT:
 225  *
 226  * Use this for default priority event sources.
 227  *
 228  * In GLib this priority is used when adding timeout functions
 229  * with g_timeout_add(). In GDK this priority is used for events
 230  * from the X server.
 231  */
 232 #define G_PRIORITY_DEFAULT          0
 233
 234 /**
 235  * G_PRIORITY_HIGH_IDLE:
 236  *
 237  * Use this for high priority idle functions.
 238  *
 239  * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
 240  * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
 241  * done to ensure that any pending resizes are processed before any
 242  * pending redraws, so that widgets are not redrawn twice unnecessarily.)
 243  */
 244 #define G_PRIORITY_HIGH_IDLE        100
 245
 246 /**
 247  * G_PRIORITY_DEFAULT_IDLE:
 248  *
 249  * Use this for default priority idle functions.
 250  *
 251  * In GLib this priority is used when adding idle functions with
 252  * g_idle_add().
 253  */
 254 #define G_PRIORITY_DEFAULT_IDLE     200
 255
 256 /**
 257  * G_PRIORITY_LOW:
 258  *
 259  * Use this for very low priority background tasks.
 260  *
 261  * It is not used within GLib or GTK+.
 262  */
 263 #define G_PRIORITY_LOW              300
 264
 265 /**
 266  * G_SOURCE_REMOVE:
 267  *
 268  * Use this macro as the return value of a #GSourceFunc to remove
 269  * the #GSource from the main loop.
 270  *
 271  * Since: 2.32
 272  */
 273 #define G_SOURCE_REMOVE         FALSE
 274
 275 /**
 276  * G_SOURCE_CONTINUE:
 277  *
 278  * Use this macro as the return value of a #GSourceFunc to leave
 279  * the #GSource in the main loop.
 280  *
 281  * Since: 2.32
 282  */
 283 #define G_SOURCE_CONTINUE       TRUE
 284
 285 /* GMainContext: */
 286
 287 GMainContext *g_main_context_new       (void);
 288 GMainContext *g_main_context_ref       (GMainContext *context);
 289 void          g_main_context_unref     (GMainContext *context);
 290 GMainContext *g_main_context_default   (void);
 291
 292 gboolean      g_main_context_iteration (GMainContext *context,
 293                                         gboolean      may_block);
 294 gboolean      g_main_context_pending   (GMainContext *context);
 295
 296 /* For implementation of legacy interfaces
 297  */
 298 GSource      *g_main_context_find_source_by_id              (GMainContext *context,
 299                                                              guint         source_id);
 300 GSource      *g_main_context_find_source_by_user_data       (GMainContext *context,
 301                                                              gpointer      user_data);
 302 GSource      *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
 303                                                              GSourceFuncs *funcs,
 304                                                              gpointer      user_data);
 305
 306 /* Low level functions for implementing custom main loops.
 307  */
 308 void     g_main_context_wakeup  (GMainContext *context);
 309 gboolean g_main_context_acquire (GMainContext *context);
 310 void     g_main_context_release (GMainContext *context);
 311 gboolean g_main_context_is_owner (GMainContext *context);
 312 gboolean g_main_context_wait    (GMainContext *context,
 313                                  GCond        *cond,
 314                                  GMutex       *mutex);
 315
 316 gboolean g_main_context_prepare  (GMainContext *context,
 317                                   gint         *priority);
 318 gint     g_main_context_query    (GMainContext *context,
 319                                   gint          max_priority,
 320                                   gint         *timeout_,
 321                                   GPollFD      *fds,
 322                                   gint          n_fds);
 323 gint     g_main_context_check    (GMainContext *context,
 324                                   gint          max_priority,
 325                                   GPollFD      *fds,
 326                                   gint          n_fds);
 327 void     g_main_context_dispatch (GMainContext *context);
 328
 329 void     g_main_context_set_poll_func (GMainContext *context,
 330                                        GPollFunc     func);
 331 GPollFunc g_main_context_get_poll_func (GMainContext *context);
 332
 333 /* Low level functions for use by source implementations
 334  */
 335 void     g_main_context_add_poll    (GMainContext *context,
 336                                      GPollFD      *fd,
 337                                      gint          priority);
 338 void     g_main_context_remove_poll (GMainContext *context,
 339                                      GPollFD      *fd);
 340
 341 gint     g_main_depth               (void);
 342 GSource *g_main_current_source      (void);
 343
 344 /* GMainContexts for other threads
 345  */
 346 void          g_main_context_push_thread_default (GMainContext *context);
 347 void          g_main_context_pop_thread_default  (GMainContext *context);
 348 GMainContext *g_main_context_get_thread_default  (void);
 349 GMainContext *g_main_context_ref_thread_default  (void);
 350
 351 /* GMainLoop: */
 352
 353 GMainLoop *g_main_loop_new        (GMainContext *context,
 354                                    gboolean      is_running);
 355 void       g_main_loop_run        (GMainLoop    *loop);
 356 void       g_main_loop_quit       (GMainLoop    *loop);
 357 GMainLoop *g_main_loop_ref        (GMainLoop    *loop);
 358 void       g_main_loop_unref      (GMainLoop    *loop);
 359 gboolean   g_main_loop_is_running (GMainLoop    *loop);
 360 GMainContext *g_main_loop_get_context (GMainLoop    *loop);
 361
 362 /* GSource: */
 363
 364 GSource *g_source_new             (GSourceFuncs   *source_funcs,
 365                                    guint           struct_size);
 366 GSource *g_source_ref             (GSource        *source);
 367 void     g_source_unref           (GSource        *source);
 368
 369 guint    g_source_attach          (GSource        *source,
 370                                    GMainContext   *context);
 371 void     g_source_destroy         (GSource        *source);
 372
 373 void     g_source_set_priority    (GSource        *source,
 374                                    gint            priority);
 375 gint     g_source_get_priority    (GSource        *source);
 376 void     g_source_set_can_recurse (GSource        *source,
 377                                    gboolean        can_recurse);
 378 gboolean g_source_get_can_recurse (GSource        *source);
 379 guint    g_source_get_id          (GSource        *source);
 380
 381 GMainContext *g_source_get_context (GSource       *source);
 382
 383 void     g_source_set_callback    (GSource        *source,
 384                                    GSourceFunc     func,
 385                                    gpointer        data,
 386                                    GDestroyNotify  notify);
 387
 388 void     g_source_set_funcs       (GSource        *source,
 389                                    GSourceFuncs   *funcs);
 390 gboolean g_source_is_destroyed    (GSource        *source);
 391
 392 void                 g_source_set_name       (GSource        *source,
 393                                               const char     *name);
 394 const char *         g_source_get_name       (GSource        *source);
 395 void                 g_source_set_name_by_id (guint           tag,
 396                                               const char     *name);
 397
 398
 399 /* Used to implement g_source_connect_closure and internally*/
 400 void g_source_set_callback_indirect (GSource              *source,
 401                                      gpointer              callback_data,
 402                                      GSourceCallbackFuncs *callback_funcs);
 403
 404 void     g_source_add_poll            (GSource        *source,
 405                                        GPollFD        *fd);
 406 void     g_source_remove_poll         (GSource        *source,
 407                                        GPollFD        *fd);
 408
 409 void     g_source_add_child_source    (GSource        *source,
 410                                        GSource        *child_source);
 411 void     g_source_remove_child_source (GSource        *source,
 412                                        GSource        *child_source);
 413
 414 GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time)
 415 void     g_source_get_current_time (GSource        *source,
 416                                     GTimeVal       *timeval);
 417
 418 gint64   g_source_get_time         (GSource        *source);
 419
 420  /* void g_source_connect_closure (GSource        *source,
 421                                   GClosure       *closure);
 422  */
 423
 424 /* Specific source types
 425  */
 426 GSource *g_idle_source_new        (void);
 427 GSource *g_child_watch_source_new (GPid pid);
 428 GSource *g_timeout_source_new     (guint interval);
 429 GSource *g_timeout_source_new_seconds (guint interval);
 430
 431 /* Miscellaneous functions
 432  */
 433 void   g_get_current_time                 (GTimeVal       *result);
 434 gint64 g_get_monotonic_time               (void);
 435 gint64 g_get_real_time                    (void);
 436
 437
 438 /* Source manipulation by ID */
 439 gboolean g_source_remove                     (guint          tag);
 440 gboolean g_source_remove_by_user_data        (gpointer       user_data);
 441 gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
 442                                               gpointer       user_data);
 443
 444 /* Idles, child watchers and timeouts */
 445 guint    g_timeout_add_full         (gint            priority,
 446                                      guint           interval,
 447                                      GSourceFunc     function,
 448                                      gpointer        data,
 449                                      GDestroyNotify  notify);
 450 guint    g_timeout_add              (guint           interval,
 451                                      GSourceFunc     function,
 452                                      gpointer        data);
 453 guint    g_timeout_add_seconds_full (gint            priority,
 454                                      guint           interval,
 455                                      GSourceFunc     function,
 456                                      gpointer        data,
 457                                      GDestroyNotify  notify);
 458 guint    g_timeout_add_seconds      (guint           interval,
 459                                      GSourceFunc     function,
 460                                      gpointer        data);
 461 guint    g_child_watch_add_full     (gint            priority,
 462                                      GPid            pid,
 463                                      GChildWatchFunc function,
 464                                      gpointer        data,
 465                                      GDestroyNotify  notify);
 466 guint    g_child_watch_add          (GPid            pid,
 467                                      GChildWatchFunc function,
 468                                      gpointer        data);
 469 guint    g_idle_add                 (GSourceFunc     function,
 470                                      gpointer        data);
 471 guint    g_idle_add_full            (gint            priority,
 472                                      GSourceFunc     function,
 473                                      gpointer        data,
 474                                      GDestroyNotify  notify);
 475 gboolean g_idle_remove_by_data      (gpointer        data);
 476
 477 void     g_main_context_invoke_full (GMainContext   *context,
 478                                      gint            priority,
 479                                      GSourceFunc     function,
 480                                      gpointer        data,
 481                                      GDestroyNotify  notify);
 482 void     g_main_context_invoke      (GMainContext   *context,
 483                                      GSourceFunc     function,
 484                                      gpointer        data);
 485
 486 /* Hook for GClosure / GSource integration. Don't touch */
 487 GLIB_VAR GSourceFuncs g_timeout_funcs;
 488 GLIB_VAR GSourceFuncs g_child_watch_funcs;
 489 GLIB_VAR GSourceFuncs g_idle_funcs;
 490
 491 G_END_DECLS
 492
 493 #endif /* __G_MAIN_H__ */