Improve docs
[platform/upstream/glib.git] / glib / gmain.h
index 5a224bc..3f0e9cd 100644 (file)
  * Boston, MA 02111-1307, USA.
  */
 
+#if defined(G_DISABLE_SINGLE_INCLUDES) && !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
+#error "Only <glib.h> can be included directly."
+#endif
+
 #ifndef __G_MAIN_H__
 #define __G_MAIN_H__
 
+#include <glib/gpoll.h>
 #include <glib/gslist.h>
 #include <glib/gthread.h>
 
@@ -32,7 +37,9 @@ typedef struct _GSourceCallbackFuncs  GSourceCallbackFuncs;
 typedef struct _GSourceFuncs           GSourceFuncs;
 
 typedef gboolean (*GSourceFunc)       (gpointer data);
-
+typedef void     (*GChildWatchFunc)   (GPid     pid,
+                                      gint     status,
+                                      gpointer data);
 struct _GSource
 {
   /*< private >*/
@@ -84,45 +91,6 @@ struct _GSourceFuncs
   GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
 };
 
-/* Any definitions using GPollFD or GPollFunc are primarily
- * for Unix and not guaranteed to be the compatible on all
- * operating systems on which GLib runs. Right now, the
- * GLib does use these functions on Win32 as well, but interprets
- * them in a fairly different way than on Unix. If you use
- * these definitions, you are should be prepared to recode
- * for different operating systems.
- *
- *
- * On Win32, the fd in a GPollFD should be Win32 HANDLE (*not* a file
- * descriptor as provided by the C runtime) that can be used by
- * MsgWaitForMultipleObjects. This does *not* include file handles
- * from CreateFile, SOCKETs, nor pipe handles. (But you can use
- * WSAEventSelect to signal events when a SOCKET is readable).
- *
- * On Win32, fd can also be the special value G_WIN32_MSG_HANDLE to
- * indicate polling for messages.
- *
- * But note that G_WIN32_MSG_HANDLE GPollFDs should not be used by GDK
- * (GTK) programs, as GDK itself wants to read messages and convert them
- * to GDK events.
- *
- * So, unless you really know what you are doing, it's best not to try
- * to use the main loop polling stuff for your own needs on
- * Win32. It's really only written for the GIMP's needs so
- * far.
- */
-typedef struct _GPollFD GPollFD;
-typedef gint   (*GPollFunc)    (GPollFD *ufds,
-                                guint    nfsd,
-                                gint     timeout_);
-
-struct _GPollFD
-{
-  gint         fd;
-  gushort      events;
-  gushort      revents;
-};
-
 /* Standard priorities */
 
 #define G_PRIORITY_HIGH            -100
@@ -134,7 +102,7 @@ struct _GPollFD
 /* GMainContext: */
 
 GMainContext *g_main_context_new       (void);
-void          g_main_context_ref       (GMainContext *context);
+GMainContext *g_main_context_ref       (GMainContext *context);
 void          g_main_context_unref     (GMainContext *context);
 GMainContext *g_main_context_default   (void);
 
