<refentry id="glib-The-Main-Event-Loop">
<refmeta>
<refentrytitle>The Main Event Loop</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>The Main Event Loop</refname><refpurpose>manages all available sources of events.</refpurpose>
</refnamediv>
<refsynopsisdiv><title>Synopsis</title>
<synopsis>
#include <glib.h>
struct <link linkend="GMainLoop">GMainLoop</link>;
<link linkend="GMainLoop">GMainLoop</link>* <link linkend="g-main-loop-new">g_main_loop_new</link> (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="gboolean">gboolean</link> is_running);
<link linkend="GMainLoop">GMainLoop</link>* <link linkend="g-main-loop-ref">g_main_loop_ref</link> (<link linkend="GMainLoop">GMainLoop</link> *loop);
<link linkend="void">void</link> <link linkend="g-main-loop-unref">g_main_loop_unref</link> (<link linkend="GMainLoop">GMainLoop</link> *loop);
<link linkend="void">void</link> <link linkend="g-main-loop-run">g_main_loop_run</link> (<link linkend="GMainLoop">GMainLoop</link> *loop);
<link linkend="void">void</link> <link linkend="g-main-loop-quit">g_main_loop_quit</link> (<link linkend="GMainLoop">GMainLoop</link> *loop);
<link linkend="gboolean">gboolean</link> <link linkend="g-main-loop-is-running">g_main_loop_is_running</link> (<link linkend="GMainLoop">GMainLoop</link> *loop);
<link linkend="GMainContext">GMainContext</link>* <link linkend="g-main-loop-get-context">g_main_loop_get_context</link> (<link linkend="GMainLoop">GMainLoop</link> *loop);
#define <link linkend="g-main-new">g_main_new</link> (is_running)
#define <link linkend="g-main-destroy">g_main_destroy</link> (loop)
#define <link linkend="g-main-run">g_main_run</link> (loop)
#define <link linkend="g-main-quit">g_main_quit</link> (loop)
#define <link linkend="g-main-is-running">g_main_is_running</link> (loop)
#define <link linkend="G-PRIORITY-HIGH-CAPS">G_PRIORITY_HIGH</link>
#define <link linkend="G-PRIORITY-DEFAULT-CAPS">G_PRIORITY_DEFAULT</link>
#define <link linkend="G-PRIORITY-HIGH-IDLE-CAPS">G_PRIORITY_HIGH_IDLE</link>
#define <link linkend="G-PRIORITY-DEFAULT-IDLE-CAPS">G_PRIORITY_DEFAULT_IDLE</link>
#define <link linkend="G-PRIORITY-LOW-CAPS">G_PRIORITY_LOW</link>
struct <link linkend="GMainContext">GMainContext</link>;
<link linkend="GMainContext">GMainContext</link>* <link linkend="g-main-context-new">g_main_context_new</link> (void);
<link linkend="void">void</link> <link linkend="g-main-context-ref">g_main_context_ref</link> (<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="void">void</link> <link linkend="g-main-context-unref">g_main_context_unref</link> (<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="GMainContext">GMainContext</link>* <link linkend="g-main-context-default">g_main_context_default</link> (void);
<link linkend="gboolean">gboolean</link> <link linkend="g-main-context-iteration">g_main_context_iteration</link> (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="gboolean">gboolean</link> may_block);
#define <link linkend="g-main-iteration">g_main_iteration</link> (may_block)
<link linkend="gboolean">gboolean</link> <link linkend="g-main-context-pending">g_main_context_pending</link> (<link linkend="GMainContext">GMainContext</link> *context);
#define <link linkend="g-main-pending">g_main_pending</link> ()
<link linkend="GSource">GSource</link>* <link linkend="g-main-context-find-source-by-id">g_main_context_find_source_by_id</link>
(<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="guint">guint</link> source_id);
<link linkend="GSource">GSource</link>* <link linkend="g-main-context-find-source-by-user-data">g_main_context_find_source_by_user_data</link>
(<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="gpointer">gpointer</link> user_data);
<link linkend="GSource">GSource</link>* <link linkend="g-main-context-find-source-by-funcs-user-data">g_main_context_find_source_by_funcs_user_data</link>
(<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="GSourceFuncs">GSourceFuncs</link> *funcs,
<link linkend="gpointer">gpointer</link> user_data);
<link linkend="void">void</link> <link linkend="g-main-context-wakeup">g_main_context_wakeup</link> (<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="gboolean">gboolean</link> <link linkend="g-main-context-acquire">g_main_context_acquire</link> (<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="void">void</link> <link linkend="g-main-context-release">g_main_context_release</link> (<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="gboolean">gboolean</link> <link linkend="g-main-context-wait">g_main_context_wait</link> (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="GCond">GCond</link> *cond,
<link linkend="GMutex">GMutex</link> *mutex);
<link linkend="gboolean">gboolean</link> <link linkend="g-main-context-prepare">g_main_context_prepare</link> (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="gint">gint</link> *priority);
<link linkend="gint">gint</link> <link linkend="g-main-context-query">g_main_context_query</link> (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="gint">gint</link> max_priority,
<link linkend="gint">gint</link> *timeout_,
<link linkend="GPollFD">GPollFD</link> *fds,
<link linkend="gint">gint</link> n_fds);
<link linkend="gint">gint</link> <link linkend="g-main-context-check">g_main_context_check</link> (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="gint">gint</link> max_priority,
<link linkend="GPollFD">GPollFD</link> *fds,
<link linkend="gint">gint</link> n_fds);
<link linkend="void">void</link> <link linkend="g-main-context-dispatch">g_main_context_dispatch</link> (<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="void">void</link> <link linkend="g-main-context-set-poll-func">g_main_context_set_poll_func</link> (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="GPollFunc">GPollFunc</link> func);
<link linkend="GPollFunc">GPollFunc</link> <link linkend="g-main-context-get-poll-func">g_main_context_get_poll_func</link> (<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="gint">gint</link> (<link linkend="GPollFunc">*GPollFunc</link>) (<link linkend="GPollFD">GPollFD</link> *ufds,
<link linkend="guint">guint</link> nfsd,
<link linkend="gint">gint</link> timeout_);
<link linkend="void">void</link> <link linkend="g-main-context-add-poll">g_main_context_add_poll</link> (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="GPollFD">GPollFD</link> *fd,
<link linkend="gint">gint</link> priority);
<link linkend="void">void</link> <link linkend="g-main-context-remove-poll">g_main_context_remove_poll</link> (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="GPollFD">GPollFD</link> *fd);
<link linkend="int">int</link> <link linkend="g-main-depth">g_main_depth</link> (void);
#define <link linkend="g-main-set-poll-func">g_main_set_poll_func</link> (func)
<link linkend="GSource">GSource</link>* <link linkend="g-timeout-source-new">g_timeout_source_new</link> (<link linkend="guint">guint</link> interval);
<link linkend="guint">guint</link> <link linkend="g-timeout-add">g_timeout_add</link> (<link linkend="guint">guint</link> interval,
<link linkend="GSourceFunc">GSourceFunc</link> function,
<link linkend="gpointer">gpointer</link> data);
<link linkend="guint">guint</link> <link linkend="g-timeout-add-full">g_timeout_add_full</link> (<link linkend="gint">gint</link> priority,
<link linkend="guint">guint</link> interval,
<link linkend="GSourceFunc">GSourceFunc</link> function,
<link linkend="gpointer">gpointer</link> data,
<link linkend="GDestroyNotify">GDestroyNotify</link> notify);
<link linkend="GSource">GSource</link>* <link linkend="g-idle-source-new">g_idle_source_new</link> (void);
<link linkend="guint">guint</link> <link linkend="g-idle-add">g_idle_add</link> (<link linkend="GSourceFunc">GSourceFunc</link> function,
<link linkend="gpointer">gpointer</link> data);
<link linkend="guint">guint</link> <link linkend="g-idle-add-full">g_idle_add_full</link> (<link linkend="gint">gint</link> priority,
<link linkend="GSourceFunc">GSourceFunc</link> function,
<link linkend="gpointer">gpointer</link> data,
<link linkend="GDestroyNotify">GDestroyNotify</link> notify);
<link linkend="gboolean">gboolean</link> <link linkend="g-idle-remove-by-data">g_idle_remove_by_data</link> (<link linkend="gpointer">gpointer</link> data);
typedef <link linkend="GPid">GPid</link>;
<link linkend="void">void</link> (<link linkend="GChildWatchFunc">*GChildWatchFunc</link>) (<link linkend="GPid">GPid</link> pid,
<link linkend="gint">gint</link> status,
<link linkend="gpointer">gpointer</link> data);
<link linkend="GSource">GSource</link>* <link linkend="g-child-watch-source-new">g_child_watch_source_new</link> (<link linkend="GPid">GPid</link> pid);
<link linkend="guint">guint</link> <link linkend="g-child-watch-add">g_child_watch_add</link> (<link linkend="GPid">GPid</link> pid,
<link linkend="GChildWatchFunc">GChildWatchFunc</link> function,
<link linkend="gpointer">gpointer</link> data);
<link linkend="guint">guint</link> <link linkend="g-child-watch-add-full">g_child_watch_add_full</link> (<link linkend="gint">gint</link> priority,
<link linkend="GPid">GPid</link> pid,
<link linkend="GChildWatchFunc">GChildWatchFunc</link> function,
<link linkend="gpointer">gpointer</link> data,
<link linkend="GDestroyNotify">GDestroyNotify</link> notify);
struct <link linkend="GPollFD">GPollFD</link>;
struct <link linkend="GSource">GSource</link>;
<link linkend="void">void</link> (<link linkend="GSourceDummyMarshal">*GSourceDummyMarshal</link>) (void);
struct <link linkend="GSourceFuncs">GSourceFuncs</link>;
struct <link linkend="GSourceCallbackFuncs">GSourceCallbackFuncs</link>;
<link linkend="GSource">GSource</link>* <link linkend="g-source-new">g_source_new</link> (<link linkend="GSourceFuncs">GSourceFuncs</link> *source_funcs,
<link linkend="guint">guint</link> struct_size);
<link linkend="GSource">GSource</link>* <link linkend="g-source-ref">g_source_ref</link> (<link linkend="GSource">GSource</link> *source);
<link linkend="void">void</link> <link linkend="g-source-unref">g_source_unref</link> (<link linkend="GSource">GSource</link> *source);
<link linkend="guint">guint</link> <link linkend="g-source-attach">g_source_attach</link> (<link linkend="GSource">GSource</link> *source,
<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="void">void</link> <link linkend="g-source-destroy">g_source_destroy</link> (<link linkend="GSource">GSource</link> *source);
<link linkend="void">void</link> <link linkend="g-source-set-priority">g_source_set_priority</link> (<link linkend="GSource">GSource</link> *source,
<link linkend="gint">gint</link> priority);
<link linkend="gint">gint</link> <link linkend="g-source-get-priority">g_source_get_priority</link> (<link linkend="GSource">GSource</link> *source);
<link linkend="void">void</link> <link linkend="g-source-set-can-recurse">g_source_set_can_recurse</link> (<link linkend="GSource">GSource</link> *source,
<link linkend="gboolean">gboolean</link> can_recurse);
<link linkend="gboolean">gboolean</link> <link linkend="g-source-get-can-recurse">g_source_get_can_recurse</link> (<link linkend="GSource">GSource</link> *source);
<link linkend="guint">guint</link> <link linkend="g-source-get-id">g_source_get_id</link> (<link linkend="GSource">GSource</link> *source);
<link linkend="GMainContext">GMainContext</link>* <link linkend="g-source-get-context">g_source_get_context</link> (<link linkend="GSource">GSource</link> *source);
<link linkend="void">void</link> <link linkend="g-source-set-callback">g_source_set_callback</link> (<link linkend="GSource">GSource</link> *source,
<link linkend="GSourceFunc">GSourceFunc</link> func,
<link linkend="gpointer">gpointer</link> data,
<link linkend="GDestroyNotify">GDestroyNotify</link> notify);
<link linkend="gboolean">gboolean</link> (<link linkend="GSourceFunc">*GSourceFunc</link>) (<link linkend="gpointer">gpointer</link> data);
<link linkend="void">void</link> <link linkend="g-source-set-callback-indirect">g_source_set_callback_indirect</link> (<link linkend="GSource">GSource</link> *source,
<link linkend="gpointer">gpointer</link> callback_data,
<link linkend="GSourceCallbackFuncs">GSourceCallbackFuncs</link> *callback_funcs);
<link linkend="void">void</link> <link linkend="g-source-add-poll">g_source_add_poll</link> (<link linkend="GSource">GSource</link> *source,
<link linkend="GPollFD">GPollFD</link> *fd);
<link linkend="void">void</link> <link linkend="g-source-remove-poll">g_source_remove_poll</link> (<link linkend="GSource">GSource</link> *source,
<link linkend="GPollFD">GPollFD</link> *fd);
<link linkend="void">void</link> <link linkend="g-source-get-current-time">g_source_get_current_time</link> (<link linkend="GSource">GSource</link> *source,
<link linkend="GTimeVal">GTimeVal</link> *timeval);
<link linkend="gboolean">gboolean</link> <link linkend="g-source-remove">g_source_remove</link> (<link linkend="guint">guint</link> tag);
<link linkend="gboolean">gboolean</link> <link linkend="g-source-remove-by-funcs-user-data">g_source_remove_by_funcs_user_data</link>
(<link linkend="GSourceFuncs">GSourceFuncs</link> *funcs,
<link linkend="gpointer">gpointer</link> user_data);
<link linkend="gboolean">gboolean</link> <link linkend="g-source-remove-by-user-data">g_source_remove_by_user_data</link> (<link linkend="gpointer">gpointer</link> user_data);
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
The main event loop manages all the available sources of events for
GLib and GTK+ applications. These events can come from any number of
different types of sources such as file descriptors (plain files,
pipes or sockets) and timeouts. New types of event sources can also
be added using <link linkend="g-source-attach"><function>g_source_attach()</function></link>.
</para>
<para>
To allow multiple independent sets of sources to be handled in
different threads, each source is associated with a <link linkend="GMainContext"><type>GMainContext</type></link>.
A <link linkend="GMainContext"><type>GMainContext</type></link> can only be running in a single thread, but
sources can be added to it and removed from it from other threads.
</para>
<para>
Each event source is assigned a priority. The default priority,
<link linkend="G-PRIORITY-DEFAULT-CAPS"><type>G_PRIORITY_DEFAULT</type></link>, is 0. Values less than 0 denote higher
priorities. Values greater than 0 denote lower priorities. Events
from high priority sources are always processed before events from
lower priority sources.
</para>
<para>
Idle functions can also be added, and assigned a priority. These will
be run whenever no events with a higher priority are ready to be
processed.
</para>
<para>
The <link linkend="GMainLoop"><type>GMainLoop</type></link> data type represents a main event loop. A <link linkend="GMainLoop"><type>GMainLoop</type></link>
is created with <link linkend="g-main-loop-new"><function>g_main_loop_new()</function></link>. After adding the initial event sources,
<link linkend="g-main-loop-run"><function>g_main_loop_run()</function></link> is called. This continuously checks for new events from
each of the event sources and dispatches them. Finally, the
processing of an event from one of the sources leads to a call to
<link linkend="g-main-loop-quit"><function>g_main_loop_quit()</function></link> to exit the main loop, and <link linkend="g-main-loop-run"><function>g_main_loop_run()</function></link> returns.
</para>
<para>
It is possible to create new instances of <link linkend="GMainLoop"><type>GMainLoop</type></link> recursively.
This is often used in GTK+ applications when showing modal dialog
boxes. Note that event sources are associated with a particular
<link linkend="GMainContext"><type>GMainContext</type></link>, and will be checked and dispatched for all main
loops associated with that <link linkend="GMainContext"><type>GMainContext</type></link>.
</para>
<para>
GTK+ contains wrappers of some of these functions, e.g. <link linkend="gtk-main"><function>gtk_main()</function></link>,
<link linkend="gtk-main-quit"><function>gtk_main_quit()</function></link> and <link linkend="gtk-events-pending"><function>gtk_events_pending()</function></link>.
</para>
<refsect2>
<title>Creating new sources types</title>
<para>
One of the unusual features of the GTK+ main loop functionality
is that new types of event source can be created and used in
addition to the builtin type of event source. A new event source
type is used for handling GDK events. A new source type is
created by <firstterm>deriving</firstterm> from the <link linkend="GSource"><type>GSource</type></link>
structure. The derived type of source is represented by a
structure that has the <link linkend="GSource"><type>GSource</type></link> structure as a first element,
and other elements specific to the new source type. To create
an instance of the new source type, call <link linkend="g-source-new"><function>g_source_new()</function></link> passing
in the size of the derived structure and a table of functions.
These <link linkend="GSourceFuncs"><type>GSourceFuncs</type></link> determine the behavior of the new source
types.
</para>
<para>
New source types basically interact with with the main context
in two ways. Their prepare function in <link linkend="GSourceFuncs"><type>GSourceFuncs</type></link> can set
a timeout to determine the maximum amount of time that the
main loop will sleep before checking the source again. In
addition, or as well, the source can add file descriptors to
the set that the main context checks using <link linkend="g-source-add-poll"><function>g_source_add_poll()</function></link>.
</para>
</refsect2>
<refsect2>
<title>Customizing the main loop iteration</title>
<para>
Single iterations of a <link linkend="GMainContext"><type>GMainContext</type></link> can be run with
<link linkend="g-main-context-iteration"><function>g_main_context_iteration()</function></link>. In some cases, more detailed control
of exactly how the details of the main loop work is desired,
for instance, when integrating the <link linkend="GMainLoop"><type>GMainLoop</type></link> with an external
main loop. In such cases, you can call the component functions
of <link linkend="g-main-context-iteration"><function>g_main_context_iteration()</function></link> directly. These functions
are <link linkend="g-main-context-prepare"><function>g_main_context_prepare()</function></link>, <link linkend="g-main-context-query"><function>g_main_context_query()</function></link>,
<link linkend="g-main-context-check"><function>g_main_context_check()</function></link> and <link linkend="g-main-context-dispatch"><function>g_main_context_dispatch()</function></link>.
</para>
<para>
The operation of these functions can best be seen in terms
of a state diagram, as shown in <xref linkend="mainloop-states"/>.
</para>
<figure id="mainloop-states">
<title>States of a Main Context</title>
<graphic fileref="mainloop-states.gif" format="GIF"></graphic>
</figure>
</refsect2>
</refsect1>
<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GMainLoop"/>struct GMainLoop</title>
<indexterm><primary>GMainLoop</primary></indexterm><programlisting>struct GMainLoop;</programlisting>
<para>
The <structname>GMainLoop</structname> struct is an opaque data type
representing the main event loop of a GLib or GTK+ application.
</para></refsect2>
<refsect2>
<title><anchor id="g-main-loop-new"/>g_main_loop_new ()</title>
<indexterm><primary>g_main_loop_new</primary></indexterm><programlisting><link linkend="GMainLoop">GMainLoop</link>* g_main_loop_new (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="gboolean">gboolean</link> is_running);</programlisting>
<para>
Creates a new <link linkend="GMainLoop"><type>GMainLoop</type></link> structure.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (if <literal>NULL</literal>, the default context will be used).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>is_running</parameter> :</term>
<listitem><simpara> set to <literal>TRUE</literal> to indicate that the loop is running. This
is not very important since calling <link linkend="g-main-loop-run"><function>g_main_loop_run()</function></link> will set this to
<literal>TRUE</literal> anyway.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-loop-ref"/>g_main_loop_ref ()</title>
<indexterm><primary>g_main_loop_ref</primary></indexterm><programlisting><link linkend="GMainLoop">GMainLoop</link>* g_main_loop_ref (<link linkend="GMainLoop">GMainLoop</link> *loop);</programlisting>
<para>
Increases the reference count on a <link linkend="GMainLoop"><type>GMainLoop</type></link> object by one.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>loop</parameter> :</term>
<listitem><simpara> a <link linkend="GMainLoop"><type>GMainLoop</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>loop</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-loop-unref"/>g_main_loop_unref ()</title>
<indexterm><primary>g_main_loop_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_main_loop_unref (<link linkend="GMainLoop">GMainLoop</link> *loop);</programlisting>
<para>
Decreases the reference count on a <link linkend="GMainLoop"><type>GMainLoop</type></link> object by one. If
the result is zero, free the loop and free all associated memory.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>loop</parameter> :</term>
<listitem><simpara> a <link linkend="GMainLoop"><type>GMainLoop</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-loop-run"/>g_main_loop_run ()</title>
<indexterm><primary>g_main_loop_run</primary></indexterm><programlisting><link linkend="void">void</link> g_main_loop_run (<link linkend="GMainLoop">GMainLoop</link> *loop);</programlisting>
<para>
Runs a main loop until <link linkend="g-main-loop-quit"><function>g_main_loop_quit()</function></link> is called on the loop.
If this is called for the thread of the loop's <link linkend="GMainContext"><type>GMainContext</type></link>,
it will process events from the loop, otherwise it will
simply wait.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>loop</parameter> :</term>
<listitem><simpara> a <link linkend="GMainLoop"><type>GMainLoop</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-loop-quit"/>g_main_loop_quit ()</title>
<indexterm><primary>g_main_loop_quit</primary></indexterm><programlisting><link linkend="void">void</link> g_main_loop_quit (<link linkend="GMainLoop">GMainLoop</link> *loop);</programlisting>
<para>
Stops a <link linkend="GMainLoop"><type>GMainLoop</type></link> from running. Any calls to <link linkend="g-main-loop-run"><function>g_main_loop_run()</function></link>
for the loop will return.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>loop</parameter> :</term>
<listitem><simpara> a <link linkend="GMainLoop"><type>GMainLoop</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-loop-is-running"/>g_main_loop_is_running ()</title>
<indexterm><primary>g_main_loop_is_running</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_main_loop_is_running (<link linkend="GMainLoop">GMainLoop</link> *loop);</programlisting>
<para>
Checks to see if the main loop is currently being run via <link linkend="g-main-loop-run"><function>g_main_loop_run()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>loop</parameter> :</term>
<listitem><simpara> a <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if the mainloop is currently being run.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-loop-get-context"/>g_main_loop_get_context ()</title>
<indexterm><primary>g_main_loop_get_context</primary></indexterm><programlisting><link linkend="GMainContext">GMainContext</link>* g_main_loop_get_context (<link linkend="GMainLoop">GMainLoop</link> *loop);</programlisting>
<para>
Returns the <link linkend="GMainContext"><type>GMainContext</type></link> of <parameter>loop</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>loop</parameter> :</term>
<listitem><simpara> a <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="GMainContext"><type>GMainContext</type></link> of <parameter>loop</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-new"/>g_main_new()</title>
<indexterm role="deprecated"><primary>g_main_new</primary></indexterm><programlisting>#define g_main_new(is_running)</programlisting>
<warning><para><literal>g_main_new</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-main-loop-new"><function>g_main_loop_new()</function></link> instead.</para></warning>
<para>
Creates a new <link linkend="GMainLoop"><type>GMainLoop</type></link> for the default main loop.
</para><variablelist role="params">
<varlistentry><term><parameter>is_running</parameter> :</term>
<listitem><simpara>set to <literal>TRUE</literal> to indicate that the loop is running. This is not
very important since calling <link linkend="g-main-run"><function>g_main_run()</function></link> will set this to <literal>TRUE</literal> anyway.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-destroy"/>g_main_destroy()</title>
<indexterm role="deprecated"><primary>g_main_destroy</primary></indexterm><programlisting>#define g_main_destroy(loop)</programlisting>
<warning><para><literal>g_main_destroy</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-main-loop-unref"><function>g_main_loop_unref()</function></link> instead.</para></warning>
<para>
Frees the memory allocated for the <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>loop</parameter> :</term>
<listitem><simpara>a <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-run"/>g_main_run()</title>
<indexterm role="deprecated"><primary>g_main_run</primary></indexterm><programlisting>#define g_main_run(loop)</programlisting>
<warning><para><literal>g_main_run</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-main-loop-run"><function>g_main_loop_run()</function></link> instead.</para></warning>
<para>
Runs a main loop until it stops running.
</para><variablelist role="params">
<varlistentry><term><parameter>loop</parameter> :</term>
<listitem><simpara>a <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-quit"/>g_main_quit()</title>
<indexterm role="deprecated"><primary>g_main_quit</primary></indexterm><programlisting>#define g_main_quit(loop)</programlisting>
<warning><para><literal>g_main_quit</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-main-loop-quit"><function>g_main_loop_quit()</function></link> instead.</para></warning>
<para>
Stops the <link linkend="GMainLoop"><type>GMainLoop</type></link>. If <link linkend="g-main-run"><function>g_main_run()</function></link> was called to run the <link linkend="GMainLoop"><type>GMainLoop</type></link>,
it will now return.
</para><variablelist role="params">
<varlistentry><term><parameter>loop</parameter> :</term>
<listitem><simpara>a <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-is-running"/>g_main_is_running()</title>
<indexterm role="deprecated"><primary>g_main_is_running</primary></indexterm><programlisting>#define g_main_is_running(loop)</programlisting>
<warning><para><literal>g_main_is_running</literal> is deprecated and should not be used in newly-written code. USe <link linkend="g-main-loop-is-running"><function>g_main_loop_is_running()</function></link> instead.</para></warning>
<para>
Checks if the main loop is running.
</para><variablelist role="params">
<varlistentry><term><parameter>loop</parameter> :</term>
<listitem><simpara>a <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if the main loop is running.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-PRIORITY-HIGH-CAPS"/>G_PRIORITY_HIGH</title>
<indexterm><primary>G_PRIORITY_HIGH</primary></indexterm><programlisting>#define G_PRIORITY_HIGH -100
</programlisting>
<para>
Use this for high priority event sources.
It is not used within GLib or GTK+.
</para></refsect2>
<refsect2>
<title><anchor id="G-PRIORITY-DEFAULT-CAPS"/>G_PRIORITY_DEFAULT</title>
<indexterm><primary>G_PRIORITY_DEFAULT</primary></indexterm><programlisting>#define G_PRIORITY_DEFAULT 0
</programlisting>
<para>
Use this for default priority event sources.
In GLib this priority is used when adding timeout functions with
<link linkend="g-timeout-add"><function>g_timeout_add()</function></link>.
In GDK this priority is used for events from the X server.
</para></refsect2>
<refsect2>
<title><anchor id="G-PRIORITY-HIGH-IDLE-CAPS"/>G_PRIORITY_HIGH_IDLE</title>
<indexterm><primary>G_PRIORITY_HIGH_IDLE</primary></indexterm><programlisting>#define G_PRIORITY_HIGH_IDLE 100
</programlisting>
<para>
Use this for high priority idle functions.
GTK+ uses <link linkend="G-PRIORITY-HIGH-IDLE-CAPS"><type>G_PRIORITY_HIGH_IDLE</type></link> + 10 for resizing operations, and
<link linkend="G-PRIORITY-HIGH-IDLE-CAPS"><type>G_PRIORITY_HIGH_IDLE</type></link> + 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.)
</para></refsect2>
<refsect2>
<title><anchor id="G-PRIORITY-DEFAULT-IDLE-CAPS"/>G_PRIORITY_DEFAULT_IDLE</title>
<indexterm><primary>G_PRIORITY_DEFAULT_IDLE</primary></indexterm><programlisting>#define G_PRIORITY_DEFAULT_IDLE 200
</programlisting>
<para>
Use this for default priority idle functions.
In GLib this priority is used when adding idle functions with <link linkend="g-idle-add"><function>g_idle_add()</function></link>.
</para></refsect2>
<refsect2>
<title><anchor id="G-PRIORITY-LOW-CAPS"/>G_PRIORITY_LOW</title>
<indexterm><primary>G_PRIORITY_LOW</primary></indexterm><programlisting>#define G_PRIORITY_LOW 300
</programlisting>
<para>
Use this for very low priority background tasks.
It is not used within GLib or GTK+.
</para></refsect2>
<refsect2>
<title><anchor id="GMainContext"/>struct GMainContext</title>
<indexterm><primary>GMainContext</primary></indexterm><programlisting>struct GMainContext;</programlisting>
<para>
The <structname>GMainContext</structname> struct is an opaque data type
representing a set of sources to be handled in a main loop.
</para></refsect2>
<refsect2>
<title><anchor id="g-main-context-new"/>g_main_context_new ()</title>
<indexterm><primary>g_main_context_new</primary></indexterm><programlisting><link linkend="GMainContext">GMainContext</link>* g_main_context_new (void);</programlisting>
<para>
Creates a new <link linkend="GMainContext"><type>GMainContext</type></link> strcuture</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the new <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-ref"/>g_main_context_ref ()</title>
<indexterm><primary>g_main_context_ref</primary></indexterm><programlisting><link linkend="void">void</link> g_main_context_ref (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Increases the reference count on a <link linkend="GMainContext"><type>GMainContext</type></link> object by one.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-unref"/>g_main_context_unref ()</title>
<indexterm><primary>g_main_context_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_main_context_unref (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Decreases the reference count on a <link linkend="GMainContext"><type>GMainContext</type></link> object by one. If
the result is zero, free the context and free all associated memory.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-default"/>g_main_context_default ()</title>
<indexterm><primary>g_main_context_default</primary></indexterm><programlisting><link linkend="GMainContext">GMainContext</link>* g_main_context_default (void);</programlisting>
<para>
Returns the default main context. This is the main context used
for main loop functions when a main loop is not explicitly
specified.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the default main context.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-iteration"/>g_main_context_iteration ()</title>
<indexterm><primary>g_main_context_iteration</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_main_context_iteration (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="gboolean">gboolean</link> may_block);</programlisting>
<para>
Runs a single iteration for the given main loop. This involves
checking to see if any event sources are ready to be processed,
then if no events sources are ready and <parameter>may_block</parameter> is <literal>TRUE</literal>, waiting
for a source to become ready, then dispatching the highest priority
events sources that are ready. Note that even when <parameter>may_block</parameter> is <literal>TRUE</literal>,
it is still possible for <link linkend="g-main-context-iteration"><function>g_main_context_iteration()</function></link> to return
<literal>FALSE</literal>, since the the wait may be interrupted for other
reasons than an event source becoming ready.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (if <literal>NULL</literal>, the default context will be used)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>may_block</parameter> :</term>
<listitem><simpara> whether the call may block.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if events were dispatched.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-iteration"/>g_main_iteration()</title>
<indexterm role="deprecated"><primary>g_main_iteration</primary></indexterm><programlisting>#define g_main_iteration(may_block)</programlisting>
<warning><para><literal>g_main_iteration</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-main-context-iteration"><function>g_main_context_iteration()</function></link> instead.</para></warning>
<para>
Runs a single iteration for the default <link linkend="GMainContext"><type>GMainContext</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>may_block</parameter> :</term>
<listitem><simpara>set to <literal>TRUE</literal> 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 <literal>FALSE</literal> it will return immediately if no event source is ready to be
processed.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if more events are pending.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-pending"/>g_main_context_pending ()</title>
<indexterm><primary>g_main_context_pending</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_main_context_pending (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Checks if any sources have pending events for the given context.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (if <literal>NULL</literal>, the default context will be used)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if events are pending.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-pending"/>g_main_pending()</title>
<indexterm role="deprecated"><primary>g_main_pending</primary></indexterm><programlisting>#define g_main_pending()</programlisting>
<warning><para><literal>g_main_pending</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-main-context-pending"><function>g_main_context_pending()</function></link> instead.</para></warning>
<para>
Checks if any events are pending for the default <link linkend="GMainContext"><type>GMainContext</type></link>
(i.e. ready to be processed).
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if any events are pending.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-find-source-by-id"/>g_main_context_find_source_by_id ()</title>
<indexterm><primary>g_main_context_find_source_by_id</primary></indexterm><programlisting><link linkend="GSource">GSource</link>* g_main_context_find_source_by_id
(<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="guint">guint</link> source_id);</programlisting>
<para>
Finds a <link linkend="GSource"><type>GSource</type></link> given a pair of context and ID</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (if <literal>NULL</literal>, the default context will be used)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>source_id</parameter> :</term>
<listitem><simpara> the source ID, as returned by <link linkend="g-source-get-id"><function>g_source_get_id()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="GSource"><type>GSource</type></link> if found, otherwise, <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-find-source-by-user-data"/>g_main_context_find_source_by_user_data ()</title>
<indexterm><primary>g_main_context_find_source_by_user_data</primary></indexterm><programlisting><link linkend="GSource">GSource</link>* g_main_context_find_source_by_user_data
(<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Finds a source with the given user data for the callback. If
multiple sources exist with the same user data, the first
one found will be returned.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara> the user_data for the callback.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the source, if one was found, otherwise <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-find-source-by-funcs-user-data"/>g_main_context_find_source_by_funcs_user_data ()</title>
<indexterm><primary>g_main_context_find_source_by_funcs_user_data</primary></indexterm><programlisting><link linkend="GSource">GSource</link>* g_main_context_find_source_by_funcs_user_data
(<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="GSourceFuncs">GSourceFuncs</link> *funcs,
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Finds a source with the given source functions and user data. If
multiple sources exist with the same source function and user data,
the first one found will be returned.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (if <literal>NULL</literal>, the default context will be used).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>funcs</parameter> :</term>
<listitem><simpara> the <parameter>source_funcs</parameter> passed to <link linkend="g-source-new"><function>g_source_new()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara> the user data from the callback.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the source, if one was found, otherwise <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-wakeup"/>g_main_context_wakeup ()</title>
<indexterm><primary>g_main_context_wakeup</primary></indexterm><programlisting><link linkend="void">void</link> g_main_context_wakeup (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
If <parameter>context</parameter> is currently waiting in a <link linkend="poll"><function>poll()</function></link>, interrupt
the <link linkend="poll"><function>poll()</function></link>, and continue the iteration process.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-acquire"/>g_main_context_acquire ()</title>
<indexterm><primary>g_main_context_acquire</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_main_context_acquire (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Tries to become the owner of the specified context.
If some other context is the owner of the context,
returns <literal>FALSE</literal> immediately. Ownership is properly
recursive: the owner can require ownership again
and will release ownership when <link linkend="g-main-context-release"><function>g_main_context_release()</function></link>
is called as many times as <link linkend="g-main-context-acquire"><function>g_main_context_acquire()</function></link>.
</para>
<para>
You must be the owner of a context before you
can call <link linkend="g-main-context-prepare"><function>g_main_context_prepare()</function></link>, <link linkend="g-main-context-query"><function>g_main_context_query()</function></link>,
<link linkend="g-main-context-check"><function>g_main_context_check()</function></link>, <link linkend="g-main-context-dispatch"><function>g_main_context_dispatch()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if the operation succeeded, and
this thread is now the owner of <parameter>context</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-release"/>g_main_context_release ()</title>
<indexterm><primary>g_main_context_release</primary></indexterm><programlisting><link linkend="void">void</link> g_main_context_release (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Releases ownership of a context previously acquired by this thread
with <link linkend="g-main-context-acquire"><function>g_main_context_acquire()</function></link>. If the context was acquired multiple
times, the only release ownership when <link linkend="g-main-context-release"><function>g_main_context_release()</function></link>
is called as many times as it was acquired.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-wait"/>g_main_context_wait ()</title>
<indexterm><primary>g_main_context_wait</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_main_context_wait (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="GCond">GCond</link> *cond,
<link linkend="GMutex">GMutex</link> *mutex);</programlisting>
<para>
Tries to become the owner of the specified context,
as with <link linkend="g-main-context-acquire"><function>g_main_context_acquire()</function></link>. But if another thread
is the owner, atomically drop <parameter>mutex</parameter> and wait on <parameter>cond</parameter> until
that owner releases ownership or until <parameter>cond</parameter> is signaled, then
try again (once) to become the owner.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cond</parameter> :</term>
<listitem><simpara> a condition variable
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mutex</parameter> :</term>
<listitem><simpara> a mutex, currently held
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if the operation succeeded, and
this thread is now the owner of <parameter>context</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-prepare"/>g_main_context_prepare ()</title>
<indexterm><primary>g_main_context_prepare</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_main_context_prepare (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="gint">gint</link> *priority);</programlisting>
<para>
Prepares to poll sources within a main loop. The resulting information
for polling is determined by calling <link linkend="g-main-context-query"><function>g_main_context_query()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>priority</parameter> :</term>
<listitem><simpara> location to store priority of highest priority
source already ready.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if some source is ready to be dispatched
prior to polling.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-query"/>g_main_context_query ()</title>
<indexterm><primary>g_main_context_query</primary></indexterm><programlisting><link linkend="gint">gint</link> g_main_context_query (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="gint">gint</link> max_priority,
<link linkend="gint">gint</link> *timeout_,
<link linkend="GPollFD">GPollFD</link> *fds,
<link linkend="gint">gint</link> n_fds);</programlisting>
<para>
Determines information necessary to poll this main loop.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max_priority</parameter> :</term>
<listitem><simpara> maximum priority source to check
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>timeout_</parameter> :</term>
<listitem><simpara> location to store timeout to be used in polling
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fds</parameter> :</term>
<listitem><simpara> location to store <link linkend="GPollFD"><type>GPollFD</type></link> records that need to be polled.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_fds</parameter> :</term>
<listitem><simpara> length of <parameter>fds</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of records actually stored in <parameter>fds</parameter>,
or, if more than <parameter>n_fds</parameter> records need to be stored, the number
of records that need to be stored.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-check"/>g_main_context_check ()</title>
<indexterm><primary>g_main_context_check</primary></indexterm><programlisting><link linkend="gint">gint</link> g_main_context_check (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="gint">gint</link> max_priority,
<link linkend="GPollFD">GPollFD</link> *fds,
<link linkend="gint">gint</link> n_fds);</programlisting>
<para>
Passes the results of polling back to the main loop.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max_priority</parameter> :</term>
<listitem><simpara> the maximum numerical priority of sources to check
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fds</parameter> :</term>
<listitem><simpara> array of <link linkend="GPollFD"><type>GPollFD</type></link>'s that was passed to the last call to
<link linkend="g-main-context-query"><function>g_main_context_query()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_fds</parameter> :</term>
<listitem><simpara> return value of <link linkend="g-main-context-query"><function>g_main_context_query()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if some sources are ready to be dispatched.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-dispatch"/>g_main_context_dispatch ()</title>
<indexterm><primary>g_main_context_dispatch</primary></indexterm><programlisting><link linkend="void">void</link> g_main_context_dispatch (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Dispatches all pending sources.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-set-poll-func"/>g_main_context_set_poll_func ()</title>
<indexterm><primary>g_main_context_set_poll_func</primary></indexterm><programlisting><link linkend="void">void</link> g_main_context_set_poll_func (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="GPollFunc">GPollFunc</link> func);</programlisting>
<para>
Sets the function to use to handle polling of file descriptors. It
will be used instead of the <link linkend="poll"><function>poll()</function></link> system call
(or GLib's replacement function, which is used where
<link linkend="poll"><function>poll()</function></link> isn't available).
</para>
<para>
This function could possibly be used to integrate the GLib event
loop with an external event loop.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter> :</term>
<listitem><simpara> the function to call to poll all file descriptors
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-get-poll-func"/>g_main_context_get_poll_func ()</title>
<indexterm><primary>g_main_context_get_poll_func</primary></indexterm><programlisting><link linkend="GPollFunc">GPollFunc</link> g_main_context_get_poll_func (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Gets the poll function set by <link linkend="g-main-context-set-poll-func"><function>g_main_context_set_poll_func()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the poll function
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GPollFunc"/>GPollFunc ()</title>
<indexterm><primary>GPollFunc</primary></indexterm><programlisting><link linkend="gint">gint</link> (*GPollFunc) (<link linkend="GPollFD">GPollFD</link> *ufds,
<link linkend="guint">guint</link> nfsd,
<link linkend="gint">gint</link> timeout_);</programlisting>
<para>
Specifies the type of function passed to <link linkend="g-main-context-set-poll-func"><function>g_main_context_set_poll_func()</function></link>.
The semantics of the function should match those of the
<function><link linkend="poll"><function>poll()</function></link></function> system call.
</para><variablelist role="params">
<varlistentry><term><parameter>ufds</parameter> :</term>
<listitem><simpara>an array of <link linkend="GPollFD"><type>GPollFD</type></link> elements.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>nfsd</parameter> :</term>
<listitem><simpara>the number of elements in <parameter>ufds</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>timeout_</parameter> :</term>
<listitem><simpara>the maximum time to wait for an event of the file descriptors.
A negative value indicates an infinite timeout.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the number of <link linkend="GPollFD"><type>GPollFD</type></link> elements which have events or errors reported,
or -1 if an error occurred.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-add-poll"/>g_main_context_add_poll ()</title>
<indexterm><primary>g_main_context_add_poll</primary></indexterm><programlisting><link linkend="void">void</link> g_main_context_add_poll (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="GPollFD">GPollFD</link> *fd,
<link linkend="gint">gint</link> priority);</programlisting>
<para>
Adds a file descriptor to the set of file descriptors polled for
this context. This will very seldomly be used directly. Instead
a typical event source will use <link linkend="g-source-add-poll"><function>g_source_add_poll()</function></link> instead.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (or <literal>NULL</literal> for the default context)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fd</parameter> :</term>
<listitem><simpara> a <link linkend="GPollFD"><type>GPollFD</type></link> structure holding information about a file
descriptor to watch.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>priority</parameter> :</term>
<listitem><simpara> the priority for this file descriptor which should be
the same as the priority used for <link linkend="g-source-attach"><function>g_source_attach()</function></link> to ensure that the
file descriptor is polled whenever the results may be needed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-context-remove-poll"/>g_main_context_remove_poll ()</title>
<indexterm><primary>g_main_context_remove_poll</primary></indexterm><programlisting><link linkend="void">void</link> g_main_context_remove_poll (<link linkend="GMainContext">GMainContext</link> *context,
<link linkend="GPollFD">GPollFD</link> *fd);</programlisting>
<para>
Removes file descriptor from the set of file descriptors to be
polled for a particular context.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara>a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fd</parameter> :</term>
<listitem><simpara> a <link linkend="GPollFD"><type>GPollFD</type></link> descriptor previously added with <link linkend="g-main-context-add-poll"><function>g_main_context_add_poll()</function></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-depth"/>g_main_depth ()</title>
<indexterm><primary>g_main_depth</primary></indexterm><programlisting><link linkend="int">int</link> g_main_depth (void);</programlisting>
<para>
Return value: The main loop recursion level in the current thread</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the depth of the stack of calls to
<link linkend="g-main-context-dispatch"><function>g_main_context_dispatch()</function></link> on any <link linkend="GMainContext"><type>GMainContext</type></link> in the current thread.
That is, when called from the toplevel, it gives 0. When
called from within a callback from <link linkend="g-main-context-iteration"><function>g_main_context_iteration()</function></link>
(or <link linkend="g-main-loop-run"><function>g_main_loop_run()</function></link>, etc.) it returns 1. When called from within
a callback to a recursive call to <link linkend="g-main-context-iterate"><function>g_main_context_iterate()</function></link>,
it returns 2. And so forth.
This function is useful in a situation like the following:
Imagine an extremely simple "garbage collected" system.
<example>
static GList *free_list;
gpointer
allocate_memory (gsize size)
{
gpointer result = g_malloc (size);
free_list = g_list_prepend (free_list, result);
return result;
}
void
free_allocated_memory (void)
{
GList *l;
for (l = free_list; l; l = l->next);
g_free (l->data);
g_list_free (free_list);
free_list = NULL;
}
[...]
while (TRUE);
{
g_main_context_iteration (NULL, TRUE);
<link linkend="free-allocated-memory"><function>free_allocated_memory()</function></link>;
}
</example>
This works from an application, however, if you want to do the same
thing from a library, it gets more difficult, since you no longer
control the main loop. You might think you can simply use an idle
function to make the call to <link linkend="free-allocated-memory"><function>free_allocated_memory()</function></link>, but that
doesn't work, since the idle function could be called from a
recursive callback. This can be fixed by using <link linkend="g-main-depth"><function>g_main_depth()</function></link>
<example>
gpointer
allocate_memory (gsize size)
{
FreeListBlock *block = g_new (FreeListBlock, 1);\
block->mem = g_malloc (size);
block->depth = <link linkend="g-main-depth"><function>g_main_depth()</function></link>;
free_list = g_list_prepend (free_list, block);
return block->mem;
}
void
free_allocated_memory (void)
{
GList *l;
int depth = <link linkend="g-main-depth"><function>g_main_depth()</function></link>;
for (l = free_list; l; );
{
GList *next = l->next;
FreeListBlock *block = l->data;
if (block->depth > depth)
{
g_free (block->mem);
g_free (block);
free_list = g_list_delete_link (free_list, l);
}
l = next;
}
}
</example>
There is a temptation to use <link linkend="g-main-depth"><function>g_main_depth()</function></link> to solve
problems with reentrancy. For instance, while waiting for data
to be received from the network in response to a menu item,
the menu item might be selected again. It might seem that
one could make the menu item's callback return immediately
and do nothing if <link linkend="g-main-depth"><function>g_main_depth()</function></link> returns a value greater than 1.
However, this should be avoided since the user then sees selecting
the menu item do nothing. Furthermore, you'll find yourself adding
these checks all over your code, since there are doubtless many,
many things that the user could do. Instead, you can use the
following techniques:
<orderedlist>
<listitem>
<para>
Use <link linkend="gtk-widget-set-sensitive"><function>gtk_widget_set_sensitive()</function></link> or modal dialogs to prevent
the user from interacting with elements while the main
loop is recursing.
</para>
</listitem>
<listitem>
<para>
Avoid main loop recursion in situations where you can't handle
arbitrary callbacks. Instead, structure your code so that you
simply return to the main loop and then get called again when
there is more work to do.
</para>
</listitem>
</orderedlist>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-main-set-poll-func"/>g_main_set_poll_func()</title>
<indexterm role="deprecated"><primary>g_main_set_poll_func</primary></indexterm><programlisting>#define g_main_set_poll_func(func)</programlisting>
<warning><para><literal>g_main_set_poll_func</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-main-context-set-poll-func"><function>g_main_context_set_poll_func()</function></link> instead.</para></warning>
<para>
Sets the function to use for the handle polling of file descriptors
for the default main context.
</para><variablelist role="params">
<varlistentry><term><parameter>func</parameter> :</term>
<listitem><simpara>the function to call to poll all file descriptors.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-timeout-source-new"/>g_timeout_source_new ()</title>
<indexterm><primary>g_timeout_source_new</primary></indexterm><programlisting><link linkend="GSource">GSource</link>* g_timeout_source_new (<link linkend="guint">guint</link> interval);</programlisting>
<para>
Creates a new timeout source.
</para>
<para>
The source will not initially be associated with any <link linkend="GMainContext"><type>GMainContext</type></link>
and must be added to one with <link linkend="g-source-attach"><function>g_source_attach()</function></link> before it will be
executed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>interval</parameter> :</term>
<listitem><simpara> the timeout interval in milliseconds.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly-created timeout source
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-timeout-add"/>g_timeout_add ()</title>
<indexterm><primary>g_timeout_add</primary></indexterm><programlisting><link linkend="guint">guint</link> g_timeout_add (<link linkend="guint">guint</link> interval,
<link linkend="GSourceFunc">GSourceFunc</link> function,
<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Sets a function to be called at regular intervals, with the default
priority, <link linkend="G-PRIORITY-DEFAULT-CAPS"><type>G_PRIORITY_DEFAULT</type></link>. The function is called repeatedly
until it returns <literal>FALSE</literal>, at which point the timeout is automatically
destroyed and the function will not be called again. The first call
to the function will be at the end of the first <parameter>interval</parameter>.
</para>
<para>
Note that timeout functions may be delayed, due to the processing of other
event sources. Thus they should not be relied on for precise timing.
After each call to the timeout function, the time of the next
timeout is recalculated based on the current time and the given interval
(it does not try to 'catch up' time lost in delays).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>interval</parameter> :</term>
<listitem><simpara> the time between calls to the function, in milliseconds
(1/1000ths of a second)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter> :</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara> data to pass to <parameter>function</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the id of event source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-timeout-add-full"/>g_timeout_add_full ()</title>
<indexterm><primary>g_timeout_add_full</primary></indexterm><programlisting><link linkend="guint">guint</link> g_timeout_add_full (<link linkend="gint">gint</link> priority,
<link linkend="guint">guint</link> interval,
<link linkend="GSourceFunc">GSourceFunc</link> function,
<link linkend="gpointer">gpointer</link> data,
<link linkend="GDestroyNotify">GDestroyNotify</link> notify);</programlisting>
<para>
Sets a function to be called at regular intervals, with the given
priority. The function is called repeatedly until it returns
<literal>FALSE</literal>, at which point the timeout is automatically destroyed and
the function will not be called again. The <parameter>notify</parameter> function is
called when the timeout is destroyed. The first call to the
function will be at the end of the first <parameter>interval</parameter>.
</para>
<para>
Note that timeout functions may be delayed, due to the processing of other
event sources. Thus they should not be relied on for precise timing.
After each call to the timeout function, the time of the next
timeout is recalculated based on the current time and the given interval
(it does not try to 'catch up' time lost in delays).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>priority</parameter> :</term>
<listitem><simpara> the priority of the idle source. Typically this will be in the
range between <link linkend="G-PRIORITY-DEFAULT-IDLE-CAPS"><type>G_PRIORITY_DEFAULT_IDLE</type></link> and <link linkend="G-PRIORITY-HIGH-IDLE-CAPS"><type>G_PRIORITY_HIGH_IDLE</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>interval</parameter> :</term>
<listitem><simpara> the time between calls to the function, in milliseconds
(1/1000ths of a second)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter> :</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara> data to pass to <parameter>function</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter> :</term>
<listitem><simpara> function to call when the idle is removed, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the id of event source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-idle-source-new"/>g_idle_source_new ()</title>
<indexterm><primary>g_idle_source_new</primary></indexterm><programlisting><link linkend="GSource">GSource</link>* g_idle_source_new (void);</programlisting>
<para>
Creates a new idle source.
</para>
<para>
The source will not initially be associated with any <link linkend="GMainContext"><type>GMainContext</type></link>
and must be added to one with <link linkend="g-source-attach"><function>g_source_attach()</function></link> before it will be
executed. Note that the default priority for idle sources is
<literal>G_PRIORITY_DEFAULT_IDLE</literal>, as compared to other sources which
have a default priority of <literal>G_PRIORITY_DEFAULT</literal>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly-created idle source
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-idle-add"/>g_idle_add ()</title>
<indexterm><primary>g_idle_add</primary></indexterm><programlisting><link linkend="guint">guint</link> g_idle_add (<link linkend="GSourceFunc">GSourceFunc</link> function,
<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Adds a function to be called whenever there are no higher priority
events pending to the default main loop. The function is given the
default idle priority, <link linkend="G-PRIORITY-DEFAULT-IDLE-CAPS"><type>G_PRIORITY_DEFAULT_IDLE</type></link>. If the function
returns <literal>FALSE</literal> it is automatically removed from the list of event
sources and will not be called again.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>function</parameter> :</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara> data to pass to <parameter>function</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the id of the event source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-idle-add-full"/>g_idle_add_full ()</title>
<indexterm><primary>g_idle_add_full</primary></indexterm><programlisting><link linkend="guint">guint</link> g_idle_add_full (<link linkend="gint">gint</link> priority,
<link linkend="GSourceFunc">GSourceFunc</link> function,
<link linkend="gpointer">gpointer</link> data,
<link linkend="GDestroyNotify">GDestroyNotify</link> notify);</programlisting>
<para>
Adds a function to be called whenever there are no higher priority
events pending. If the function returns <literal>FALSE</literal> it is automatically
removed from the list of event sources and will not be called again.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>priority</parameter> :</term>
<listitem><simpara> the priority of the idle source. Typically this will be in the
range btweeen <link linkend="G-PRIORITY-DEFAULT-IDLE-CAPS"><type>G_PRIORITY_DEFAULT_IDLE</type></link> and <link linkend="G-PRIORITY-HIGH-IDLE-CAPS"><type>G_PRIORITY_HIGH_IDLE</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter> :</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara> data to pass to <parameter>function</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter> :</term>
<listitem><simpara> function to call when the idle is removed, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the id of the event source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-idle-remove-by-data"/>g_idle_remove_by_data ()</title>
<indexterm><primary>g_idle_remove_by_data</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_idle_remove_by_data (<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Removes the idle function with the given data.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara> the data for the idle source's callback.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if an idle source was found and removed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GPid"/>GPid</title>
<indexterm><primary>GPid</primary></indexterm><programlisting>typedef int GPid;
</programlisting>
<para>
</para></refsect2>
<refsect2>
<title><anchor id="GChildWatchFunc"/>GChildWatchFunc ()</title>
<indexterm><primary>GChildWatchFunc</primary></indexterm><programlisting><link linkend="void">void</link> (*GChildWatchFunc) (<link linkend="GPid">GPid</link> pid,
<link linkend="gint">gint</link> status,
<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>pid</parameter> :</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>status</parameter> :</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-child-watch-source-new"/>g_child_watch_source_new ()</title>
<indexterm role="2.4"><primary>g_child_watch_source_new</primary></indexterm><programlisting><link linkend="GSource">GSource</link>* g_child_watch_source_new (<link linkend="GPid">GPid</link> pid);</programlisting>
<para>
Creates a new child_watch source.
</para>
<para>
The source will not initially be associated with any <link linkend="GMainContext"><type>GMainContext</type></link>
and must be added to one with <link linkend="g-source-attach"><function>g_source_attach()</function></link> before it will be
executed.
</para>
<para>
Note that on platforms where <link linkend="GPid"><type>GPid</type></link> must be explicitely closed
(see <link linkend="g-spawn-close-pid"><function>g_spawn_close_pid()</function></link>) <parameter>pid</parameter> must not be closed while the
source is still active. Typically, you will want to call
<link linkend="g-spawn-close-pid"><function>g_spawn_close_pid()</function></link> in the callback function for the source.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>pid</parameter> :</term>
<listitem><simpara> process id of a child process to watch. On Windows, a HANDLE
for the process to watch (which actually doesn't have to be a child).
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly-created child watch source
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="g-child-watch-add"/>g_child_watch_add ()</title>
<indexterm role="2.4"><primary>g_child_watch_add</primary></indexterm><programlisting><link linkend="guint">guint</link> g_child_watch_add (<link linkend="GPid">GPid</link> pid,
<link linkend="GChildWatchFunc">GChildWatchFunc</link> function,
<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Sets a function to be called when the child indicated by <parameter>pid</parameter> exits, at a
default priority, <link linkend="G-PRIORITY-DEFAULT-CAPS"><type>G_PRIORITY_DEFAULT</type></link>.
</para>
<para>
Note that on platforms where <link linkend="GPid"><type>GPid</type></link> must be explicitely closed
(see <link linkend="g-spawn-close-pid"><function>g_spawn_close_pid()</function></link>) <parameter>pid</parameter> must not be closed while the
source is still active. Typically, you will want to call
<link linkend="g-spawn-close-pid"><function>g_spawn_close_pid()</function></link> in the callback function for the source.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>pid</parameter> :</term>
<listitem><simpara> process id of a child process to watch
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter> :</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara> data to pass to <parameter>function</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the id of event source.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="g-child-watch-add-full"/>g_child_watch_add_full ()</title>
<indexterm role="2.4"><primary>g_child_watch_add_full</primary></indexterm><programlisting><link linkend="guint">guint</link> g_child_watch_add_full (<link linkend="gint">gint</link> priority,
<link linkend="GPid">GPid</link> pid,
<link linkend="GChildWatchFunc">GChildWatchFunc</link> function,
<link linkend="gpointer">gpointer</link> data,
<link linkend="GDestroyNotify">GDestroyNotify</link> notify);</programlisting>
<para>
Sets a function to be called when the child indicated by <parameter>pid</parameter> exits, at a
default priority, <link linkend="G-PRIORITY-DEFAULT-CAPS"><type>G_PRIORITY_DEFAULT</type></link>.
</para>
<para>
Note that on platforms where <link linkend="GPid"><type>GPid</type></link> must be explicitely closed
(see <link linkend="g-spawn-close-pid"><function>g_spawn_close_pid()</function></link>) <parameter>pid</parameter> must not be closed while the
source is still active. Typically, you will want to call
<link linkend="g-spawn-close-pid"><function>g_spawn_close_pid()</function></link> in the callback function for the source.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>priority</parameter> :</term>
<listitem><simpara> the priority of the idle source. Typically this will be in the
range between <link linkend="G-PRIORITY-DEFAULT-IDLE-CAPS"><type>G_PRIORITY_DEFAULT_IDLE</type></link> and <link linkend="G-PRIORITY-HIGH-IDLE-CAPS"><type>G_PRIORITY_HIGH_IDLE</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pid</parameter> :</term>
<listitem><simpara> process id of a child process to watch
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter> :</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara> data to pass to <parameter>function</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter> :</term>
<listitem><simpara> function to call when the idle is removed, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the id of event source.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="GPollFD"/>struct GPollFD</title>
<indexterm><primary>GPollFD</primary></indexterm><programlisting>struct GPollFD {
gint fd;
gushort events;
gushort revents;
};
</programlisting>
<para>
<informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
<tbody>
<row>
<entry><link linkend="gint"><type>gint</type></link> fd;</entry>
<entry>the file descriptor to poll (or a <type>HANDLE</type> on Win32 platforms).</entry>
</row>
<row>
<entry><link linkend="gushort"><type>gushort</type></link> events;</entry>
<entry>a bitwise combination of flags from <link linkend="GIOCondition"><type>GIOCondition</type></link>, specifying which
events should be polled for. Typically for reading from a file descriptor
you would use <literal>G_IO_IN</literal> | <literal>G_IO_HUP</literal> | <literal>G_IO_ERR</literal>, and for writing you would use
<literal>G_IO_OUT</literal> | <literal>G_IO_ERR</literal>.
</entry>
</row>
<row>
<entry><link linkend="gushort"><type>gushort</type></link> revents;</entry>
<entry>a bitwise combination of flags from <link linkend="GIOCondition"><type>GIOCondition</type></link>, returned from the
<function><link linkend="poll"><function>poll()</function></link></function> function to indicate which events occurred.
</entry>
</row>
</tbody></tgroup></informaltable>
</para></refsect2>
<refsect2>
<title><anchor id="GSource"/>struct GSource</title>
<indexterm><primary>GSource</primary></indexterm><programlisting>struct GSource {
};
</programlisting>
<para>
The <structname>GSource</structname> struct is an opaque data type representing
an event source.
</para></refsect2>
<refsect2>
<title><anchor id="GSourceDummyMarshal"/>GSourceDummyMarshal ()</title>
<indexterm><primary>GSourceDummyMarshal</primary></indexterm><programlisting><link linkend="void">void</link> (*GSourceDummyMarshal) (void);</programlisting>
<para>
This is just a placeholder for <link linkend="GClosureMarshal"><type>GClosureMarshal</type></link>, which cannot be used here
for dependency reasons.
</para></refsect2>
<refsect2>
<title><anchor id="GSourceFuncs"/>struct GSourceFuncs</title>
<indexterm><primary>GSourceFuncs</primary></indexterm><programlisting>struct GSourceFuncs {
gboolean (*prepare) (GSource *source,
gint *timeout_);
gboolean (*check) (GSource *source);
gboolean (*dispatch) (GSource *source,
GSourceFunc callback,
gpointer user_data);
void (*finalize) (GSource *source); /* Can be NULL */
/* For use by g_source_set_closure */
GSourceFunc closure_callback;
GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
};
</programlisting>
<para>
The <link linkend="GSourceFuncs"><type>GSourceFuncs</type></link> struct contains a table of functions used to handle
event sources in a generic manner.
<informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
<tbody>
<row>
<entry>prepare</entry>
<entry>
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 <function><link linkend="poll"><function>poll()</function></link></function> call) it should return <literal>TRUE</literal>.
It can also return a <parameter>timeout_</parameter> value which should be the maximum timeout
(in milliseconds) which should be passed to the <function><link linkend="poll"><function>poll()</function></link></function> call.
The actual timeout used will be -1 if all sources returned -1, or it will
be the minimum of all the <parameter>timeout_</parameter> values returned which were >= 0.
</entry>
</row>
<row>
<entry>check</entry>
<entry>
Called after all the file descriptors are polled.
The source should return <literal>TRUE</literal> 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.
</entry>
</row>
<row>
<entry>dispatch</entry>
<entry>
Called to dispatch the event source, after it has returned <literal>TRUE</literal> in
either its <parameter>prepare</parameter> or its <parameter>check</parameter> function. The <parameter>dispatch</parameter> function is
passed in a callback function and data. The callback function may be
<literal>NULL</literal> if the source was never connected to a callback using
<link linkend="g-source-set-callback"><function>g_source_set_callback()</function></link>. The <parameter>dispatch</parameter> function should call the
callback function with <parameter>user_data</parameter> and whatever additional parameters are
needed for this type of event source.
</entry>
</row>
<row>
<entry>finalize</entry>
<entry>
Called when the source is finalized.
</entry>
</row>
</tbody></tgroup></informaltable>
</para>
<para>
For idle sources, the prepare and check functions always return <literal>TRUE</literal> 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
<function><link linkend="poll"><function>poll()</function></link></function> call doesn't block (since that would be time
wasted which could have been spent running the idle function).
</para>
<para>
For timeout sources, the prepare and check functions both return <literal>TRUE</literal> if the
timeout interval has expired. The prepare function also returns a timeout
value to ensure that the <function><link linkend="poll"><function>poll()</function></link></function> call doesn't block too
long and miss the next timeout.
</para>
<para>
For file descriptor sources, the prepare function typically returns <literal>FALSE</literal>,
since it must wait until <function><link linkend="poll"><function>poll()</function></link></function> 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
<function><link linkend="poll"><function>poll()</function></link></function> call blocks.
In the check function, it tests the results of the <function><link linkend="poll"><function>poll()</function></link></function>
call to see if the required condition has been met, and returns <literal>TRUE</literal> if so.
</para></refsect2>
<refsect2>
<title><anchor id="GSourceCallbackFuncs"/>struct GSourceCallbackFuncs</title>
<indexterm><primary>GSourceCallbackFuncs</primary></indexterm><programlisting>struct GSourceCallbackFuncs {
void (*ref) (gpointer cb_data);
void (*unref) (gpointer cb_data);
void (*get) (gpointer cb_data,
GSource *source,
GSourceFunc *func,
gpointer *data);
};
</programlisting>
<para>
The <structname>GSourceCallbackFuncs</structname> struct contains
functions for managing callback objects.
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="void">void</link> (*<structfield>ref</structfield>) (gpointer cb_data)</term>
<listitem><simpara>Called when a reference is added to the callback object.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="void">void</link> (*<structfield>unref</structfield>) (gpointer cb_data)</term>
<listitem><simpara>Called when a reference to the callback object is dropped.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="void">void</link> (*<structfield>get</structfield>) (gpointer cb_data,
GSource *source,
GSourceFunc *func,
gpointer *data)</term>
<listitem><simpara>Called to extract the callback function and data from the callback object.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-new"/>g_source_new ()</title>
<indexterm><primary>g_source_new</primary></indexterm><programlisting><link linkend="GSource">GSource</link>* g_source_new (<link linkend="GSourceFuncs">GSourceFuncs</link> *source_funcs,
<link linkend="guint">guint</link> struct_size);</programlisting>
<para>
Creates a new <link linkend="GSource"><type>GSource</type></link> structure. The size is specified to
allow creating structures derived from <link linkend="GSource"><type>GSource</type></link> that contain
additional data. The size passed in must be at least
<literal>sizeof (GSource)</literal>.
</para>
<para>
The source will not initially be associated with any <link linkend="GMainContext"><type>GMainContext</type></link>
and must be added to one with <link linkend="g-source-attach"><function>g_source_attach()</function></link> before it will be
executed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source_funcs</parameter> :</term>
<listitem><simpara> structure containing functions that implement
the sources behavior.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>struct_size</parameter> :</term>
<listitem><simpara> size of the <link linkend="GSource"><type>GSource</type></link> structure to create.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly-created <link linkend="GSource"><type>GSource</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-ref"/>g_source_ref ()</title>
<indexterm><primary>g_source_ref</primary></indexterm><programlisting><link linkend="GSource">GSource</link>* g_source_ref (<link linkend="GSource">GSource</link> *source);</programlisting>
<para>
Increases the reference count on a source by one.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>source</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-unref"/>g_source_unref ()</title>
<indexterm><primary>g_source_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_source_unref (<link linkend="GSource">GSource</link> *source);</programlisting>
<para>
Decreases the reference count of a source by one. If the
resulting reference count is zero the source and associated
memory will be destroyed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-attach"/>g_source_attach ()</title>
<indexterm><primary>g_source_attach</primary></indexterm><programlisting><link linkend="guint">guint</link> g_source_attach (<link linkend="GSource">GSource</link> *source,
<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Adds a <link linkend="GSource"><type>GSource</type></link> to a <parameter>context</parameter> so that it will be executed within
that context.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>context</parameter> :</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (if <literal>NULL</literal>, the default context will be used)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the ID for the source within the <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-destroy"/>g_source_destroy ()</title>
<indexterm><primary>g_source_destroy</primary></indexterm><programlisting><link linkend="void">void</link> g_source_destroy (<link linkend="GSource">GSource</link> *source);</programlisting>
<para>
Removes a source from its <link linkend="GMainContext"><type>GMainContext</type></link>, if any, and mark it as
destroyed. The source cannot be subsequently added to another
context.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-set-priority"/>g_source_set_priority ()</title>
<indexterm><primary>g_source_set_priority</primary></indexterm><programlisting><link linkend="void">void</link> g_source_set_priority (<link linkend="GSource">GSource</link> *source,
<link linkend="gint">gint</link> priority);</programlisting>
<para>
Sets the priority of a source. While the main loop is being
run, a source will be dispatched if it is ready to be dispatched and no sources
at a higher (numerically smaller) priority are ready to be dispatched.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>priority</parameter> :</term>
<listitem><simpara> the new priority.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-get-priority"/>g_source_get_priority ()</title>
<indexterm><primary>g_source_get_priority</primary></indexterm><programlisting><link linkend="gint">gint</link> g_source_get_priority (<link linkend="GSource">GSource</link> *source);</programlisting>
<para>
Gets the priority of a source.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the priority of the source
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-set-can-recurse"/>g_source_set_can_recurse ()</title>
<indexterm><primary>g_source_set_can_recurse</primary></indexterm><programlisting><link linkend="void">void</link> g_source_set_can_recurse (<link linkend="GSource">GSource</link> *source,
<link linkend="gboolean">gboolean</link> can_recurse);</programlisting>
<para>
Sets whether a source can be called recursively. If <parameter>can_recurse</parameter> is
<literal>TRUE</literal>, then while the source is being dispatched then this source
will be processed normally. Otherwise, all processing of this
source is blocked until the dispatch function returns.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>can_recurse</parameter> :</term>
<listitem><simpara> whether recursion is allowed for this source
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-get-can-recurse"/>g_source_get_can_recurse ()</title>
<indexterm><primary>g_source_get_can_recurse</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_source_get_can_recurse (<link linkend="GSource">GSource</link> *source);</programlisting>
<para>
Checks whether a source is allowed to be called recursively.
see <link linkend="g-source-set-can-recurse"><function>g_source_set_can_recurse()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> whether recursion is allowed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-get-id"/>g_source_get_id ()</title>
<indexterm><primary>g_source_get_id</primary></indexterm><programlisting><link linkend="guint">guint</link> g_source_get_id (<link linkend="GSource">GSource</link> *source);</programlisting>
<para>
Returns the numeric ID for a particular source. The ID of a source
is unique within a particular main loop context. The reverse
mapping from ID to source is done by <link linkend="g-main-context-find-source-by-id"><function>g_main_context_find_source_by_id()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the ID for the source
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-get-context"/>g_source_get_context ()</title>
<indexterm><primary>g_source_get_context</primary></indexterm><programlisting><link linkend="GMainContext">GMainContext</link>* g_source_get_context (<link linkend="GSource">GSource</link> *source);</programlisting>
<para>
Gets the <link linkend="GMainContext"><type>GMainContext</type></link> with which the source is associated.
Calling this function on a destroyed source is an error.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="GMainContext"><type>GMainContext</type></link> with which the source is associated,
or <literal>NULL</literal> if the context has not yet been added
to a source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-set-callback"/>g_source_set_callback ()</title>
<indexterm><primary>g_source_set_callback</primary></indexterm><programlisting><link linkend="void">void</link> g_source_set_callback (<link linkend="GSource">GSource</link> *source,
<link linkend="GSourceFunc">GSourceFunc</link> func,
<link linkend="gpointer">gpointer</link> data,
<link linkend="GDestroyNotify">GDestroyNotify</link> notify);</programlisting>
<para>
Sets the callback function for a source. The callback for a source is
called from the source's dispatch function.
</para>
<para>
The exact type of <parameter>func</parameter> depends on the type of source; ie. you
should not count on <parameter>func</parameter> being called with <parameter>data</parameter> as its first
parameter.
</para>
<para>
Typically, you won't use this function. Instead use functions specific
to the type of source you are using.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> the source
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter> :</term>
<listitem><simpara> a callback function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara> the data to pass to callback function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter> :</term>
<listitem><simpara> a function to call when <parameter>data</parameter> is no longer in use, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GSourceFunc"/>GSourceFunc ()</title>
<indexterm><primary>GSourceFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> (*GSourceFunc) (<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Specifies the type of function passed to <link linkend="g-timeout-add"><function>g_timeout_add()</function></link>, <link linkend="g-timeout-add-full"><function>g_timeout_add_full()</function></link>,
<link linkend="g-idle-add"><function>g_idle_add()</function></link>, and <link linkend="g-idle-add-full"><function>g_idle_add_full()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara>data passed to the function, set when the source was created with one
of the above functions.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>it should return <literal>FALSE</literal> if the source should be removed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-set-callback-indirect"/>g_source_set_callback_indirect ()</title>
<indexterm><primary>g_source_set_callback_indirect</primary></indexterm><programlisting><link linkend="void">void</link> g_source_set_callback_indirect (<link linkend="GSource">GSource</link> *source,
<link linkend="gpointer">gpointer</link> callback_data,
<link linkend="GSourceCallbackFuncs">GSourceCallbackFuncs</link> *callback_funcs);</programlisting>
<para>
Sets the callback function storing the data as a refcounted callback
"object". This is used internally. Note that calling
<link linkend="g-source-set-callback-indirect"><function>g_source_set_callback_indirect()</function></link> assumes
an initial reference count on <parameter>callback_data</parameter>, and thus
<parameter>callback_funcs->unref</parameter> will eventually be called once more
than <parameter>callback_funcs->ref</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> the source
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback_data</parameter> :</term>
<listitem><simpara> pointer to callback data "object"
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback_funcs</parameter> :</term>
<listitem><simpara> functions for reference counting <parameter>callback_data</parameter>
and getting the callback and data
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-add-poll"/>g_source_add_poll ()</title>
<indexterm><primary>g_source_add_poll</primary></indexterm><programlisting><link linkend="void">void</link> g_source_add_poll (<link linkend="GSource">GSource</link> *source,
<link linkend="GPollFD">GPollFD</link> *fd);</programlisting>
<para>
Adds a file descriptor to the set of file descriptors polled for
this source. This is usually combined with <link linkend="g-source-new"><function>g_source_new()</function></link> to add an
event source. The event source's check function will typically test
the <parameter>revents</parameter> field in the <link linkend="GPollFD"><type>GPollFD</type></link> struct and return <literal>TRUE</literal> if events need
to be processed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara>a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fd</parameter> :</term>
<listitem><simpara> a <link linkend="GPollFD"><type>GPollFD</type></link> structure holding information about a file
descriptor to watch.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-remove-poll"/>g_source_remove_poll ()</title>
<indexterm><primary>g_source_remove_poll</primary></indexterm><programlisting><link linkend="void">void</link> g_source_remove_poll (<link linkend="GSource">GSource</link> *source,
<link linkend="GPollFD">GPollFD</link> *fd);</programlisting>
<para>
Removes a file descriptor from the set of file descriptors polled for
this source.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara>a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fd</parameter> :</term>
<listitem><simpara> a <link linkend="GPollFD"><type>GPollFD</type></link> structure previously passed to <link linkend="g-source-add-poll"><function>g_source_add_poll()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-get-current-time"/>g_source_get_current_time ()</title>
<indexterm><primary>g_source_get_current_time</primary></indexterm><programlisting><link linkend="void">void</link> g_source_get_current_time (<link linkend="GSource">GSource</link> *source,
<link linkend="GTimeVal">GTimeVal</link> *timeval);</programlisting>
<para>
Gets the "current time" to be used when checking
this source. The advantage of calling this function over
calling <link linkend="g-get-current-time"><function>g_get_current_time()</function></link> directly is that when
checking multiple sources, GLib can cache a single value
instead of having to repeatedly get the system time.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>timeval</parameter> :</term>
<listitem><simpara> <link linkend="GTimeVal"><type>GTimeVal</type></link> structure in which to store current time.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-remove"/>g_source_remove ()</title>
<indexterm><primary>g_source_remove</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_source_remove (<link linkend="guint">guint</link> tag);</programlisting>
<para>
Removes the source with the given id from the default main context. The id of
a <link linkend="GSource"><type>GSource</type></link> is given by <link linkend="g-source-get-id"><function>g_source_get_id()</function></link>, or will be returned by the
functions <link linkend="g-source-attach"><function>g_source_attach()</function></link>, <link linkend="g-idle-add"><function>g_idle_add()</function></link>, <link linkend="g-idle-add-full"><function>g_idle_add_full()</function></link>,
<link linkend="g-timeout-add"><function>g_timeout_add()</function></link>, <link linkend="g-timeout-add-full"><function>g_timeout_add_full()</function></link>, <link linkend="g-child-watch-add"><function>g_child_watch_add()</function></link>,
<link linkend="g-child-watch-add-full"><function>g_child_watch_add_full()</function></link>, <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link>, and <link linkend="g-io-add-watch-full"><function>g_io_add_watch_full()</function></link>.
</para>
<para>
See also <link linkend="g-source-destroy"><function>g_source_destroy()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tag</parameter> :</term>
<listitem><simpara> the id of the source to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if the source was found and removed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-remove-by-funcs-user-data"/>g_source_remove_by_funcs_user_data ()</title>
<indexterm><primary>g_source_remove_by_funcs_user_data</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_source_remove_by_funcs_user_data
(<link linkend="GSourceFuncs">GSourceFuncs</link> *funcs,
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Removes a source from the default main loop context given the
source functions and user data. If multiple sources exist with the
same source functions and user data, only one will be destroyed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>funcs</parameter> :</term>
<listitem><simpara> The <parameter>source_funcs</parameter> passed to <link linkend="g-source-new"><function>g_source_new()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara> the user data for the callback
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if a source was found and removed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-source-remove-by-user-data"/>g_source_remove_by_user_data ()</title>
<indexterm><primary>g_source_remove_by_user_data</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_source_remove_by_user_data (<link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Removes a source from the default main loop context given the user
data for the callback. If multiple sources exist with the same user
data, only one will be destroyed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara> the user_data for the callback.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if a source was found and removed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
</refentry>