* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
-#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__
+#if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
+#error "Only <glib.h> can be included directly."
+#endif
+
#include <glib/gpoll.h>
#include <glib/gslist.h>
#include <glib/gthread.h>
G_BEGIN_DECLS
+typedef enum /*< flags >*/
+{
+ G_IO_IN GLIB_SYSDEF_POLLIN,
+ G_IO_OUT GLIB_SYSDEF_POLLOUT,
+ G_IO_PRI GLIB_SYSDEF_POLLPRI,
+ G_IO_ERR GLIB_SYSDEF_POLLERR,
+ G_IO_HUP GLIB_SYSDEF_POLLHUP,
+ G_IO_NVAL GLIB_SYSDEF_POLLNVAL
+} GIOCondition;
+
+
/**
* GMainContext:
*
- * The <structname>GMainContext</structname> struct is an opaque data
+ * The `GMainContext` 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
+ * The `GMainLoop` struct is an opaque data type
* representing the main event loop of a GLib or GTK+ application.
*/
typedef struct _GMainLoop GMainLoop;
/**
* GSource:
*
- * The <structname>GSource</structname> struct is an opaque data type
+ * The `GSource` struct is an opaque data type
* representing an event source.
*/
typedef struct _GSource GSource;
* @get: Called to extract the callback function and data from the
* callback object.
- * The <structname>GSourceCallbackFuncs</structname> struct contains
+ * The `GSourceCallbackFuncs` struct contains
* functions for managing callback objects.
*/
typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs;
* 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.
+ * be -1 if all sources returned -1, or it will be the minimum of all
+ * the @timeout_ values returned which were >= 0. Since 2.36 this may
+ * be %NULL, in which case the effect is as if the function always returns
+ * %FALSE with a timeout of -1. If @prepare returns a
+ * timeout and the source also has a 'ready time' set then the
+ * nearer of the two will be used.
* @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.
+ * so the source should be checked again here. Since 2.36 this may
+ * be %NULL, in which case the effect is as if the function always returns
+ * %FALSE.
* @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
* 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
+ * The `GSourceFuncs` 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
*
* On UNIX, processes are identified by a process id (an integer),
* while Windows uses process handles (which are pointers).
+ *
+ * GPid is used in GLib only for descendant processes spawned with
+ * the g_spawn 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
+ * Returns: %FALSE if the source should be removed. #G_SOURCE_CONTINUE and
+ * #G_SOURCE_REMOVE are more memorable names for the return value.
*/
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
+ * @status: Status information about the child process, encoded
+ * in a platform-specific manner
* @user_data: user data passed to g_child_watch_add()
*
- * The type of functions to be called when a child exists.
+ * Prototype of a #GChildWatchSource callback, called when a child
+ * process has exited. To interpret @status, see the documentation
+ * for g_spawn_check_exit_status().
*/
typedef void (*GChildWatchFunc) (GPid pid,
gint status,
gpointer callback_data;
GSourceCallbackFuncs *callback_funcs;
- GSourceFuncs *source_funcs;
+ const GSourceFuncs *source_funcs;
guint ref_count;
GMainContext *context;
gpointer user_data);
void (*finalize) (GSource *source); /* Can be NULL */
+ /*< private >*/
/* For use by g_source_set_closure */
GSourceFunc closure_callback;
GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
*/
#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.32
+ */
+#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.32
+ */
+#define G_SOURCE_CONTINUE TRUE
+
/* GMainContext: */
+GLIB_AVAILABLE_IN_ALL
GMainContext *g_main_context_new (void);
+GLIB_AVAILABLE_IN_ALL
GMainContext *g_main_context_ref (GMainContext *context);
+GLIB_AVAILABLE_IN_ALL
void g_main_context_unref (GMainContext *context);
+GLIB_AVAILABLE_IN_ALL
GMainContext *g_main_context_default (void);
+GLIB_AVAILABLE_IN_ALL
gboolean g_main_context_iteration (GMainContext *context,
gboolean may_block);
+GLIB_AVAILABLE_IN_ALL
gboolean g_main_context_pending (GMainContext *context);
/* For implementation of legacy interfaces
*/
+GLIB_AVAILABLE_IN_ALL
GSource *g_main_context_find_source_by_id (GMainContext *context,
guint source_id);
+GLIB_AVAILABLE_IN_ALL
GSource *g_main_context_find_source_by_user_data (GMainContext *context,
gpointer user_data);
+GLIB_AVAILABLE_IN_ALL
GSource *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
GSourceFuncs *funcs,
gpointer user_data);
/* Low level functions for implementing custom main loops.
*/
+GLIB_AVAILABLE_IN_ALL
void g_main_context_wakeup (GMainContext *context);
+GLIB_AVAILABLE_IN_ALL
gboolean g_main_context_acquire (GMainContext *context);
+GLIB_AVAILABLE_IN_ALL
void g_main_context_release (GMainContext *context);
+GLIB_AVAILABLE_IN_ALL
gboolean g_main_context_is_owner (GMainContext *context);
+GLIB_AVAILABLE_IN_ALL
gboolean g_main_context_wait (GMainContext *context,
GCond *cond,
GMutex *mutex);
+GLIB_AVAILABLE_IN_ALL
gboolean g_main_context_prepare (GMainContext *context,
gint *priority);
+GLIB_AVAILABLE_IN_ALL
gint g_main_context_query (GMainContext *context,
gint max_priority,
gint *timeout_,
GPollFD *fds,
gint n_fds);
+GLIB_AVAILABLE_IN_ALL
gint g_main_context_check (GMainContext *context,
gint max_priority,
GPollFD *fds,
gint n_fds);
+GLIB_AVAILABLE_IN_ALL
void g_main_context_dispatch (GMainContext *context);
+GLIB_AVAILABLE_IN_ALL
void g_main_context_set_poll_func (GMainContext *context,
GPollFunc func);
+GLIB_AVAILABLE_IN_ALL
GPollFunc g_main_context_get_poll_func (GMainContext *context);
/* Low level functions for use by source implementations
*/
+GLIB_AVAILABLE_IN_ALL
void g_main_context_add_poll (GMainContext *context,
GPollFD *fd,
gint priority);
+GLIB_AVAILABLE_IN_ALL
void g_main_context_remove_poll (GMainContext *context,
GPollFD *fd);
+GLIB_AVAILABLE_IN_ALL
gint g_main_depth (void);
+GLIB_AVAILABLE_IN_ALL
GSource *g_main_current_source (void);
/* GMainContexts for other threads
*/
+GLIB_AVAILABLE_IN_ALL
void g_main_context_push_thread_default (GMainContext *context);
+GLIB_AVAILABLE_IN_ALL
void g_main_context_pop_thread_default (GMainContext *context);
+GLIB_AVAILABLE_IN_ALL
GMainContext *g_main_context_get_thread_default (void);
+GLIB_AVAILABLE_IN_ALL
+GMainContext *g_main_context_ref_thread_default (void);
/* GMainLoop: */
+GLIB_AVAILABLE_IN_ALL
GMainLoop *g_main_loop_new (GMainContext *context,
gboolean is_running);
+GLIB_AVAILABLE_IN_ALL
void g_main_loop_run (GMainLoop *loop);
+GLIB_AVAILABLE_IN_ALL
void g_main_loop_quit (GMainLoop *loop);
+GLIB_AVAILABLE_IN_ALL
GMainLoop *g_main_loop_ref (GMainLoop *loop);
+GLIB_AVAILABLE_IN_ALL
void g_main_loop_unref (GMainLoop *loop);
+GLIB_AVAILABLE_IN_ALL
gboolean g_main_loop_is_running (GMainLoop *loop);
+GLIB_AVAILABLE_IN_ALL
GMainContext *g_main_loop_get_context (GMainLoop *loop);
/* GSource: */
+GLIB_AVAILABLE_IN_ALL
GSource *g_source_new (GSourceFuncs *source_funcs,
guint struct_size);
+GLIB_AVAILABLE_IN_ALL
GSource *g_source_ref (GSource *source);
+GLIB_AVAILABLE_IN_ALL
void g_source_unref (GSource *source);
+GLIB_AVAILABLE_IN_ALL
guint g_source_attach (GSource *source,
GMainContext *context);
+GLIB_AVAILABLE_IN_ALL
void g_source_destroy (GSource *source);
+GLIB_AVAILABLE_IN_ALL
void g_source_set_priority (GSource *source,
gint priority);
+GLIB_AVAILABLE_IN_ALL
gint g_source_get_priority (GSource *source);
+GLIB_AVAILABLE_IN_ALL
void g_source_set_can_recurse (GSource *source,
gboolean can_recurse);
+GLIB_AVAILABLE_IN_ALL
gboolean g_source_get_can_recurse (GSource *source);
+GLIB_AVAILABLE_IN_ALL
guint g_source_get_id (GSource *source);
+GLIB_AVAILABLE_IN_ALL
GMainContext *g_source_get_context (GSource *source);
+GLIB_AVAILABLE_IN_ALL
void g_source_set_callback (GSource *source,
GSourceFunc func,
gpointer data,
GDestroyNotify notify);
+GLIB_AVAILABLE_IN_ALL
void g_source_set_funcs (GSource *source,
GSourceFuncs *funcs);
+GLIB_AVAILABLE_IN_ALL
gboolean g_source_is_destroyed (GSource *source);
+GLIB_AVAILABLE_IN_ALL
void g_source_set_name (GSource *source,
const char *name);
+GLIB_AVAILABLE_IN_ALL
const char * g_source_get_name (GSource *source);
+GLIB_AVAILABLE_IN_ALL
void g_source_set_name_by_id (guint tag,
const char *name);
+GLIB_AVAILABLE_IN_2_36
+void g_source_set_ready_time (GSource *source,
+ gint64 ready_time);
+GLIB_AVAILABLE_IN_2_36
+gint64 g_source_get_ready_time (GSource *source);
+
+#ifdef G_OS_UNIX
+GLIB_AVAILABLE_IN_2_36
+gpointer g_source_add_unix_fd (GSource *source,
+ gint fd,
+ GIOCondition events);
+GLIB_AVAILABLE_IN_2_36
+void g_source_modify_unix_fd (GSource *source,
+ gpointer tag,
+ GIOCondition new_events);
+GLIB_AVAILABLE_IN_2_36
+void g_source_remove_unix_fd (GSource *source,
+ gpointer tag);
+GLIB_AVAILABLE_IN_2_36
+GIOCondition g_source_query_unix_fd (GSource *source,
+ gpointer tag);
+#endif
/* Used to implement g_source_connect_closure and internally*/
+GLIB_AVAILABLE_IN_ALL
void g_source_set_callback_indirect (GSource *source,
gpointer callback_data,
GSourceCallbackFuncs *callback_funcs);
+GLIB_AVAILABLE_IN_ALL
void g_source_add_poll (GSource *source,
GPollFD *fd);
+GLIB_AVAILABLE_IN_ALL
void g_source_remove_poll (GSource *source,
GPollFD *fd);
+GLIB_AVAILABLE_IN_ALL
void g_source_add_child_source (GSource *source,
GSource *child_source);
+GLIB_AVAILABLE_IN_ALL
void g_source_remove_child_source (GSource *source,
GSource *child_source);
-#ifndef G_DISABLE_DEPRECATED
+GLIB_DEPRECATED_IN_2_28_FOR(g_source_get_time)
void g_source_get_current_time (GSource *source,
GTimeVal *timeval);
-#endif
+
+GLIB_AVAILABLE_IN_ALL
gint64 g_source_get_time (GSource *source);
/* void g_source_connect_closure (GSource *source,
/* Specific source types
*/
+GLIB_AVAILABLE_IN_ALL
GSource *g_idle_source_new (void);
+GLIB_AVAILABLE_IN_ALL
GSource *g_child_watch_source_new (GPid pid);
+GLIB_AVAILABLE_IN_ALL
GSource *g_timeout_source_new (guint interval);
+GLIB_AVAILABLE_IN_ALL
GSource *g_timeout_source_new_seconds (guint interval);
/* Miscellaneous functions
*/
+GLIB_AVAILABLE_IN_ALL
void g_get_current_time (GTimeVal *result);
+GLIB_AVAILABLE_IN_ALL
gint64 g_get_monotonic_time (void);
+GLIB_AVAILABLE_IN_ALL
gint64 g_get_real_time (void);
-/* ============== Compat main loop stuff ================== */
-
-#ifndef G_DISABLE_DEPRECATED
-
-/**
- * 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_run(loop) g_main_loop_run(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)
-
-/**
- * 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)
-
-/**
- * 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 */
/* Source manipulation by ID */
+GLIB_AVAILABLE_IN_ALL
gboolean g_source_remove (guint tag);
+GLIB_AVAILABLE_IN_ALL
gboolean g_source_remove_by_user_data (gpointer user_data);
+GLIB_AVAILABLE_IN_ALL
gboolean g_source_remove_by_funcs_user_data (GSourceFuncs *funcs,
gpointer user_data);
/* Idles, child watchers and timeouts */
+GLIB_AVAILABLE_IN_ALL
guint g_timeout_add_full (gint priority,
guint interval,
GSourceFunc function,
gpointer data,
GDestroyNotify notify);
+GLIB_AVAILABLE_IN_ALL
guint g_timeout_add (guint interval,
GSourceFunc function,
gpointer data);
+GLIB_AVAILABLE_IN_ALL
guint g_timeout_add_seconds_full (gint priority,
guint interval,
GSourceFunc function,
gpointer data,
GDestroyNotify notify);
+GLIB_AVAILABLE_IN_ALL
guint g_timeout_add_seconds (guint interval,
GSourceFunc function,
gpointer data);
-
+GLIB_AVAILABLE_IN_ALL
guint g_child_watch_add_full (gint priority,
GPid pid,
GChildWatchFunc function,
gpointer data,
GDestroyNotify notify);
+GLIB_AVAILABLE_IN_ALL
guint g_child_watch_add (GPid pid,
GChildWatchFunc function,
gpointer data);
+GLIB_AVAILABLE_IN_ALL
guint g_idle_add (GSourceFunc function,
gpointer data);
+GLIB_AVAILABLE_IN_ALL
guint g_idle_add_full (gint priority,
GSourceFunc function,
gpointer data,
GDestroyNotify notify);
+GLIB_AVAILABLE_IN_ALL
gboolean g_idle_remove_by_data (gpointer data);
+GLIB_AVAILABLE_IN_ALL
void g_main_context_invoke_full (GMainContext *context,
gint priority,
GSourceFunc function,
gpointer data,
GDestroyNotify notify);
+GLIB_AVAILABLE_IN_ALL
void g_main_context_invoke (GMainContext *context,
GSourceFunc function,
gpointer data);
GLIB_VAR GSourceFuncs g_timeout_funcs;
GLIB_VAR GSourceFuncs g_child_watch_funcs;
GLIB_VAR GSourceFuncs g_idle_funcs;
+#ifdef G_OS_UNIX
+GLIB_VAR GSourceFuncs g_unix_signal_funcs;
+GLIB_VAR GSourceFuncs g_unix_fd_source_funcs;
+#endif
G_END_DECLS