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 (__GLIB_H_INSIDE__) && !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/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  * @closure_callback:
  92  * @closure_marshal:
  93  *
  94  * The <structname>GSourceFuncs</structname> struct contains a table of
  95  * functions used to handle event sources in a generic manner.
  96  *
  97  * For idle sources, the prepare and check functions always return %TRUE
  98  * to indicate that the source is always ready to be processed. The prepare
  99  * function also returns a timeout value of 0 to ensure that the poll() call
 100  * doesn't block (since that would be time wasted which could have been spent
 101  * running the idle function).
 102  *
 103  * For timeout sources, the prepare and check functions both return %TRUE
 104  * if the timeout interval has expired. The prepare function also returns
 105  * a timeout value to ensure that the poll() call doesn't block too long
 106  * and miss the next timeout.
 107  *
 108  * For file descriptor sources, the prepare function typically returns %FALSE,
 109  * since it must wait until poll() has been called before it knows whether
 110  * any events need to be processed. It sets the returned timeout to -1 to
 111  * indicate that it doesn't mind how long the poll() call blocks. In the
 112  * check function, it tests the results of the poll() call to see if the
 113  * required condition has been met, and returns %TRUE if so.
 114  */
 115 typedef struct _GSourceFuncs            GSourceFuncs;
 116
 117 /**
 118  * GPid:
 119  *
 120  * A type which is used to hold a process identification.
 121  *
 122  * On UNIX, processes are identified by a process id (an integer),
 123  * while Windows uses process handles (which are pointers).
 124  */
 125
 126 typedef gboolean (*GSourceFunc)       (gpointer data);
 127
 128 /**
 129  * GChildWatchFunc:
 130  * @pid: the process id of the child process
 131  * @status: Status information about the child process,
 132  *     see waitpid(2) for more information about this field
 133  * @data: user data passed to g_child_watch_add()
 134  *
 135  * The type of functions to be called when a child exists.
 136  */
 137 typedef void     (*GChildWatchFunc)   (GPid     pid,
 138                                        gint     status,
 139                                        gpointer data);
 140 struct _GSource
 141 {
 142   /*< private >*/
 143   gpointer callback_data;
 144   GSourceCallbackFuncs *callback_funcs;
 145
 146   GSourceFuncs *source_funcs;
 147   guint ref_count;
 148
 149   GMainContext *context;
 150
 151   gint priority;
 152   guint flags;
 153   guint source_id;
 154
 155   GSList *poll_fds;
 156
 157   GSource *prev;
 158   GSource *next;
 159
 160   char    *name;
 161
 162   GSourcePrivate *priv;
 163 };
 164
 165 struct _GSourceCallbackFuncs
 166 {
 167   void (*ref)   (gpointer     cb_data);
 168   void (*unref) (gpointer     cb_data);
 169   void (*get)   (gpointer     cb_data,
 170                  GSource     *source,
 171                  GSourceFunc *func,
 172                  gpointer    *data);
 173 };
 174
 175 typedef void (*GSourceDummyMarshal) (void);
 176
 177 struct _GSourceFuncs
 178 {
 179   gboolean (*prepare)  (GSource    *source,
 180                         gint       *timeout_);
 181   gboolean (*check)    (GSource    *source);
 182   gboolean (*dispatch) (GSource    *source,
 183                         GSourceFunc callback,
 184                         gpointer    user_data);
 185   void     (*finalize) (GSource    *source); /* Can be NULL */
 186
 187   /* For use by g_source_set_closure */
 188   GSourceFunc     closure_callback;
 189   GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
 190 };
 191
 192 /* Standard priorities */
 193
 194 /**
 195  * G_PRIORITY_HIGH:
 196  *
 197  * Use this for high priority event sources.
 198  *
 199  * It is not used within GLib or GTK+.
 200  */
 201 #define G_PRIORITY_HIGH            -100
 202
 203 /**
 204  * G_PRIORITY_DEFAULT:
 205  *
 206  * Use this for default priority event sources.
 207  *
 208  * In GLib this priority is used when adding timeout functions
 209  * with g_timeout_add(). In GDK this priority is used for events
 210  * from the X server.
 211  */
 212 #define G_PRIORITY_DEFAULT          0
 213
 214 /**
 215  * G_PRIORITY_HIGH_IDLE:
 216  *
 217  * Use this for high priority idle functions.
 218  *
 219  * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
 220  * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
 221  * done to ensure that any pending resizes are processed before any
 222  * pending redraws, so that widgets are not redrawn twice unnecessarily.)
 223  */
 224 #define G_PRIORITY_HIGH_IDLE        100
 225
 226 /**
 227  * G_PRIORITY_DEFAULT_IDLE:
 228  *
 229  * Use this for default priority idle functions.
 230  *
 231  * In GLib this priority is used when adding idle functions with
 232  * g_idle_add().
 233  */
 234 #define G_PRIORITY_DEFAULT_IDLE     200
 235
 236 /**
 237  * G_PRIORITY_LOW:
 238  *
 239  * Use this for very low priority background tasks.
 240  *
 241  * It is not used within GLib or GTK+.
 242  */
 243 #define G_PRIORITY_LOW              300
 244
 245 /* GMainContext: */
 246
 247 GMainContext *g_main_context_new       (void);
 248 GMainContext *g_main_context_ref       (GMainContext *context);
 249 void          g_main_context_unref     (GMainContext *context);
 250 GMainContext *g_main_context_default   (void);
 251
 252 gboolean      g_main_context_iteration (GMainContext *context,
 253                                         gboolean      may_block);
 254 gboolean      g_main_context_pending   (GMainContext *context);
 255
 256 /* For implementation of legacy interfaces
 257  */
 258 GSource      *g_main_context_find_source_by_id              (GMainContext *context,
 259                                                              guint         source_id);
 260 GSource      *g_main_context_find_source_by_user_data       (GMainContext *context,
 261                                                              gpointer      user_data);
 262 GSource      *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
 263                                                              GSourceFuncs *funcs,
 264                                                              gpointer      user_data);
 265
 266 /* Low level functions for implementing custom main loops.
 267  */
 268 void     g_main_context_wakeup  (GMainContext *context);
 269 gboolean g_main_context_acquire (GMainContext *context);
 270 void     g_main_context_release (GMainContext *context);
 271 gboolean g_main_context_is_owner (GMainContext *context);
 272 gboolean g_main_context_wait    (GMainContext *context,
 273                                  GCond        *cond,
 274                                  GMutex       *mutex);
 275
 276 gboolean g_main_context_prepare  (GMainContext *context,
 277                                   gint         *priority);
 278 gint     g_main_context_query    (GMainContext *context,
 279                                   gint          max_priority,
 280                                   gint         *timeout_,
 281                                   GPollFD      *fds,
 282                                   gint          n_fds);
 283 gint     g_main_context_check    (GMainContext *context,
 284                                   gint          max_priority,
 285                                   GPollFD      *fds,
 286                                   gint          n_fds);
 287 void     g_main_context_dispatch (GMainContext *context);
 288
 289 void     g_main_context_set_poll_func (GMainContext *context,
 290                                        GPollFunc     func);
 291 GPollFunc g_main_context_get_poll_func (GMainContext *context);
 292
 293 /* Low level functions for use by source implementations
 294  */
 295 void     g_main_context_add_poll    (GMainContext *context,
 296                                      GPollFD      *fd,
 297                                      gint          priority);
 298 void     g_main_context_remove_poll (GMainContext *context,
 299                                      GPollFD      *fd);
 300
 301 gint     g_main_depth               (void);
 302 GSource *g_main_current_source      (void);
 303
 304 /* GMainContexts for other threads
 305  */
 306 void          g_main_context_push_thread_default (GMainContext *context);
 307 void          g_main_context_pop_thread_default  (GMainContext *context);
 308 GMainContext *g_main_context_get_thread_default  (void);
 309
 310 /* GMainLoop: */
 311
 312 GMainLoop *g_main_loop_new        (GMainContext *context,
 313                                    gboolean      is_running);
 314 void       g_main_loop_run        (GMainLoop    *loop);
 315 void       g_main_loop_quit       (GMainLoop    *loop);
 316 GMainLoop *g_main_loop_ref        (GMainLoop    *loop);
 317 void       g_main_loop_unref      (GMainLoop    *loop);
 318 gboolean   g_main_loop_is_running (GMainLoop    *loop);
 319 GMainContext *g_main_loop_get_context (GMainLoop    *loop);
 320
 321 /* GSource: */
 322
 323 GSource *g_source_new             (GSourceFuncs   *source_funcs,
 324                                    guint           struct_size);
 325 GSource *g_source_ref             (GSource        *source);
 326 void     g_source_unref           (GSource        *source);
 327
 328 guint    g_source_attach          (GSource        *source,
 329                                    GMainContext   *context);
 330 void     g_source_destroy         (GSource        *source);
 331
 332 void     g_source_set_priority    (GSource        *source,
 333                                    gint            priority);
 334 gint     g_source_get_priority    (GSource        *source);
 335 void     g_source_set_can_recurse (GSource        *source,
 336                                    gboolean        can_recurse);
 337 gboolean g_source_get_can_recurse (GSource        *source);
 338 guint    g_source_get_id          (GSource        *source);
 339
 340 GMainContext *g_source_get_context (GSource       *source);
 341
 342 void     g_source_set_callback    (GSource        *source,
 343                                    GSourceFunc     func,
 344                                    gpointer        data,
 345                                    GDestroyNotify  notify);
 346
 347 void     g_source_set_funcs       (GSource        *source,
 348                                    GSourceFuncs   *funcs);
 349 gboolean g_source_is_destroyed    (GSource        *source);
 350
 351 void                 g_source_set_name       (GSource        *source,
 352                                               const char     *name);
 353 G_CONST_RETURN char* g_source_get_name       (GSource        *source);
 354 void                 g_source_set_name_by_id (guint           tag,
 355                                               const char     *name);
 356
 357
 358 /* Used to implement g_source_connect_closure and internally*/
 359 void g_source_set_callback_indirect (GSource              *source,
 360                                      gpointer              callback_data,
 361                                      GSourceCallbackFuncs *callback_funcs);
 362
 363 void     g_source_add_poll            (GSource        *source,
 364                                        GPollFD        *fd);
 365 void     g_source_remove_poll         (GSource        *source,
 366                                        GPollFD        *fd);
 367
 368 void     g_source_add_child_source    (GSource        *source,
 369                                        GSource        *child_source);
 370 void     g_source_remove_child_source (GSource        *source,
 371                                        GSource        *child_source);
 372
 373 #ifndef G_DISABLE_DEPRECATED
 374 void     g_source_get_current_time (GSource        *source,
 375                                     GTimeVal       *timeval);
 376 #endif
 377 gint64   g_source_get_time         (GSource        *source);
 378
 379  /* void g_source_connect_closure (GSource        *source,
 380                                   GClosure       *closure);
 381  */
 382
 383 /* Specific source types
 384  */
 385 GSource *g_idle_source_new        (void);
 386 GSource *g_child_watch_source_new (GPid pid);
 387 GSource *g_timeout_source_new     (guint interval);
 388 GSource *g_timeout_source_new_seconds (guint interval);
 389
 390 /* Miscellaneous functions
 391  */
 392 void   g_get_current_time                 (GTimeVal       *result);
 393 gint64 g_get_monotonic_time               (void);
 394 gint64 g_get_real_time                    (void);
 395
 396 /* ============== Compat main loop stuff ================== */
 397
 398 #ifndef G_DISABLE_DEPRECATED
 399
 400 /**
 401  * g_main_new:
 402  * @is_running: set to %TRUE to indicate that the loop is running. This
 403  *     is not very important since calling g_main_run() will set this
 404  *     to %TRUE anyway.
 405  *
 406  * Creates a new #GMainLoop for th default main context.
 407  *
 408  * Returns: a new #GMainLoop
 409  *
 410  * Deprecated: 2.2: Use g_main_loop_new() instead
 411  */
 412 #define         g_main_new(is_running)  g_main_loop_new (NULL, is_running)
 413
 414 /**
 415  * g_main_run:
 416  * @loop: a #GMainLoop
 417  *
 418  * Runs a main loop until it stops running.
 419  *
 420  * Deprecated: 2.2: Use g_main_loop_run() instead
 421  */
 422 #define         g_main_run(loop)        g_main_loop_run(loop)
 423
 424 /**
 425  * g_main_quit:
 426  * @loop: a #GMainLoop
 427  *
 428  * Stops the #GMainLoop.
 429  * If g_main_run() was called to run the #GMainLoop, it will now return.
 430  *
 431  * Deprecated: 2.2: Use g_main_loop_quit() instead
 432  */
 433 #define g_main_quit(loop)       g_main_loop_quit(loop)
 434
 435 /**
 436  * g_main_destroy:
 437  * @loop: a #GMainLoop
 438  *
 439  * Frees the memory allocated for the #GMainLoop.
 440  *
 441  * Deprecated: 2.2: Use g_main_loop_unref() instead
 442  */
 443 #define g_main_destroy(loop)    g_main_loop_unref(loop)
 444
 445 /**
 446  * g_main_is_running:
 447  * @loop: a #GMainLoop
 448  *
 449  * Checks if the main loop is running.
 450  *
 451  * Returns: %TRUE if the main loop is running
 452  *
 453  * Deprecated: 2.2: Use g_main_loop_is_running() instead
 454  */
 455 #define g_main_is_running(loop) g_main_loop_is_running(loop)
 456
 457 /**
 458  * g_main_iteration:
 459  * @may_block: set to %TRUE if it should block (i.e. wait) until an event
 460  *     source becomes ready. It will return after an event source has been
 461  *     processed. If set to %FALSE it will return immediately if no event
 462  *     source is ready to be processed.
 463  *
 464  * Runs a single iteration for the default #GMainContext.
 465  *
 466  * Returns: %TRUE if more events are pending.
 467  *
 468  * Deprecated: 2.2: Use g_main_context_iteration() instead.
 469  */
 470 #define g_main_iteration(may_block) g_main_context_iteration (NULL, may_block)
 471
 472 /**
 473  * g_main_pending:
 474  *
 475  * Checks if any events are pending for the default #GMainContext
 476  * (i.e. ready to be processed).
 477  *
 478  * Returns: %TRUE if any events are pending.
 479  *
 480  * Deprected: 2.2: Use g_main_context_pending() instead.
 481  */
 482 #define g_main_pending()            g_main_context_pending (NULL)
 483
 484 /**
 485  * g_main_set_poll_func:
 486  * @func: the function to call to poll all file descriptors
 487  *
 488  * Sets the function to use for the handle polling of file descriptors
 489  * for the default main context.
 490  *
 491  * Deprecated: 2.2: Use g_main_context_set_poll_func() again
 492  */
 493 #define g_main_set_poll_func(func)  g_main_context_set_poll_func (NULL, func)
 494
 495 #endif /* G_DISABLE_DEPRECATED */
 496
 497 /* Source manipulation by ID */
 498 gboolean g_source_remove                     (guint          tag);
 499 gboolean g_source_remove_by_user_data        (gpointer       user_data);
 500 gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
 501                                               gpointer       user_data);
 502
 503 /* Idles, child watchers and timeouts */
 504 guint    g_timeout_add_full         (gint            priority,
 505                                      guint           interval,
 506                                      GSourceFunc     function,
 507                                      gpointer        data,
 508                                      GDestroyNotify  notify);
 509 guint    g_timeout_add              (guint           interval,
 510                                      GSourceFunc     function,
 511                                      gpointer        data);
 512 guint    g_timeout_add_seconds_full (gint            priority,
 513                                      guint           interval,
 514                                      GSourceFunc     function,
 515                                      gpointer        data,
 516                                      GDestroyNotify  notify);
 517 guint    g_timeout_add_seconds      (guint           interval,
 518                                      GSourceFunc     function,
 519                                      gpointer        data);
 520 guint    g_child_watch_add_full     (gint            priority,
 521                                      GPid            pid,
 522                                      GChildWatchFunc function,
 523                                      gpointer        data,
 524                                      GDestroyNotify  notify);
 525 guint    g_child_watch_add          (GPid            pid,
 526                                      GChildWatchFunc function,
 527                                      gpointer        data);
 528 guint    g_idle_add                 (GSourceFunc     function,
 529                                      gpointer        data);
 530 guint    g_idle_add_full            (gint            priority,
 531                                      GSourceFunc     function,
 532                                      gpointer        data,
 533                                      GDestroyNotify  notify);
 534 gboolean g_idle_remove_by_data      (gpointer        data);
 535
 536 void     g_main_context_invoke_full (GMainContext   *context,
 537                                      gint            priority,
 538                                      GSourceFunc     function,
 539                                      gpointer        data,
 540                                      GDestroyNotify  notify);
 541 void     g_main_context_invoke      (GMainContext   *context,
 542                                      GSourceFunc     function,
 543                                      gpointer        data);
 544
 545 /* Hook for GClosure / GSource integration. Don't touch */
 546 GLIB_VAR GSourceFuncs g_timeout_funcs;
 547 GLIB_VAR GSourceFuncs g_child_watch_funcs;
 548 GLIB_VAR GSourceFuncs g_idle_funcs;
 549
 550 G_END_DECLS
 551
 552 #endif /* __G_MAIN_H__ */