*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* Boston, MA 02111-1307, USA.
*/
+#if !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>
G_BEGIN_DECLS
-typedef struct _GMainContext GMainContext; /* Opaque */
-typedef struct _GMainLoop GMainLoop; /* Opaque */
-typedef struct _GSource GSource;
-typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs;
-typedef struct _GSourceFuncs GSourceFuncs;
+/**
+ * GMainContext:
+ *
+ * The <structname>GMainContext</structname> struct is an opaque data
+ * type representing a set of sources to be handled in a main loop.
+ */
+typedef struct _GMainContext GMainContext;
+
+/**
+ * GMainLoop:
+ *
+ * The <structname>GMainLoop</structname> struct is an opaque data type
+ * representing the main event loop of a GLib or GTK+ application.
+ */
+typedef struct _GMainLoop GMainLoop;
-typedef gboolean (*GSourceFunc) (gpointer data);
+/**
+ * GSource:
+ *
+ * The <structname>GSource</structname> struct is an opaque data type
+ * representing an event source.
+ */
+typedef struct _GSource GSource;
+typedef struct _GSourcePrivate GSourcePrivate;
+
+/**
+ * GSourceCallbackFuncs:
+ * @ref: Called when a reference is added to the callback object
+ * @unref: Called when a reference to the callback object is dropped
+ * @get: Called to extract the callback function and data from the
+ * callback object.
+
+ * The <structname>GSourceCallbackFuncs</structname> struct contains
+ * functions for managing callback objects.
+ */
+typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs;
+
+/**
+ * GSourceFuncs:
+ * @prepare: Called before all the file descriptors are polled. If the
+ * source can determine that it is ready here (without waiting for the
+ * results of the poll() call) it should return %TRUE. It can also return
+ * a @timeout_ value which should be the maximum timeout (in milliseconds)
+ * which should be passed to the poll() call. The actual timeout used will
+ * be -1 if all sources returned -1, or it will be the minimum of all the
+ * @timeout_ values returned which were >= 0.
+ * @check: Called after all the file descriptors are polled. The source
+ * should return %TRUE if it is ready to be dispatched. Note that some
+ * time may have passed since the previous prepare function was called,
+ * so the source should be checked again here.
+ * @dispatch: Called to dispatch the event source, after it has returned
+ * %TRUE in either its @prepare or its @check function. The @dispatch
+ * function is passed in a callback function and data. The callback
+ * function may be %NULL if the source was never connected to a callback
+ * using g_source_set_callback(). The @dispatch function should call the
+ * callback function with @user_data and whatever additional parameters
+ * are needed for this type of event source.
+ * @finalize: Called when the source is finalized.
+ * @closure_callback:
+ * @closure_marshal:
+ *
+ * The <structname>GSourceFuncs</structname> struct contains a table of
+ * functions used to handle event sources in a generic manner.
+ *
+ * For idle sources, the prepare and check functions always return %TRUE
+ * to indicate that the source is always ready to be processed. The prepare
+ * function also returns a timeout value of 0 to ensure that the poll() call
+ * doesn't block (since that would be time wasted which could have been spent
+ * running the idle function).
+ *
+ * For timeout sources, the prepare and check functions both return %TRUE
+ * if the timeout interval has expired. The prepare function also returns
+ * a timeout value to ensure that the poll() call doesn't block too long
+ * and miss the next timeout.
+ *
+ * For file descriptor sources, the prepare function typically returns %FALSE,
+ * since it must wait until poll() has been called before it knows whether
+ * any events need to be processed. It sets the returned timeout to -1 to
+ * indicate that it doesn't mind how long the poll() call blocks. In the
+ * check function, it tests the results of the poll() call to see if the
+ * required condition has been met, and returns %TRUE if so.
+ */
+typedef struct _GSourceFuncs GSourceFuncs;
+
+/**
+ * GPid:
+ *
+ * A type which is used to hold a process identification.
+ *
+ * On UNIX, processes are identified by a process id (an integer),
+ * while Windows uses process handles (which are pointers).
+ */
+
+/**
+ * GSourceFunc:
+ * @user_data: data passed to the function, set when the source was
+ * created with one of the above functions
+ *
+ * Specifies the type of function passed to g_timeout_add(),
+ * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
+ *
+ * Returns: %FALSE if the source should be removed
+ */
+typedef gboolean (*GSourceFunc) (gpointer user_data);
+
+/**
+ * GChildWatchFunc:
+ * @pid: the process id of the child process
+ * @status: Status information about the child process,
+ * see waitpid(2) for more information about this field
+ * @user_data: user data passed to g_child_watch_add()
+ *
+ * The type of functions to be called when a child exists.
+ */
typedef void (*GChildWatchFunc) (GPid pid,
- gint status,
- gpointer data);
+ gint status,
+ gpointer user_data);
struct _GSource
{
/*< private >*/
GSource *prev;
GSource *next;
- gpointer reserved1;
- gpointer reserved2;
+ char *name;
+
+ GSourcePrivate *priv;
};
struct _GSourceCallbackFuncs
void (*ref) (gpointer cb_data);
void (*unref) (gpointer cb_data);
void (*get) (gpointer cb_data,
- GSource *source,
- GSourceFunc *func,
- gpointer *data);
+ GSource *source,
+ GSourceFunc *func,
+ gpointer *data);
};
+/**
+ * GSourceDummyMarshal:
+ *
+ * This is just a placeholder for #GClosureMarshal,
+ * which cannot be used here for dependency reasons.
+ */
typedef void (*GSourceDummyMarshal) (void);
struct _GSourceFuncs
{
gboolean (*prepare) (GSource *source,
- gint *timeout_);
+ gint *timeout_);
gboolean (*check) (GSource *source);
gboolean (*dispatch) (GSource *source,
- GSourceFunc callback,
- gpointer user_data);
+ GSourceFunc callback,
+ gpointer user_data);
void (*finalize) (GSource *source); /* Can be NULL */
/* For use by g_source_set_closure */
- GSourceFunc closure_callback;
+ GSourceFunc closure_callback;
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.
+/* Standard priorities */
+
+/**
+ * G_PRIORITY_HIGH:
*
+ * Use this for high priority event sources.
*
- * 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).
+ * It is not used within GLib or GTK+.
+ */
+#define G_PRIORITY_HIGH -100
+
+/**
+ * G_PRIORITY_DEFAULT:
*
- * On Win32, fd can also be the special value G_WIN32_MSG_HANDLE to
- * indicate polling for messages.
+ * Use this for default priority event sources.
*
- * 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.
+ * In GLib this priority is used when adding timeout functions
+ * with g_timeout_add(). In GDK this priority is used for events
+ * from the X server.
+ */
+#define G_PRIORITY_DEFAULT 0
+
+/**
+ * G_PRIORITY_HIGH_IDLE:
*
- * 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.
+ * Use this for high priority idle functions.
+ *
+ * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
+ * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
+ * done to ensure that any pending resizes are processed before any
+ * pending redraws, so that widgets are not redrawn twice unnecessarily.)
*/
-typedef struct _GPollFD GPollFD;
-typedef gint (*GPollFunc) (GPollFD *ufds,
- guint nfsd,
- gint timeout_);
+#define G_PRIORITY_HIGH_IDLE 100
-struct _GPollFD
-{
- gint fd;
- gushort events;
- gushort revents;
-};
+/**
+ * G_PRIORITY_DEFAULT_IDLE:
+ *
+ * Use this for default priority idle functions.
+ *
+ * In GLib this priority is used when adding idle functions with
+ * g_idle_add().
+ */
+#define G_PRIORITY_DEFAULT_IDLE 200
-/* Standard priorities */
+/**
+ * G_PRIORITY_LOW:
+ *
+ * Use this for very low priority background tasks.
+ *
+ * It is not used within GLib or GTK+.
+ */
+#define G_PRIORITY_LOW 300
-#define G_PRIORITY_HIGH -100
-#define G_PRIORITY_DEFAULT 0
-#define G_PRIORITY_HIGH_IDLE 100
-#define G_PRIORITY_DEFAULT_IDLE 200
-#define G_PRIORITY_LOW 300
+/**
+ * G_SOURCE_REMOVE:
+ *
+ * Use this macro as the return value of a #GSourceFunc to remove
+ * the #GSource from the main loop.
+ *
+ * Since: 2.28
+ */
+#define G_SOURCE_REMOVE FALSE
+
+/**
+ * G_SOURCE_CONTINUE:
+ *
+ * Use this macro as the return value of a #GSourceFunc to leave
+ * the #GSource in the main loop.
+ *
+ * Since: 2.28
+ */
+#define G_SOURCE_CONTINUE TRUE
/* GMainContext: */
GMainContext *g_main_context_default (void);
gboolean g_main_context_iteration (GMainContext *context,
- gboolean may_block);
+ gboolean may_block);
gboolean g_main_context_pending (GMainContext *context);
/* For implementation of legacy interfaces
*/
GSource *g_main_context_find_source_by_id (GMainContext *context,
- guint source_id);
+ guint source_id);
GSource *g_main_context_find_source_by_user_data (GMainContext *context,
- gpointer user_data);
+ gpointer user_data);
GSource *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
- GSourceFuncs *funcs,
- gpointer user_data);
+ GSourceFuncs *funcs,
+ gpointer user_data);
/* Low level functions for implementing custom main loops.
*/
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);
+ GCond *cond,
+ GMutex *mutex);
gboolean g_main_context_prepare (GMainContext *context,
- gint *priority);
+ gint *priority);
gint g_main_context_query (GMainContext *context,
- gint max_priority,
- gint *timeout_,
- GPollFD *fds,
- gint n_fds);
+ gint max_priority,
+ gint *timeout_,
+ GPollFD *fds,
+ gint n_fds);
gint g_main_context_check (GMainContext *context,
- gint max_priority,
- GPollFD *fds,
- gint n_fds);
+ gint max_priority,
+ GPollFD *fds,
+ gint n_fds);
void g_main_context_dispatch (GMainContext *context);
void g_main_context_set_poll_func (GMainContext *context,
- GPollFunc func);
+ 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);
+ GPollFD *fd,
+ gint priority);
void g_main_context_remove_poll (GMainContext *context,
- GPollFD *fd);
+ GPollFD *fd);
gint g_main_depth (void);
GSource *g_main_current_source (void);
+/* GMainContexts for other threads
+ */
+void g_main_context_push_thread_default (GMainContext *context);
+void g_main_context_pop_thread_default (GMainContext *context);
+GMainContext *g_main_context_get_thread_default (void);
+GMainContext *g_main_context_ref_thread_default (void);
/* GMainLoop: */
GMainLoop *g_main_loop_new (GMainContext *context,
- gboolean is_running);
+ gboolean is_running);
void g_main_loop_run (GMainLoop *loop);
void g_main_loop_quit (GMainLoop *loop);
GMainLoop *g_main_loop_ref (GMainLoop *loop);
/* GSource: */
GSource *g_source_new (GSourceFuncs *source_funcs,
- guint struct_size);
+ guint struct_size);
GSource *g_source_ref (GSource *source);
void g_source_unref (GSource *source);
guint g_source_attach (GSource *source,
- GMainContext *context);
+ GMainContext *context);
void g_source_destroy (GSource *source);
void g_source_set_priority (GSource *source,
- gint priority);
+ gint priority);
gint g_source_get_priority (GSource *source);
void g_source_set_can_recurse (GSource *source,
- gboolean can_recurse);
+ gboolean can_recurse);
gboolean g_source_get_can_recurse (GSource *source);
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);
+ GSourceFunc func,
+ gpointer data,
+ GDestroyNotify notify);
void g_source_set_funcs (GSource *source,
GSourceFuncs *funcs);
gboolean g_source_is_destroyed (GSource *source);
+void g_source_set_name (GSource *source,
+ const char *name);
+const char * g_source_get_name (GSource *source);
+void g_source_set_name_by_id (guint tag,
+ const char *name);
+
+
/* Used to implement g_source_connect_closure and internally*/
void g_source_set_callback_indirect (GSource *source,
- gpointer callback_data,
- GSourceCallbackFuncs *callback_funcs);
+ gpointer callback_data,
+ GSourceCallbackFuncs *callback_funcs);
-void g_source_add_poll (GSource *source,
- GPollFD *fd);
-void g_source_remove_poll (GSource *source,
- GPollFD *fd);
+void g_source_add_poll (GSource *source,
+ GPollFD *fd);
+void g_source_remove_poll (GSource *source,
+ GPollFD *fd);
+void g_source_add_child_source (GSource *source,
+ GSource *child_source);
+void g_source_remove_child_source (GSource *source,
+ GSource *child_source);
+
+GLIB_DEPRECATED_FOR(g_source_get_time)
void g_source_get_current_time (GSource *source,
- GTimeVal *timeval);
+ GTimeVal *timeval);
+
+gint64 g_source_get_time (GSource *source);
/* void g_source_connect_closure (GSource *source,
GClosure *closure);
/* Miscellaneous functions
*/
-void g_get_current_time (GTimeVal *result);
+void g_get_current_time (GTimeVal *result);
+gint64 g_get_monotonic_time (void);
+gint64 g_get_real_time (void);
/* ============== Compat main loop stuff ================== */
#ifndef G_DISABLE_DEPRECATED
-/* Legacy names for GMainLoop functions
+/**
+ * g_main_new:
+ * @is_running: set to %TRUE to indicate that the loop is running. This
+ * is not very important since calling g_main_run() will set this
+ * to %TRUE anyway.
+ *
+ * Creates a new #GMainLoop for th default main context.
+ *
+ * Returns: a new #GMainLoop
+ *
+ * Deprecated: 2.2: Use g_main_loop_new() instead
+ */
+#define g_main_new(is_running) g_main_loop_new (NULL, is_running)
+
+/**
+ * g_main_run:
+ * @loop: a #GMainLoop
+ *
+ * Runs a main loop until it stops running.
+ *
+ * Deprecated: 2.2: Use g_main_loop_run() instead
*/
-#define g_main_new(is_running) g_main_loop_new (NULL, is_running);
#define g_main_run(loop) g_main_loop_run(loop)
-#define g_main_quit(loop) g_main_loop_quit(loop)
-#define g_main_destroy(loop) g_main_loop_unref(loop)
-#define g_main_is_running(loop) g_main_loop_is_running(loop)
-/* Functions to manipulate the default main loop
+/**
+ * g_main_quit:
+ * @loop: a #GMainLoop
+ *
+ * Stops the #GMainLoop.
+ * If g_main_run() was called to run the #GMainLoop, it will now return.
+ *
+ * Deprecated: 2.2: Use g_main_loop_quit() instead
*/
+#define g_main_quit(loop) g_main_loop_quit(loop)
-#define g_main_iteration(may_block) g_main_context_iteration (NULL, may_block)
-#define g_main_pending() g_main_context_pending (NULL)
+/**
+ * g_main_destroy:
+ * @loop: a #GMainLoop
+ *
+ * Frees the memory allocated for the #GMainLoop.
+ *
+ * Deprecated: 2.2: Use g_main_loop_unref() instead
+ */
+#define g_main_destroy(loop) g_main_loop_unref(loop)
-#define g_main_set_poll_func(func) g_main_context_set_poll_func (NULL, func)
+/**
+ * g_main_is_running:
+ * @loop: a #GMainLoop
+ *
+ * Checks if the main loop is running.
+ *
+ * Returns: %TRUE if the main loop is running
+ *
+ * Deprecated: 2.2: Use g_main_loop_is_running() instead
+ */
+#define g_main_is_running(loop) g_main_loop_is_running(loop)
+
+/**
+ * g_main_iteration:
+ * @may_block: set to %TRUE if it should block (i.e. wait) until an event
+ * source becomes ready. It will return after an event source has been
+ * processed. If set to %FALSE it will return immediately if no event
+ * source is ready to be processed.
+ *
+ * Runs a single iteration for the default #GMainContext.
+ *
+ * Returns: %TRUE if more events are pending.
+ *
+ * Deprecated: 2.2: Use g_main_context_iteration() instead.
+ */
+#define g_main_iteration(may_block) g_main_context_iteration (NULL, may_block)
+
+/**
+ * g_main_pending:
+ *
+ * Checks if any events are pending for the default #GMainContext
+ * (i.e. ready to be processed).
+ *
+ * Returns: %TRUE if any events are pending.
+ *
+ * Deprected: 2.2: Use g_main_context_pending() instead.
+ */
+#define g_main_pending() g_main_context_pending (NULL)
+
+/**
+ * g_main_set_poll_func:
+ * @func: the function to call to poll all file descriptors
+ *
+ * Sets the function to use for the handle polling of file descriptors
+ * for the default main context.
+ *
+ * Deprecated: 2.2: Use g_main_context_set_poll_func() again
+ */
+#define g_main_set_poll_func(func) g_main_context_set_poll_func (NULL, func)
#endif /* G_DISABLE_DEPRECATED */
gboolean g_source_remove (guint tag);
gboolean g_source_remove_by_user_data (gpointer user_data);
gboolean g_source_remove_by_funcs_user_data (GSourceFuncs *funcs,
- gpointer user_data);
+ gpointer user_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 (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);
+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);
+
+void g_main_context_invoke_full (GMainContext *context,
+ gint priority,
+ GSourceFunc function,
+ gpointer data,
+ GDestroyNotify notify);
+void g_main_context_invoke (GMainContext *context,
+ GSourceFunc function,
+ gpointer data);
/* Hook for GClosure / GSource integration. Don't touch */
GLIB_VAR GSourceFuncs g_timeout_funcs;