<refentry id="glib-The-Main-Event-Loop">
<refmeta>
<refentrytitle role="top_of_page" id="glib-The-Main-Event-Loop.top_of_page">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 id="glib-The-Main-Event-Loop.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

                    <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>

                    <link linkend="GMainContext">GMainContext</link>;
<link linkend="GMainContext">GMainContext</link> *      <link linkend="g-main-context-new">g_main_context_new</link>                  (void);
<link linkend="GMainContext">GMainContext</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-is-owner">g_main_context_is_owner</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="gint">gint</link>                <link linkend="g-main-depth">g_main_depth</link>                        (void);
<link linkend="GSource">GSource</link> *           <link linkend="g-main-current-source">g_main_current_source</link>               (void);
#define             <link linkend="g-main-set-poll-func">g_main_set_poll_func</link>                (func)

<link linkend="GMainContext">GMainContext</link> *      <link linkend="g-main-context-get-thread-default">g_main_context_get_thread_default</link>   (void);
<link linkend="void">void</link>                <link linkend="g-main-context-push-thread-default">g_main_context_push_thread_default</link>  (<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="void">void</link>                <link linkend="g-main-context-pop-thread-default">g_main_context_pop_thread_default</link>   (<link linkend="GMainContext">GMainContext</link> *context);

<link linkend="GSource">GSource</link> *           <link linkend="g-timeout-source-new">g_timeout_source_new</link>                (<link linkend="guint">guint</link> interval);
<link linkend="GSource">GSource</link> *           <link linkend="g-timeout-source-new-seconds">g_timeout_source_new_seconds</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="guint">guint</link>               <link linkend="g-timeout-add-seconds">g_timeout_add_seconds</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-seconds-full">g_timeout_add_seconds_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);

                    <link linkend="GPollFD">GPollFD</link>;
<link linkend="gint">gint</link>                <link linkend="g-poll">g_poll</link>                              (<link linkend="GPollFD">GPollFD</link> *fds,
                                                         <link linkend="guint">guint</link> nfds,
                                                         <link linkend="gint">gint</link> timeout);

                    <link linkend="GSource">GSource</link>;
<link linkend="void">void</link>                (<link linkend="GSourceDummyMarshal">*GSourceDummyMarshal</link>)              (void);
                    <link linkend="GSourceFuncs">GSourceFuncs</link>;
                    <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="void">void</link>                <link linkend="g-source-set-funcs">g_source_set_funcs</link>                  (<link linkend="GSource">GSource</link> *source,
                                                         <link linkend="GSourceFuncs">GSourceFuncs</link> *funcs);
<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="gboolean">gboolean</link>            <link linkend="g-source-is-destroyed">g_source_is_destroyed</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 id="glib-The-Main-Event-Loop.description" role="desc">
<title role="desc.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 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 id="glib-The-Main-Event-Loop.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GMainLoop" role="struct">
<title>GMainLoop</title>
<indexterm zone="GMainLoop"><primary sortas="MainLoop">GMainLoop</primary></indexterm><programlisting>typedef struct _GMainLoop 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 id="g-main-loop-new" role="function">
<title>g_main_loop_new ()</title>
<indexterm zone="g-main-loop-new"><primary sortas="main_loop_new">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>  (if <link linkend="NULL--CAPS"><literal>NULL</literal></link>, the default context will be used).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>is_running</parameter>&#160;:</term>
<listitem><simpara> set to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> 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
<link linkend="TRUE--CAPS"><literal>TRUE</literal></link> anyway.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-loop-ref" role="function">
<title>g_main_loop_ref ()</title>
<indexterm zone="g-main-loop-ref"><primary sortas="main_loop_ref">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainLoop"><type>GMainLoop</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <parameter>loop</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-loop-unref" role="function">
<title>g_main_loop_unref ()</title>
<indexterm zone="g-main-loop-unref"><primary sortas="main_loop_unref">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainLoop"><type>GMainLoop</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-loop-run" role="function">
<title>g_main_loop_run ()</title>
<indexterm zone="g-main-loop-run"><primary sortas="main_loop_run">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainLoop"><type>GMainLoop</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-loop-quit" role="function">
<title>g_main_loop_quit ()</title>
<indexterm zone="g-main-loop-quit"><primary sortas="main_loop_quit">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>
Note that sources that have already been dispatched when 
<link linkend="g-main-loop-quit"><function>g_main_loop_quit()</function></link> is called will still be executed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>loop</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GMainLoop"><type>GMainLoop</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-loop-is-running" role="function">
<title>g_main_loop_is_running ()</title>
<indexterm zone="g-main-loop-is-running"><primary sortas="main_loop_is_running">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the mainloop is currently being run.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-loop-get-context" role="function">
<title>g_main_loop_get_context ()</title>
<indexterm zone="g-main-loop-get-context"><primary sortas="main_loop_get_context">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GMainContext"><type>GMainContext</type></link> of <parameter>loop</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-new" role="macro" condition="deprecated:2.2: Use g_main_loop_new() instead.">
<title>g_main_new()</title>
<indexterm zone="g-main-new" role="deprecated"><primary sortas="main_new">g_main_new</primary></indexterm><programlisting>#define             g_main_new(is_running)</programlisting>
<warning><para><literal>g_main_new</literal> has been deprecated since version 2.2 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>&#160;:</term>
<listitem><simpara>set to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> 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 <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> anyway.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-destroy" role="macro" condition="deprecated:2.2: Use g_main_loop_unref() instead.">
<title>g_main_destroy()</title>
<indexterm zone="g-main-destroy" role="deprecated"><primary sortas="main_destroy">g_main_destroy</primary></indexterm><programlisting>#define             g_main_destroy(loop)</programlisting>
<warning><para><literal>g_main_destroy</literal> has been deprecated since version 2.2 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>&#160;:</term>
<listitem><simpara>a <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-run" role="macro" condition="deprecated:2.2: Use g_main_loop_run() instead.">
<title>g_main_run()</title>
<indexterm zone="g-main-run" role="deprecated"><primary sortas="main_run">g_main_run</primary></indexterm><programlisting>#define             g_main_run(loop)</programlisting>
<warning><para><literal>g_main_run</literal> has been deprecated since version 2.2 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>&#160;:</term>
<listitem><simpara>a <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-quit" role="macro" condition="deprecated:2.2: Use g_main_loop_quit() instead.">
<title>g_main_quit()</title>
<indexterm zone="g-main-quit" role="deprecated"><primary sortas="main_quit">g_main_quit</primary></indexterm><programlisting>#define             g_main_quit(loop)</programlisting>
<warning><para><literal>g_main_quit</literal> has been deprecated since version 2.2 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>&#160;:</term>
<listitem><simpara>a <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-is-running" role="macro" condition="deprecated:2.2: USe g_main_loop_is_running() instead.">
<title>g_main_is_running()</title>
<indexterm zone="g-main-is-running" role="deprecated"><primary sortas="main_is_running">g_main_is_running</primary></indexterm><programlisting>#define             g_main_is_running(loop)</programlisting>
<warning><para><literal>g_main_is_running</literal> has been deprecated since version 2.2 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>&#160;:</term>
<listitem><simpara>a <link linkend="GMainLoop"><type>GMainLoop</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if the main loop is running.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="G-PRIORITY-HIGH--CAPS" role="macro">
<title>G_PRIORITY_HIGH</title>
<indexterm zone="G-PRIORITY-HIGH--CAPS"><primary sortas="PRIORITY_HIGH">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 id="G-PRIORITY-DEFAULT--CAPS" role="macro">
<title>G_PRIORITY_DEFAULT</title>
<indexterm zone="G-PRIORITY-DEFAULT--CAPS"><primary sortas="PRIORITY_DEFAULT">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 id="G-PRIORITY-HIGH-IDLE--CAPS" role="macro">
<title>G_PRIORITY_HIGH_IDLE</title>
<indexterm zone="G-PRIORITY-HIGH-IDLE--CAPS"><primary sortas="PRIORITY_HIGH_IDLE">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 id="G-PRIORITY-DEFAULT-IDLE--CAPS" role="macro">
<title>G_PRIORITY_DEFAULT_IDLE</title>
<indexterm zone="G-PRIORITY-DEFAULT-IDLE--CAPS"><primary sortas="PRIORITY_DEFAULT_IDLE">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 id="G-PRIORITY-LOW--CAPS" role="macro">
<title>G_PRIORITY_LOW</title>
<indexterm zone="G-PRIORITY-LOW--CAPS"><primary sortas="PRIORITY_LOW">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 id="GMainContext" role="struct">
<title>GMainContext</title>
<indexterm zone="GMainContext"><primary sortas="MainContext">GMainContext</primary></indexterm><programlisting>typedef struct _GMainContext 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 id="g-main-context-new" role="function">
<title>g_main_context_new ()</title>
<indexterm zone="g-main-context-new"><primary sortas="main_context_new">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> structure.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the new <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-ref" role="function">
<title>g_main_context_ref ()</title>
<indexterm zone="g-main-context-ref"><primary sortas="main_context_ref">g_main_context_ref</primary></indexterm><programlisting><link linkend="GMainContext">GMainContext</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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <parameter>context</parameter> that was passed in (since 2.6)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-unref" role="function">
<title>g_main_context_unref ()</title>
<indexterm zone="g-main-context-unref"><primary sortas="main_context_unref">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-default" role="function">
<title>g_main_context_default ()</title>
<indexterm zone="g-main-context-default"><primary sortas="main_context_default">g_main_context_default</primary></indexterm><programlisting><link linkend="GMainContext">GMainContext</link> *      g_main_context_default              (void);</programlisting>
<para>
Returns the global default main context. This is the main context
used for main loop functions when a main loop is not explicitly
specified, and corresponds to the "main" main loop. See also
<link linkend="g-main-context-get-thread-default"><function>g_main_context_get_thread_default()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the global default main context.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-iteration" role="function">
<title>g_main_context_iteration ()</title>
<indexterm zone="g-main-context-iteration"><primary sortas="main_context_iteration">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 <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, waiting
for a source to become ready, then dispatching the highest priority
events sources that are ready. Otherwise, if <parameter>may_block</parameter> is <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> 
sources are not waited to become ready, only those highest priority 
events sources will be dispatched (if any), that are ready at this 
given moment without further waiting.
</para>
<para>
Note that even when <parameter>may_block</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, it is still possible for 
<link linkend="g-main-context-iteration"><function>g_main_context_iteration()</function></link> to return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, 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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (if <link linkend="NULL--CAPS"><literal>NULL</literal></link>, the default context will be used) 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>may_block</parameter>&#160;:</term>
<listitem><simpara> whether the call may block.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if events were dispatched.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-iteration" role="macro" condition="deprecated:2.2: Use g_main_context_iteration() instead.">
<title>g_main_iteration()</title>
<indexterm zone="g-main-iteration" role="deprecated"><primary sortas="main_iteration">g_main_iteration</primary></indexterm><programlisting>#define             g_main_iteration(may_block)</programlisting>
<warning><para><literal>g_main_iteration</literal> has been deprecated since version 2.2 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>&#160;:</term>
<listitem><simpara>set to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> 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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> it will return immediately if no event source is ready to be
processed.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if more events are pending.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-pending" role="function">
<title>g_main_context_pending ()</title>
<indexterm zone="g-main-context-pending"><primary sortas="main_context_pending">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (if <link linkend="NULL--CAPS"><literal>NULL</literal></link>, the default context will be used)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if events are pending.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-pending" role="macro" condition="deprecated:2.2: Use g_main_context_pending() instead.">
<title>g_main_pending()</title>
<indexterm zone="g-main-pending" role="deprecated"><primary sortas="main_pending">g_main_pending</primary></indexterm><programlisting>#define             g_main_pending()</programlisting>
<warning><para><literal>g_main_pending</literal> has been deprecated since version 2.2 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>&#160;:</term><listitem><simpara>%TRUE if any events are pending.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-find-source-by-id" role="function">
<title>g_main_context_find_source_by_id ()</title>
<indexterm zone="g-main-context-find-source-by-id"><primary sortas="main_context_find_source_by_id">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (if <link linkend="NULL--CAPS"><literal>NULL</literal></link>, the default context will be used)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>source_id</parameter>&#160;:</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>&#160;:</term><listitem><simpara> the <link linkend="GSource"><type>GSource</type></link> if found, otherwise, <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-find-source-by-user-data" role="function">
<title>g_main_context_find_source_by_user_data ()</title>
<indexterm zone="g-main-context-find-source-by-user-data"><primary sortas="main_context_find_source_by_user_data">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> the user_data for the callback.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the source, if one was found, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-find-source-by-funcs-user-data" role="function">
<title>g_main_context_find_source_by_funcs_user_data ()</title>
<indexterm zone="g-main-context-find-source-by-funcs-user-data"><primary sortas="main_context_find_source_by_funcs_user_data">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (if <link linkend="NULL--CAPS"><literal>NULL</literal></link>, the default context will be used).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>funcs</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> the user data from the callback.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the source, if one was found, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-wakeup" role="function">
<title>g_main_context_wakeup ()</title>
<indexterm zone="g-main-context-wakeup"><primary sortas="main_context_wakeup">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-acquire" role="function">
<title>g_main_context_acquire ()</title>
<indexterm zone="g-main-context-acquire"><primary sortas="main_context_acquire">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 thread is the owner of the context,
returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> 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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the operation succeeded, and
  this thread is now the owner of <parameter>context</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-release" role="function">
<title>g_main_context_release ()</title>
<indexterm zone="g-main-context-release"><primary sortas="main_context_release">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 ownership will be released only 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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-is-owner" role="function" condition="since:2.10">
<title>g_main_context_is_owner ()</title>
<indexterm zone="g-main-context-is-owner" role="2.10"><primary sortas="main_context_is_owner">g_main_context_is_owner</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_main_context_is_owner             (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Determines whether this thread holds the (recursive)
ownership of this <link linkend="GMaincontext"><type>GMaincontext</type></link>. This is useful to
know before waiting on another thread that may be
blocking to get ownership of <parameter>context</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if current thread is owner of <parameter>context</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.10</para></refsect2>
<refsect2 id="g-main-context-wait" role="function">
<title>g_main_context_wait ()</title>
<indexterm zone="g-main-context-wait"><primary sortas="main_context_wait">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cond</parameter>&#160;:</term>
<listitem><simpara> a condition variable
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mutex</parameter>&#160;:</term>
<listitem><simpara> a mutex, currently held
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the operation succeeded, and
  this thread is now the owner of <parameter>context</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-prepare" role="function">
<title>g_main_context_prepare ()</title>
<indexterm zone="g-main-context-prepare"><primary sortas="main_context_prepare">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>priority</parameter>&#160;:</term>
<listitem><simpara> location to store priority of highest priority
           source already ready.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if some source is ready to be dispatched
              prior to polling.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-query" role="function">
<title>g_main_context_query ()</title>
<indexterm zone="g-main-context-query"><primary sortas="main_context_query">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max_priority</parameter>&#160;:</term>
<listitem><simpara> maximum priority source to check
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>timeout_</parameter>&#160;:</term>
<listitem><simpara> location to store timeout to be used in polling
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fds</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> length of <parameter>fds</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</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 id="g-main-context-check" role="function">
<title>g_main_context_check ()</title>
<indexterm zone="g-main-context-check"><primary sortas="main_context_check">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max_priority</parameter>&#160;:</term>
<listitem><simpara> the maximum numerical priority of sources to check
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fds</parameter>&#160;:</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>&#160;:</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>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if some sources are ready to be dispatched.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-dispatch" role="function">
<title>g_main_context_dispatch ()</title>
<indexterm zone="g-main-context-dispatch"><primary sortas="main_context_dispatch">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-set-poll-func" role="function">
<title>g_main_context_set_poll_func ()</title>
<indexterm zone="g-main-context-set-poll-func"><primary sortas="main_context_set_poll_func">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> the function to call to poll all file descriptors
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-get-poll-func" role="function">
<title>g_main_context_get_poll_func ()</title>
<indexterm zone="g-main-context-get-poll-func"><primary sortas="main_context_get_poll_func">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the poll function
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GPollFunc" role="function">
<title>GPollFunc ()</title>
<indexterm zone="GPollFunc"><primary sortas="PollFunc">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>&#160;:</term>
<listitem><simpara>an array of <link linkend="GPollFD"><type>GPollFD</type></link> elements.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>nfsd</parameter>&#160;:</term>
<listitem><simpara>the number of elements in <parameter>ufds</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>timeout_</parameter>&#160;:</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>&#160;:</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 id="g-main-context-add-poll" role="function">
<title>g_main_context_add_poll ()</title>
<indexterm zone="g-main-context-add-poll"><primary sortas="main_context_add_poll">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>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (or <link linkend="NULL--CAPS"><literal>NULL</literal></link> for the default context)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fd</parameter>&#160;:</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>&#160;:</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 id="g-main-context-remove-poll" role="function">
<title>g_main_context_remove_poll ()</title>
<indexterm zone="g-main-context-remove-poll"><primary sortas="main_context_remove_poll">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>&#160;:</term>
<listitem><simpara>a <link linkend="GMainContext"><type>GMainContext</type></link> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fd</parameter>&#160;:</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 id="g-main-depth" role="function">
<title>g_main_depth ()</title>
<indexterm zone="g-main-depth"><primary sortas="main_depth">g_main_depth</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_main_depth                        (void);</programlisting>
<para>
Returns 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.
</para>
<para>
This function is useful in a situation like the following:
Imagine an extremely simple "garbage collected" system.
</para>
<para>
<informalexample><programlisting>
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);
   free_allocated_memory();
  }