@@ -157,6 +125,7 @@ GSource      *g_main_context_find_source_by_funcs_user_data (GMainContext *conte
 void     g_main_context_wakeup  (GMainContext *context);
 gboolean g_main_context_acquire (GMainContext *context);
 void     g_main_context_release (GMainContext *context);
+gboolean g_main_context_is_owner (GMainContext *context);
 gboolean g_main_context_wait    (GMainContext *context,
                                 GCond        *cond,
                                 GMutex       *mutex);
@@ -174,17 +143,21 @@ gint     g_main_context_check    (GMainContext *context,
                                  gint          n_fds);
 void     g_main_context_dispatch (GMainContext *context);
 
-void      g_main_context_set_poll_func (GMainContext *context,
-                                       GPollFunc     func);
+void     g_main_context_set_poll_func (GMainContext *context,
+                                      GPollFunc     func);
 GPollFunc g_main_context_get_poll_func (GMainContext *context);
 
 /* Low level functions for use by source implementations
  */
-void g_main_context_add_poll      (GMainContext *context,
-                                  GPollFD      *fd,
-                                  gint          priority);
-void g_main_context_remove_poll   (GMainContext *context,
-                                  GPollFD      *fd);
+void     g_main_context_add_poll    (GMainContext *context,
+                                    GPollFD      *fd,
+                                    gint          priority);
+void     g_main_context_remove_poll (GMainContext *context,
+                                    GPollFD      *fd);
+
+gint     g_main_depth               (void);
+GSource *g_main_current_source      (void);
+
 
 /* GMainLoop: */
 
@@ -218,11 +191,14 @@ guint    g_source_get_id          (GSource        *source);
 
 GMainContext *g_source_get_context (GSource       *source);
 
-void g_source_set_callback          (GSource              *source,
-                                    GSourceFunc           func,
-                                    gpointer              data,
-                                    GDestroyNotify        notify);
+void     g_source_set_callback    (GSource        *source,
+                                  GSourceFunc     func,
+                                  gpointer        data,
+                                  GDestroyNotify  notify);
 
+void     g_source_set_funcs       (GSource        *source,
+                                   GSourceFuncs   *funcs);
+gboolean g_source_is_destroyed    (GSource        *source);
 
 /* Used to implement g_source_connect_closure and internally*/
 void g_source_set_callback_indirect (GSource              *source,
@@ -243,8 +219,10 @@ void     g_source_get_current_time (GSource        *source,
 
 /* Specific source types
  */
-GSource *g_idle_source_new    (void);
-GSource *g_timeout_source_new (guint         interval);
+GSource *g_idle_source_new        (void);
+GSource *g_child_watch_source_new (GPid pid);
+GSource *g_timeout_source_new     (guint interval);
+GSource *g_timeout_source_new_seconds (guint interval);
 
 /* Miscellaneous functions
  */
@@ -278,25 +256,42 @@ gboolean g_source_remove_by_user_data        (gpointer       user_data);
 gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
                                              gpointer       user_data);
 
-/* Idles and timeouts */
-guint          g_timeout_add_full      (gint           priority,
-                                        guint          interval, 
-                                        GSourceFunc    function,
-                                        gpointer       data,
-                                        GDestroyNotify notify);
-guint          g_timeout_add           (guint          interval,
-                                        GSourceFunc    function,
-                                        gpointer       data);
-guint          g_idle_add              (GSourceFunc    function,
-                                        gpointer       data);
-guint          g_idle_add_full         (gint           priority,
-                                        GSourceFunc    function,
-                                        gpointer       data,
-                                        GDestroyNotify notify);
-gboolean       g_idle_remove_by_data   (gpointer       data);
+/* Idles, child watchers and timeouts */
+guint    g_timeout_add_full         (gint            priority,
+                                    guint           interval,
+                                    GSourceFunc     function,
+                                    gpointer        data,
+                                    GDestroyNotify  notify);
+guint    g_timeout_add              (guint           interval,
+                                    GSourceFunc     function,
+                                    gpointer        data);
+guint    g_timeout_add_seconds_full (gint            priority,
+                                     guint           interval,
+                                     GSourceFunc     function,
+                                     gpointer        data,
+                                     GDestroyNotify  notify);
+guint    g_timeout_add_seconds      (guint           interval,
+                                    GSourceFunc     function,
+                                    gpointer        data);
+guint    g_child_watch_add_full     (gint            priority,
+                                    GPid            pid,
+                                    GChildWatchFunc function,
+                                    gpointer        data,
+                                    GDestroyNotify  notify);
+guint    g_child_watch_add          (GPid            pid,
+                                    GChildWatchFunc function,
+                                    gpointer        data);
+guint    g_idle_add                 (GSourceFunc     function,
+                                    gpointer        data);
+guint    g_idle_add_full            (gint            priority,
+                                    GSourceFunc     function,
+                                    gpointer        data,
+                                    GDestroyNotify  notify);
+gboolean g_idle_remove_by_data      (gpointer        data);
 
 /* Hook for GClosure / GSource integration. Don't touch */
 GLIB_VAR GSourceFuncs g_timeout_funcs;
+GLIB_VAR GSourceFuncs g_child_watch_funcs;
 GLIB_VAR GSourceFuncs g_idle_funcs;
 
 G_END_DECLS