</programlisting></informalexample>
</para>
<para>
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>
</para>
<para>
<informalexample><programlisting>
gpointer
allocate_memory (gsize size)
{ 
  FreeListBlock *block = g_new (FreeListBlock, 1);
  block->mem = g_malloc (size);
  block->depth = g_main_depth ();   
  free_list = g_list_prepend (free_list, block);
  return block->mem;
}

void
free_allocated_memory (void)
{
  GList *l;
  
  int depth = g_main_depth ();
  for (l = free_list; l; );
    {
      GList *next = l->next;
      FreeListBlock *block = l->data;
      if (block->depth &gt; depth)
        {
          g_free (block->mem);
          g_free (block);
          free_list = g_list_delete_link (free_list, l);
        }
              
      l = next;
    }
  }
</programlisting></informalexample>
</para>
<para>
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:
</para>
<para>
<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></para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The main loop recursion level in the current thread
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-current-source" role="function" condition="since:2.12">
<title>g_main_current_source ()</title>
<indexterm zone="g-main-current-source" role="2.12"><primary sortas="main_current_source">g_main_current_source</primary></indexterm><programlisting><link linkend="GSource">GSource</link> *           g_main_current_source               (void);</programlisting>
<para>
Returns the currently firing source for this thread.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The currently firing source or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.12</para></refsect2>
<refsect2 id="g-main-set-poll-func" role="macro" condition="deprecated:2.2: Use g_main_context_set_poll_func() instead.">
<title>g_main_set_poll_func()</title>
<indexterm zone="g-main-set-poll-func" role="deprecated"><primary sortas="main_set_poll_func">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> has been deprecated since version 2.2 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>&#160;:</term>
<listitem><simpara>the function to call to poll all file descriptors.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-main-context-get-thread-default" role="function" condition="since:2.22">
<title>g_main_context_get_thread_default ()</title>
<indexterm zone="g-main-context-get-thread-default" role="2.22"><primary sortas="main_context_get_thread_default">g_main_context_get_thread_default</primary></indexterm><programlisting><link linkend="GMainContext">GMainContext</link> *      g_main_context_get_thread_default   (void);</programlisting>
<para>
Gets the thread-default <link linkend="GMainContext"><type>GMainContext</type></link> for this thread. Asynchronous
operations that want to be able to be run in contexts other than
the default one should call this method to get a <link linkend="GMainContext"><type>GMainContext</type></link> to
add their <link linkend="GSource"><type>GSource</type></link><!-- -->s to. (Note that even in single-threaded
programs applications may sometimes want to temporarily push a
non-default context, so it is not safe to assume that this will
always return <link linkend="NULL--CAPS"><literal>NULL</literal></link> if threads are not initialized.)</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the thread-default <link linkend="GMainContext"><type>GMainContext</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the
thread-default context is the global default context.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-main-context-push-thread-default" role="function" condition="since:2.22">
<title>g_main_context_push_thread_default ()</title>
<indexterm zone="g-main-context-push-thread-default" role="2.22"><primary sortas="main_context_push_thread_default">g_main_context_push_thread_default</primary></indexterm><programlisting><link linkend="void">void</link>                g_main_context_push_thread_default  (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Acquires <parameter>context</parameter> and sets it as the thread-default context for the
current thread. This will cause certain asynchronous operations
(such as most <link linkend="gio">gio</link>-based I/O) which are
started in this thread to run under <parameter>context</parameter> and deliver their
results to its main loop, rather than running under the global
default context in the main thread. Note that calling this function
changes the context returned by
<link linkend="g-main-context-get-thread-default"><function>g_main_context_get_thread_default()</function></link>, <emphasis>not</emphasis> the
one returned by <link linkend="g-main-context-default"><function>g_main_context_default()</function></link>, so it does not affect the
context used by functions like <link linkend="g-idle-add"><function>g_idle_add()</function></link>.
</para>
<para>
Normally you would call this function shortly after creating a new
thread, passing it a <link linkend="GMainContext"><type>GMainContext</type></link> which will be run by a
<link linkend="GMainLoop"><type>GMainLoop</type></link> in that thread, to set a new default context for all
async operations in that thread. (In this case, you don't need to
ever call <link linkend="g-main-context-pop-thread-default"><function>g_main_context_pop_thread_default()</function></link>.) In some cases
however, you may want to schedule a single operation in a
non-default context, or temporarily use a non-default context in
the main thread. In that case, you can wrap the call to the
asynchronous operation inside a
<link linkend="g-main-context-push-thread-default"><function>g_main_context_push_thread_default()</function></link> /
<link linkend="g-main-context-pop-thread-default"><function>g_main_context_pop_thread_default()</function></link> pair, but it is up to you to
ensure that no other asynchronous operations accidentally get
started while the non-default context is active.
</para>
<para>
Beware that libraries that predate this function may not correctly
handle being used from a thread with a thread-default context. Eg,
see <link linkend="g-file-supports-thread-contexts"><function>g_file_supports_thread_contexts()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> for the global default context
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-main-context-pop-thread-default" role="function" condition="since:2.22">
<title>g_main_context_pop_thread_default ()</title>
<indexterm zone="g-main-context-pop-thread-default" role="2.22"><primary sortas="main_context_pop_thread_default">g_main_context_pop_thread_default</primary></indexterm><programlisting><link linkend="void">void</link>                g_main_context_pop_thread_default   (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Pops <parameter>context</parameter> off the thread-default context stack (verifying that
it was on the top of the stack).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>context</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> object, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-timeout-source-new" role="function">
<title>g_timeout_source_new ()</title>
<indexterm zone="g-timeout-source-new"><primary sortas="timeout_source_new">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>&#160;:</term>
<listitem><simpara> the timeout interval in milliseconds.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly-created timeout source
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-timeout-source-new-seconds" role="function" condition="since:2.14">
<title>g_timeout_source_new_seconds ()</title>
<indexterm zone="g-timeout-source-new-seconds" role="2.14"><primary sortas="timeout_source_new_seconds">g_timeout_source_new_seconds</primary></indexterm><programlisting><link linkend="GSource">GSource</link> *           g_timeout_source_new_seconds        (<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>
The scheduling granularity/accuracy of this timeout source will be
in seconds.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>interval</parameter>&#160;:</term>
<listitem><simpara> the timeout interval in seconds
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly-created timeout source

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.14</para></refsect2>
<refsect2 id="g-timeout-add" role="function">
<title>g_timeout_add ()</title>
<indexterm zone="g-timeout-add"><primary sortas="timeout_add">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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, 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>
If you want to have a timer in the "seconds" range and do not care
about the exact time of the first call of the timer, use the
<link linkend="g-timeout-add-seconds"><function>g_timeout_add_seconds()</function></link> function; this function allows for more
optimizations and more efficient system power usage.
</para>
<para>
This internally creates a main loop source using <link linkend="g-timeout-source-new"><function>g_timeout_source_new()</function></link>
and attaches it to the main loop context using <link linkend="g-source-attach"><function>g_source_attach()</function></link>. You can
do these steps manually if you need greater control.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>interval</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>     data to pass to <parameter>function</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the ID (greater than 0) of the event source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-timeout-add-full" role="function">
<title>g_timeout_add_full ()</title>
<indexterm zone="g-timeout-add-full"><primary sortas="timeout_add_full">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
<link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, 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>
This internally creates a main loop source using <link linkend="g-timeout-source-new"><function>g_timeout_source_new()</function></link>
and attaches it to the main loop context using <link linkend="g-source-attach"><function>g_source_attach()</function></link>. You can
do these steps manually if you need greater control.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>priority</parameter>&#160;:</term>
<listitem><simpara> the priority of the timeout source. Typically this will be in
           the range between <link linkend="G-PRIORITY-DEFAULT--CAPS"><type>G_PRIORITY_DEFAULT</type></link> and <link linkend="G-PRIORITY-HIGH--CAPS"><type>G_PRIORITY_HIGH</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>interval</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>     data to pass to <parameter>function</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter>&#160;:</term>
<listitem><simpara>   function to call when the timeout is removed, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the ID (greater than 0) of the event source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-timeout-add-seconds" role="function" condition="since:2.14">
<title>g_timeout_add_seconds ()</title>
<indexterm zone="g-timeout-add-seconds" role="2.14"><primary sortas="timeout_add_seconds">g_timeout_add_seconds</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_timeout_add_seconds               (<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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, at which point the timeout is automatically destroyed
and the function will not be called again.
</para>
<para>
This internally creates a main loop source using 
<link linkend="g-timeout-source-new-seconds"><function>g_timeout_source_new_seconds()</function></link> and attaches it to the main loop context 
using <link linkend="g-source-attach"><function>g_source_attach()</function></link>. You can do these steps manually if you need 
greater control. Also see <link linkend="g-timout-add-seconds-full"><function>g_timout_add_seconds_full()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>interval</parameter>&#160;:</term>
<listitem><simpara> the time between calls to the function, in seconds
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> data to pass to <parameter>function</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the ID (greater than 0) of the event source.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.14</para></refsect2>
<refsect2 id="g-timeout-add-seconds-full" role="function" condition="since:2.14">
<title>g_timeout_add_seconds_full ()</title>
<indexterm zone="g-timeout-add-seconds-full" role="2.14"><primary sortas="timeout_add_seconds_full">g_timeout_add_seconds_full</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_timeout_add_seconds_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 <parameter>priority</parameter>.
The function is called repeatedly until it returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, at which
point the timeout is automatically destroyed and the function will
not be called again.
</para>
<para>
Unlike <link linkend="g-timeout-add"><function>g_timeout_add()</function></link>, this function operates at whole second granularity.
The initial starting point of the timer is determined by the implementation
and the implementation is expected to group multiple timers together so that
they fire all at the same time.
To allow this grouping, the <parameter>interval</parameter> to the first timer is rounded
and can deviate up to one second from the specified interval.
Subsequent timer iterations will generally run at the specified interval.
</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 <parameter>interval</parameter>
</para>
<para>
If you want timing more precise than whole seconds, use <link linkend="g-timeout-add"><function>g_timeout_add()</function></link>
instead.
</para>
<para>
The grouping of timers to fire at the same time results in a more power
and CPU efficient behavior so if your timer is in multiples of seconds
and you don't require the first timer exactly one second from now, the
use of <link linkend="g-timeout-add-seconds"><function>g_timeout_add_seconds()</function></link> is preferred over <link linkend="g-timeout-add"><function>g_timeout_add()</function></link>.
</para>
<para>
This internally creates a main loop source using 
<link linkend="g-timeout-source-new-seconds"><function>g_timeout_source_new_seconds()</function></link> and attaches it to the main loop context 
using <link linkend="g-source-attach"><function>g_source_attach()</function></link>. You can do these steps manually if you need 
greater control.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>priority</parameter>&#160;:</term>
<listitem><simpara> the priority of the timeout source. Typically this will be in
           the range between <link linkend="G-PRIORITY-DEFAULT--CAPS"><type>G_PRIORITY_DEFAULT</type></link> and <link linkend="G-PRIORITY-HIGH--CAPS"><type>G_PRIORITY_HIGH</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>interval</parameter>&#160;:</term>
<listitem><simpara> the time between calls to the function, in seconds
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>     data to pass to <parameter>function</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter>&#160;:</term>
<listitem><simpara>   function to call when the timeout is removed, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the ID (greater than 0) of the event source.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.14</para></refsect2>
<refsect2 id="g-idle-source-new" role="function">
<title>g_idle_source_new ()</title>
<indexterm zone="g-idle-source-new"><primary sortas="idle_source_new">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
<link linkend="G-PRIORITY-DEFAULT-IDLE--CAPS"><literal>G_PRIORITY_DEFAULT_IDLE</literal></link>, as compared to other sources which
have a default priority of <link linkend="G-PRIORITY-DEFAULT--CAPS"><literal>G_PRIORITY_DEFAULT</literal></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly-created idle source
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-idle-add" role="function">
<title>g_idle_add ()</title>
<indexterm zone="g-idle-add"><primary sortas="idle_add">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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> it is automatically removed from the list of event
sources and will not be called again.
</para>
<para>
This internally creates a main loop source using <link linkend="g-idle-source-new"><function>g_idle_source_new()</function></link>
and attaches it to the main loop context using <link linkend="g-source-attach"><function>g_source_attach()</function></link>. 
You can do these steps manually if you need greater control.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara> function to call 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> data to pass to <parameter>function</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the ID (greater than 0) of the event source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-idle-add-full" role="function">
<title>g_idle_add_full ()</title>
<indexterm zone="g-idle-add-full"><primary sortas="idle_add_full">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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> it is automatically
removed from the list of event sources and will not be called again.
</para>
<para>
This internally creates a main loop source using <link linkend="g-idle-source-new"><function>g_idle_source_new()</function></link>
and attaches it to the main loop context using <link linkend="g-source-attach"><function>g_source_attach()</function></link>. 
You can do these steps manually if you need greater control.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>priority</parameter>&#160;:</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>function</parameter>&#160;:</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>     data to pass to <parameter>function</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter>&#160;:</term>
<listitem><simpara>   function to call when the idle is removed, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the ID (greater than 0) of the event source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-idle-remove-by-data" role="function">
<title>g_idle_remove_by_data ()</title>
<indexterm zone="g-idle-remove-by-data"><primary sortas="idle_remove_by_data">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>&#160;:</term>
<listitem><simpara> the data for the idle source's callback.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if an idle source was found and removed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GPid" role="typedef">
<title>GPid</title>
<indexterm zone="GPid"><primary sortas="Pid">GPid</primary></indexterm><programlisting>typedef int GPid;
</programlisting>
<para>
A type which is used to hold a process identification.
On Unix, processes are identified by a process id (an
integer), while Windows uses process handles (which are
pointers).
</para></refsect2>
<refsect2 id="GChildWatchFunc" role="function">
<title>GChildWatchFunc ()</title>
<indexterm zone="GChildWatchFunc"><primary sortas="ChildWatchFunc">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>
The type of functions to be called when a child exists.
</para><variablelist role="params">
<varlistentry><term><parameter>pid</parameter>&#160;:</term>
<listitem><simpara>the process id of the child process
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>status</parameter>&#160;:</term>
<listitem><simpara>Status information about the child process,
  see waitpid(2) for more information about this field
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>user data passed to <link linkend="g-child-watch-add"><function>g_child_watch_add()</function></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-child-watch-source-new" role="function" condition="since:2.4">
<title>g_child_watch_source_new ()</title>
<indexterm zone="g-child-watch-source-new" role="2.4"><primary sortas="child_watch_source_new">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 child watch sources can only be used in conjunction with
<literal>g_spawn...</literal> when the <link linkend="G-SPAWN-DO-NOT-REAP-CHILD--CAPS"><literal>G_SPAWN_DO_NOT_REAP_CHILD</literal></link>
flag is used.
</para>
<para>
Note that on platforms where <link linkend="GPid"><type>GPid</type></link> must be explicitly 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>
Note further that using <link linkend="g-child-watch-source-new"><function>g_child_watch_source_new()</function></link> is not 
compatible with calling <literal>waitpid(-1)</literal> in 
the application. Calling <link linkend="waitpid"><function>waitpid()</function></link> for individual pids will
still work fine.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>pid</parameter>&#160;:</term>
<listitem><simpara> process to watch. On POSIX the pid of a child process. On
Windows a handle for a process (which doesn't have to be a child).
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly-created child watch source

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-child-watch-add" role="function" condition="since:2.4">
<title>g_child_watch_add ()</title>
<indexterm zone="g-child-watch-add" role="2.4"><primary sortas="child_watch_add">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>
If you obtain <parameter>pid</parameter> from <link linkend="g-spawn-async"><function>g_spawn_async()</function></link> or <link linkend="g-spawn-async-with-pipes"><function>g_spawn_async_with_pipes()</function></link> 
you will need to pass <link linkend="G-SPAWN-DO-NOT-REAP-CHILD--CAPS"><type>G_SPAWN_DO_NOT_REAP_CHILD</type></link> as flag to 
the spawn function for the child watching to work.
</para>
<para>
Note that on platforms where <link linkend="GPid"><type>GPid</type></link> must be explicitly 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>
GLib supports only a single callback per process id.
</para>
<para>
This internally creates a main loop source using 
<link linkend="g-child-watch-source-new"><function>g_child_watch_source_new()</function></link> and attaches it to the main loop context 
using <link linkend="g-source-attach"><function>g_source_attach()</function></link>. You can do these steps manually if you 
need greater control.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>pid</parameter>&#160;:</term>
<listitem><simpara>      process id to watch. On POSIX the pid of a child process. On
Windows a handle for a process (which doesn't have to be a child).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>     data to pass to <parameter>function</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the ID (greater than 0) of the event source.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-child-watch-add-full" role="function" condition="since:2.4">
<title>g_child_watch_add_full ()</title>
<indexterm zone="g-child-watch-add-full" role="2.4"><primary sortas="child_watch_add_full">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 the priority <parameter>priority</parameter>.
</para>
<para>
If you obtain <parameter>pid</parameter> from <link linkend="g-spawn-async"><function>g_spawn_async()</function></link> or <link linkend="g-spawn-async-with-pipes"><function>g_spawn_async_with_pipes()</function></link> 
you will need to pass <link linkend="G-SPAWN-DO-NOT-REAP-CHILD--CAPS"><type>G_SPAWN_DO_NOT_REAP_CHILD</type></link> as flag to 
the spawn function for the child watching to work.
</para>
<para>
Note that on platforms where <link linkend="GPid"><type>GPid</type></link> must be explicitly 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>
GLib supports only a single callback per process id.
</para>
<para>
This internally creates a main loop source using 
<link linkend="g-child-watch-source-new"><function>g_child_watch_source_new()</function></link> and attaches it to the main loop context 
using <link linkend="g-source-attach"><function>g_source_attach()</function></link>. You can do these steps manually if you 
need greater control.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>priority</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara>      process to watch. On POSIX the pid of a child process. On
Windows a handle for a process (which doesn't have to be a child).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>function</parameter>&#160;:</term>
<listitem><simpara> function to call
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>     data to pass to <parameter>function</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter>&#160;:</term>
<listitem><simpara>   function to call when the idle is removed, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the ID (greater than 0) of the event source.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="GPollFD" role="struct">
<title>GPollFD</title>
<indexterm zone="GPollFD"><primary sortas="PollFD">GPollFD</primary></indexterm><programlisting>typedef struct {
#if defined (G_OS_WIN32) &amp;&amp; GLIB_SIZEOF_VOID_P == 8
  gint64	fd;
#else
  gint		fd;
#endif
  gushort 	events;
  gushort 	revents;
} GPollFD;
</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 <link linkend="G-IO-IN--CAPS"><literal>G_IO_IN</literal></link> | <link linkend="G-IO-HUP--CAPS"><literal>G_IO_HUP</literal></link> | <link linkend="G-IO-ERR--CAPS"><literal>G_IO_ERR</literal></link>, and for writing you would use
<link linkend="G-IO-OUT--CAPS"><literal>G_IO_OUT</literal></link> | <link linkend="G-IO-ERR--CAPS"><literal>G_IO_ERR</literal></link>.
</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 id="g-poll" role="function" condition="since:2.20">
<title>g_poll ()</title>
<indexterm zone="g-poll" role="2.20"><primary sortas="poll">g_poll</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_poll                              (<link linkend="GPollFD">GPollFD</link> *fds,
                                                         <link linkend="guint">guint</link> nfds,
                                                         <link linkend="gint">gint</link> timeout);</programlisting>
<para>
Polls <parameter>fds</parameter>, as with the <link linkend="poll"><function>poll()</function></link> system call, but portably. (On
systems that don't have <link linkend="poll"><function>poll()</function></link>, it is emulated using <link linkend="select"><function>select()</function></link>.)
This is used internally by <link linkend="GMainContext"><type>GMainContext</type></link>, but it can be called
directly if you need to block until a file descriptor is ready, but
don't want to run the full main loop.
</para>
<para>
Each element of <parameter>fds</parameter> is a <link linkend="GPollFD"><type>GPollFD</type></link> describing a single file
descriptor to poll. The <link linkend="fd"><literal>fd</literal></link> field indicates the file descriptor,
and the <link linkend="events"><literal>events</literal></link> field indicates the events to poll for. On return,
the <link linkend="revents"><literal>revents</literal></link> fields will be filled with the events that actually
occurred.
</para>
<para>
On POSIX systems, the file descriptors in <parameter>fds</parameter> can be any sort of
file descriptor, but the situation is much more complicated on
Windows. If you need to use <link linkend="g-poll"><function>g_poll()</function></link> in code that has to run on
Windows, the easiest solution is to construct all of your
<link linkend="GPollFD"><type>GPollFD</type></link><!-- -->s with <link linkend="g-io-channel-win32-make-pollfd"><function>g_io_channel_win32_make_pollfd()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>fds</parameter>&#160;:</term>
<listitem><simpara> file descriptors to poll
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>nfds</parameter>&#160;:</term>
<listitem><simpara> the number of file descriptors in <parameter>fds</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>timeout</parameter>&#160;:</term>
<listitem><simpara> amount of time to wait, in milliseconds, or -1 to wait forever
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of entries in <parameter>fds</parameter> whose <link linkend="revents"><literal>revents</literal></link> fields
were filled in, or 0 if the operation timed out, or -1 on error or
if the call was interrupted.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.20</para></refsect2>
<refsect2 id="GSource" role="struct">
<title>GSource</title>
<indexterm zone="GSource"><primary sortas="Source">GSource</primary></indexterm><programlisting>typedef struct {
} GSource;
</programlisting>
<para>
The <structname>GSource</structname> struct is an opaque data type representing
an event source.
</para></refsect2>
<refsect2 id="GSourceDummyMarshal" role="function">
<title>GSourceDummyMarshal ()</title>
<indexterm zone="GSourceDummyMarshal"><primary sortas="SourceDummyMarshal">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 id="GSourceFuncs" role="struct">
<title>GSourceFuncs</title>
<indexterm zone="GSourceFuncs"><primary sortas="SourceFuncs">GSourceFuncs</primary></indexterm><programlisting>typedef struct {
  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 */
} GSourceFuncs;
</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.
</para>
<para>
For idle sources, the prepare and check functions always return <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> 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
<link linkend="poll"><function>poll()</function></link> 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 <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the
timeout interval has expired. The prepare function also returns a timeout
value to ensure that the <link linkend="poll"><function>poll()</function></link> call doesn't block too
long and miss the next timeout.
</para>
<para>
For file descriptor sources, the prepare function typically returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>,
since it must wait until <link linkend="poll"><function>poll()</function></link> 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
<link linkend="poll"><function>poll()</function></link> call blocks.
In the check function, it tests the results of the <link linkend="poll"><function>poll()</function></link>
call to see if the required condition has been met, and returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if so.
</para><variablelist role="struct">
<varlistentry>
<term><structfield>prepare</structfield>&#160;()</term>
<listitem><simpara>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 <link linkend="poll"><function>poll()</function></link> call) it should return <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>.
It can also return a <parameter>timeout_</parameter> value which should be the maximum timeout
(in milliseconds) which should be passed to the <link linkend="poll"><function>poll()</function></link> 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.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>check</structfield>&#160;()</term>
<listitem><simpara>Called after all the file descriptors are polled.
The source should return <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> 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.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>dispatch</structfield>&#160;()</term>
<listitem><simpara>Called to dispatch the event source, after it has returned <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> 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
<link linkend="NULL--CAPS"><literal>NULL</literal></link> 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.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>finalize</structfield>&#160;()</term>
<listitem><simpara>Called when the source is finalized.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GSourceFunc">GSourceFunc</link>&#160;<structfield>closure_callback</structfield>;</term>
<listitem><simpara>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GSourceDummyMarshal">GSourceDummyMarshal</link>&#160;<structfield>closure_marshal</structfield>;</term>
<listitem><simpara>
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="GSourceCallbackFuncs" role="struct">
<title>GSourceCallbackFuncs</title>
<indexterm zone="GSourceCallbackFuncs"><primary sortas="SourceCallbackFuncs">GSourceCallbackFuncs</primary></indexterm><programlisting>typedef struct {
  void (*ref)   (gpointer     cb_data);
  void (*unref) (gpointer     cb_data);
  void (*get)   (gpointer     cb_data,
		 GSource     *source, 
		 GSourceFunc *func,
		 gpointer    *data);
} GSourceCallbackFuncs;
</programlisting>
<para>
The <structname>GSourceCallbackFuncs</structname> struct contains
functions for managing callback objects.
</para><variablelist role="struct">
<varlistentry>
<term><structfield>ref</structfield>&#160;()</term>
<listitem><simpara>Called when a reference is added to the callback object.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>unref</structfield>&#160;()</term>
<listitem><simpara>Called when a reference to the callback object is dropped.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>get</structfield>&#160;()</term>
<listitem><simpara>Called to extract the callback function and data from the callback object.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-new" role="function">
<title>g_source_new ()</title>
<indexterm zone="g-source-new"><primary sortas="source_new">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>&#160;:</term>
<listitem><simpara> structure containing functions that implement
               the sources behavior.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>struct_size</parameter>&#160;:</term>
<listitem><simpara> size of the <link linkend="GSource"><type>GSource</type></link> structure to create.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly-created <link linkend="GSource"><type>GSource</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-ref" role="function">
<title>g_source_ref ()</title>
<indexterm zone="g-source-ref"><primary sortas="source_ref">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>&#160;:</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <parameter>source</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-unref" role="function">
<title>g_source_unref ()</title>
<indexterm zone="g-source-unref"><primary sortas="source_unref">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>&#160;:</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-set-funcs" role="function" condition="since:2.12">
<title>g_source_set_funcs ()</title>
<indexterm zone="g-source-set-funcs" role="2.12"><primary sortas="source_set_funcs">g_source_set_funcs</primary></indexterm><programlisting><link linkend="void">void</link>                g_source_set_funcs                  (<link linkend="GSource">GSource</link> *source,
                                                         <link linkend="GSourceFuncs">GSourceFuncs</link> *funcs);</programlisting>
<para>
Sets the source functions (can be used to override 
default implementations) of an unattached source.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>funcs</parameter>&#160;:</term>
<listitem><simpara> the new <link linkend="GSourceFuncs"><type>GSourceFuncs</type></link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.12</para></refsect2>
<refsect2 id="g-source-attach" role="function">
<title>g_source_attach ()</title>
<indexterm zone="g-source-attach"><primary sortas="source_attach">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. Remove it by calling <link linkend="g-source-destroy"><function>g_source_destroy()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>context</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> (if <link linkend="NULL--CAPS"><literal>NULL</literal></link>, the default context will be used)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the ID (greater than 0) for the source within the 
  <link linkend="GMainContext"><type>GMainContext</type></link>. 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-destroy" role="function">
<title>g_source_destroy ()</title>
<indexterm zone="g-source-destroy"><primary sortas="source_destroy">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>&#160;:</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-is-destroyed" role="function" condition="since:2.12">
<title>g_source_is_destroyed ()</title>
<indexterm zone="g-source-is-destroyed" role="2.12"><primary sortas="source_is_destroyed">g_source_is_destroyed</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_source_is_destroyed               (<link linkend="GSource">GSource</link> *source);</programlisting>
<para>
Returns whether <parameter>source</parameter> has been destroyed.
</para>
<para>
This is important when you operate upon your objects 
from within idle handlers, but may have freed the object 
before the dispatch of your idle handler.
</para>
<para>
<informalexample><programlisting>
static gboolean 
idle_callback (gpointer data)
{
  SomeWidget *self = data;
   
  GDK_THREADS_ENTER (<!-- -->);
  /<!-- -->* do stuff with self *<!-- -->/
  self->idle_id = 0;
  GDK_THREADS_LEAVE (<!-- -->);
   
  return FALSE;
}
 
static void 
some_widget_do_stuff_later (SomeWidget *self)
{
  self->idle_id = g_idle_add (idle_callback, self);
}
 
static void 
some_widget_finalize (GObject *object)
{
  SomeWidget *self = SOME_WIDGET (object);
   
  if (self->idle_id)
    g_source_remove (self->idle_id);
   
  G_OBJECT_CLASS (parent_class)->finalize (object);
}
</programlisting></informalexample>
</para>
<para>
This will fail in a multi-threaded application if the 
widget is destroyed before the idle handler fires due 
to the use after free in the callback. A solution, to 
this particular problem, is to check to if the source
has already been destroy within the callback.
</para>
<para>
<informalexample><programlisting>
static gboolean 
idle_callback (gpointer data)
{
  SomeWidget *self = data;
  
  GDK_THREADS_ENTER ();
  if (!g_source_is_destroyed (g_main_current_source ()))
    {
      /<!-- -->* do stuff with self *<!-- -->/
    }
  GDK_THREADS_LEAVE ();
  
  return FALSE;
}
</programlisting></informalexample></para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the source has been destroyed

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.12</para></refsect2>
<refsect2 id="g-source-set-priority" role="function">
<title>g_source_set_priority ()</title>
<indexterm zone="g-source-set-priority"><primary sortas="source_set_priority">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>&#160;:</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>priority</parameter>&#160;:</term>
<listitem><simpara> the new priority.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-get-priority" role="function">
<title>g_source_get_priority ()</title>
<indexterm zone="g-source-get-priority"><primary sortas="source_get_priority">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>&#160;:</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the priority of the source
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-set-can-recurse" role="function">
<title>g_source_set_can_recurse ()</title>
<indexterm zone="g-source-set-can-recurse"><primary sortas="source_set_can_recurse">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
<link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, 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>&#160;:</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>can_recurse</parameter>&#160;:</term>
<listitem><simpara> whether recursion is allowed for this source
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-get-can-recurse" role="function">
<title>g_source_get_can_recurse ()</title>
<indexterm zone="g-source-get-can-recurse"><primary sortas="source_get_can_recurse">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>&#160;:</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> whether recursion is allowed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-get-id" role="function">
<title>g_source_get_id ()</title>
<indexterm zone="g-source-get-id"><primary sortas="source_get_id">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 a positive integer which 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>&#160;:</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the ID (greater than 0) for the source
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-get-context" role="function">
<title>g_source_get_context ()</title>
<indexterm zone="g-source-get-context"><primary sortas="source_get_context">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>&#160;:</term>
<listitem><simpara> a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GMainContext"><type>GMainContext</type></link> with which the source is associated,
              or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the context has not yet been added
              to a source.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-set-callback" role="function">
<title>g_source_set_callback ()</title>
<indexterm zone="g-source-set-callback"><primary sortas="source_set_callback">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>&#160;:</term>
<listitem><simpara> the source
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> a callback function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> the data to pass to callback function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter>&#160;:</term>
<listitem><simpara> a function to call when <parameter>data</parameter> is no longer in use, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GSourceFunc" role="function">
<title>GSourceFunc ()</title>
<indexterm zone="GSourceFunc"><primary sortas="SourceFunc">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>&#160;:</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>&#160;:</term><listitem><simpara>it should return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if the source should be removed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-set-callback-indirect" role="function">
<title>g_source_set_callback_indirect ()</title>
<indexterm zone="g-source-set-callback-indirect"><primary sortas="source_set_callback_indirect">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>&#160;:</term>
<listitem><simpara> the source
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback_data</parameter>&#160;:</term>
<listitem><simpara> pointer to callback data "object"
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback_funcs</parameter>&#160;:</term>
<listitem><simpara> functions for reference counting <parameter>callback_data</parameter>
                 and getting the callback and data
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-add-poll" role="function">
<title>g_source_add_poll ()</title>
<indexterm zone="g-source-add-poll"><primary sortas="source_add_poll">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 <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if events need
to be processed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GSource"><type>GSource</type></link> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fd</parameter>&#160;:</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 id="g-source-remove-poll" role="function">
<title>g_source_remove_poll ()</title>
<indexterm zone="g-source-remove-poll"><primary sortas="source_remove_poll">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>&#160;:</term>
<listitem><simpara>a <link linkend="GSource"><type>GSource</type></link> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fd</parameter>&#160;:</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 id="g-source-get-current-time" role="function">
<title>g_source_get_current_time ()</title>
<indexterm zone="g-source-get-current-time"><primary sortas="source_get_current_time">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>&#160;:</term>
<listitem><simpara>  a <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>timeval</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GTimeVal"><type>GTimeVal</type></link> structure in which to store current time.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-remove" role="function">
<title>g_source_remove ()</title>
<indexterm zone="g-source-remove"><primary sortas="source_remove">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>. You must use <link linkend="g-source-destroy"><function>g_source_destroy()</function></link> for sources
added to a non-default main context.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tag</parameter>&#160;:</term>
<listitem><simpara> the ID of the source to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the source was found and removed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-remove-by-funcs-user-data" role="function">
<title>g_source_remove_by_funcs_user_data ()</title>
<indexterm zone="g-source-remove-by-funcs-user-data"><primary sortas="source_remove_by_funcs_user_data">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>&#160;:</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>&#160;:</term>
<listitem><simpara> the user data for the callback
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if a source was found and removed. 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-source-remove-by-user-data" role="function">
<title>g_source_remove_by_user_data ()</title>
<indexterm zone="g-source-remove-by-user-data"><primary sortas="source_remove_by_user_data">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>&#160;:</term>
<listitem><simpara> the user_data for the callback.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if a source was found and removed. 
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
