<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<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>

<refsect1 id="glib-The-Main-Event-Loop.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_return" colwidth="150px"/>
<colspec colname="functions_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GMainLoop"><returnvalue>GMainLoop</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-main-loop-new">g_main_loop_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GMainLoop"><returnvalue>GMainLoop</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-main-loop-ref">g_main_loop_ref</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-loop-unref">g_main_loop_unref</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-loop-run">g_main_loop_run</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-loop-quit">g_main_loop_quit</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-loop-is-running">g_main_loop_is_running</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-main-loop-get-context">g_main_loop_get_context</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-main-new">g_main_new</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-main-destroy">g_main_destroy</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-main-run">g_main_run</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-main-quit">g_main_quit</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-main-is-running">g_main_is_running</link><phrase role="c_punctuation">()</phrase></entry></row>



<row><entry role="function_type"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-main-context-new">g_main_context_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-main-context-ref">g_main_context_ref</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-unref">g_main_context_unref</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-main-context-default">g_main_context_default</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-iteration">g_main_context_iteration</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-main-iteration">g_main_iteration</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-pending">g_main_context_pending</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-main-pending">g_main_pending</link></entry></row>
<row><entry role="function_type"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-main-context-find-source-by-id">g_main_context_find_source_by_id</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-main-context-find-source-by-user-data">g_main_context_find_source_by_user_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-main-context-find-source-by-funcs-user-data">g_main_context_find_source_by_funcs_user_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-wakeup">g_main_context_wakeup</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-acquire">g_main_context_acquire</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-release">g_main_context_release</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-is-owner">g_main_context_is_owner</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-wait">g_main_context_wait</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-prepare">g_main_context_prepare</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-query">g_main_context_query</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-check">g_main_context_check</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-dispatch">g_main_context_dispatch</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-set-poll-func">g_main_context_set_poll_func</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GPollFunc"><returnvalue>GPollFunc</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-get-poll-func">g_main_context_get_poll_func</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="GPollFunc">*GPollFunc</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-add-poll">g_main_context_add_poll</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-remove-poll">g_main_context_remove_poll</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-depth">g_main_depth</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-main-current-source">g_main_current_source</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-main-set-poll-func">g_main_set_poll_func</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-invoke">g_main_context_invoke</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-invoke-full">g_main_context_invoke_full</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-main-context-get-thread-default">g_main_context_get_thread_default</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-main-context-ref-thread-default">g_main_context_ref_thread_default</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-push-thread-default">g_main_context_push_thread_default</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-main-context-pop-thread-default">g_main_context_pop_thread_default</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-timeout-source-new">g_timeout_source_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-timeout-source-new-seconds">g_timeout_source_new_seconds</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-timeout-add">g_timeout_add</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-timeout-add-full">g_timeout_add_full</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-timeout-add-seconds">g_timeout_add_seconds</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-timeout-add-seconds-full">g_timeout_add_seconds_full</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-idle-source-new">g_idle_source_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-idle-add">g_idle_add</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-idle-add-full">g_idle_add_full</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-idle-remove-by-data">g_idle_remove_by_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="GChildWatchFunc">*GChildWatchFunc</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-child-watch-source-new">g_child_watch_source_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-child-watch-add">g_child_watch_add</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-child-watch-add-full">g_child_watch_add_full</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-poll">g_poll</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="GSourceDummyMarshal">*GSourceDummyMarshal</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-source-new">g_source_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-source-ref">g_source_ref</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-unref">g_source_unref</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-set-funcs">g_source_set_funcs</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-attach">g_source_attach</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-destroy">g_source_destroy</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-is-destroyed">g_source_is_destroyed</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-set-priority">g_source_set_priority</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-get-priority">g_source_get_priority</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-set-can-recurse">g_source_set_can_recurse</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-get-can-recurse">g_source_get_can_recurse</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-get-id">g_source_get_id</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-source-get-name">g_source_get_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-set-name">g_source_set_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-set-name-by-id">g_source_set_name_by_id</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-source-get-context">g_source_get_context</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-set-callback">g_source_set_callback</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="GSourceFunc">*GSourceFunc</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-SOURCE-FUNC:CAPS">G_SOURCE_FUNC</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-set-callback-indirect">g_source_set_callback_indirect</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-set-ready-time">g_source_set_ready_time</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint64"><returnvalue>gint64</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-get-ready-time">g_source_get_ready_time</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-add-unix-fd">g_source_add_unix_fd</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-remove-unix-fd">g_source_remove_unix_fd</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-modify-unix-fd">g_source_modify_unix_fd</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GIOCondition"><returnvalue>GIOCondition</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-query-unix-fd">g_source_query_unix_fd</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-add-poll">g_source_add_poll</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-remove-poll">g_source_remove_poll</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-add-child-source">g_source_add_child_source</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-remove-child-source">g_source_remove_child_source</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint64"><returnvalue>gint64</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-get-time">g_source_get_time</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-get-current-time">g_source_get_current_time</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-remove">g_source_remove</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-remove-by-funcs-user-data">g_source_remove_by_funcs_user_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-source-remove-by-user-data">g_source_remove_by_user_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="GClearHandleFunc">*GClearHandleFunc</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-clear-handle-id">g_clear_handle_id</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="glib-The-Main-Event-Loop.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="name" colwidth="150px"/>
<colspec colname="description"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GMainLoop">GMainLoop</link></entry></row>

<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-PRIORITY-HIGH:CAPS">G_PRIORITY_HIGH</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-PRIORITY-DEFAULT:CAPS">G_PRIORITY_DEFAULT</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-PRIORITY-HIGH-IDLE:CAPS">G_PRIORITY_HIGH_IDLE</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-PRIORITY-DEFAULT-IDLE:CAPS">G_PRIORITY_DEFAULT_IDLE</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-PRIORITY-LOW:CAPS">G_PRIORITY_LOW</link></entry></row>

<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-SOURCE-CONTINUE:CAPS">G_SOURCE_CONTINUE</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-SOURCE-REMOVE:CAPS">G_SOURCE_REMOVE</link></entry></row>

<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GMainContext">GMainContext</link></entry></row>




<row><entry role="typedef_keyword">typedef</entry><entry role="function_name"><link linkend="GPid">GPid</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-PID-FORMAT:CAPS">G_PID_FORMAT</link></entry></row>

<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GPollFD">GPollFD</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-POLLFD-FORMAT:CAPS">G_POLLFD_FORMAT</link></entry></row>

<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GSource">GSource</link></entry></row>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GSourceFuncs">GSourceFuncs</link></entry></row>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GSourceCallbackFuncs">GSourceCallbackFuncs</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="glib-The-Main-Event-Loop.includes"><title>Includes</title><synopsis>#include &lt;glib.h&gt;
</synopsis></refsect1>

<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 GMainContext 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 GMainLoop 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 GMainContext.</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>
<refsect3><title>Creating new source types</title><para>One of the unusual features of the <link linkend="GMainLoop"><type>GMainLoop</type></link> 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 "deriving" 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 type.</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>
</refsect3>
<refsect3><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>
</refsect3>
<refsect3 id="mainloop-states"><title>State of a Main Context</title><para>The operation of these functions can best be seen in terms
of a state diagram, as shown in this image.</para>
<para><inlinemediaobject><imageobject><imagedata fileref="mainloop-states.gif"></imagedata></imageobject><textobject><phrase></phrase></textobject></inlinemediaobject></para>
<para>On UNIX, the GLib mainloop is incompatible with <link linkend="fork"><function>fork()</function></link>. Any program
using the mainloop must either <link linkend="exec"><function>exec()</function></link> or <link linkend="exit"><function>exit()</function></link> from the child
without returning to the mainloop.</para>
</refsect3>
<refsect3 id="mainloop-memory-management"><title>Memory management of sources</title><para>There are two options for memory management of the user data passed to a
<link linkend="GSource"><type>GSource</type></link> to be passed to its callback on invocation. This data is provided
in calls 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>, etc. and
more generally, using <link linkend="g-source-set-callback"><function>g_source_set_callback()</function></link>. This data is typically an
object which ‘owns’ the timeout or idle callback, such as a widget or a
network protocol implementation. In many cases, it is an error for the
callback to be invoked after this owning object has been destroyed, as that
results in use of freed memory.</para>
<para>The first, and preferred, option is to store the source ID returned by
functions such as <link linkend="g-timeout-add"><function>g_timeout_add()</function></link> or <link linkend="g-source-attach"><function>g_source_attach()</function></link>, and explicitly
remove that source from the main context using <link linkend="g-source-remove"><function>g_source_remove()</function></link> when the
owning object is finalized. This ensures that the callback can only be
invoked while the object is still alive.</para>
<para>The second option is to hold a strong reference to the object in the
callback, and to release it in the callback’s <link linkend="GDestroyNotify"><type>GDestroyNotify</type></link>. This ensures
that the object is kept alive until after the source is finalized, which is
guaranteed to be after it is invoked for the final time. The <link linkend="GDestroyNotify"><type>GDestroyNotify</type></link>
is another callback passed to the ‘full’ variants of <link linkend="GSource"><type>GSource</type></link> functions (for
example, <link linkend="g-timeout-add-full"><function>g_timeout_add_full()</function></link>). It is called when the source is finalized,
and is designed for releasing references like this.</para>
<para>One important caveat of this second approach is that it will keep the object
alive indefinitely if the main loop is stopped before the <link linkend="GSource"><type>GSource</type></link> is
invoked, which may be undesirable.</para>
</refsect3>

</refsect1>
<refsect1 id="glib-The-Main-Event-Loop.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="g-main-loop-new" role="function">
<title>g_main_loop_new&#160;()</title>
<indexterm zone="g-main-loop-new"><primary sortas="main_loop_new">g_main_loop_new</primary></indexterm>
<programlisting language="C"><link linkend="GMainLoop"><returnvalue>GMainLoop</returnvalue></link>&#160;*
g_main_loop_new (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                 <parameter><link linkend="gboolean"><type>gboolean</type></link> is_running</parameter>);</programlisting>
<para>Creates a new <link linkend="GMainLoop"><type>GMainLoop</type></link> structure.</para>
<refsect3 id="g-main-loop-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link>  (if <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the default context will be used). </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>is_running</para></entry>
<entry role="parameter_description"><para>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.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-loop-new.returns" role="returns">
<title>Returns</title>
<para> a new <link linkend="GMainLoop"><type>GMainLoop</type></link>.</para>
</refsect3></refsect2>
<refsect2 id="g-main-loop-ref" role="function">
<title>g_main_loop_ref&#160;()</title>
<indexterm zone="g-main-loop-ref"><primary sortas="main_loop_ref">g_main_loop_ref</primary></indexterm>
<programlisting language="C"><link linkend="GMainLoop"><returnvalue>GMainLoop</returnvalue></link>&#160;*
g_main_loop_ref (<parameter><link linkend="GMainLoop"><type>GMainLoop</type></link> *loop</parameter>);</programlisting>
<para>Increases the reference count on a <link linkend="GMainLoop"><type>GMainLoop</type></link> object by one.</para>
<refsect3 id="g-main-loop-ref.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>loop</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainLoop"><type>GMainLoop</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-loop-ref.returns" role="returns">
<title>Returns</title>
<para> <parameter>loop</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-main-loop-unref" role="function">
<title>g_main_loop_unref&#160;()</title>
<indexterm zone="g-main-loop-unref"><primary sortas="main_loop_unref">g_main_loop_unref</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_loop_unref (<parameter><link linkend="GMainLoop"><type>GMainLoop</type></link> *loop</parameter>);</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>
<refsect3 id="g-main-loop-unref.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>loop</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainLoop"><type>GMainLoop</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-main-loop-run" role="function">
<title>g_main_loop_run&#160;()</title>
<indexterm zone="g-main-loop-run"><primary sortas="main_loop_run">g_main_loop_run</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_loop_run (<parameter><link linkend="GMainLoop"><type>GMainLoop</type></link> *loop</parameter>);</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>
<refsect3 id="g-main-loop-run.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>loop</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainLoop"><type>GMainLoop</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-main-loop-quit" role="function">
<title>g_main_loop_quit&#160;()</title>
<indexterm zone="g-main-loop-quit"><primary sortas="main_loop_quit">g_main_loop_quit</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_loop_quit (<parameter><link linkend="GMainLoop"><type>GMainLoop</type></link> *loop</parameter>);</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>
<refsect3 id="g-main-loop-quit.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>loop</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainLoop"><type>GMainLoop</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-main-loop-is-running" role="function">
<title>g_main_loop_is_running&#160;()</title>
<indexterm zone="g-main-loop-is-running"><primary sortas="main_loop_is_running">g_main_loop_is_running</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_main_loop_is_running (<parameter><link linkend="GMainLoop"><type>GMainLoop</type></link> *loop</parameter>);</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>
<refsect3 id="g-main-loop-is-running.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>loop</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainLoop"><type>GMainLoop</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-loop-is-running.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the mainloop is currently being run.</para>
</refsect3></refsect2>
<refsect2 id="g-main-loop-get-context" role="function">
<title>g_main_loop_get_context&#160;()</title>
<indexterm zone="g-main-loop-get-context"><primary sortas="main_loop_get_context">g_main_loop_get_context</primary></indexterm>
<programlisting language="C"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
g_main_loop_get_context (<parameter><link linkend="GMainLoop"><type>GMainLoop</type></link> *loop</parameter>);</programlisting>
<para>Returns the <link linkend="GMainContext"><type>GMainContext</type></link> of <parameter>loop</parameter>
.</para>
<refsect3 id="g-main-loop-get-context.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>loop</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainLoop"><type>GMainLoop</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-loop-get-context.returns" role="returns">
<title>Returns</title>
<para>the <link linkend="GMainContext"><type>GMainContext</type></link> of <parameter>loop</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></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 language="C">#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.</para> <para>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 th default main context.</para>
<refsect3 id="g-main-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>is_running</para></entry>
<entry role="parameter_description"><para>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.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-new.returns" role="returns">
<title>Returns</title>
<para> a new <link linkend="GMainLoop"><type>GMainLoop</type></link></para>
</refsect3></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 language="C">#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.</para> <para>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>
<refsect3 id="g-main-destroy.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>loop</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainLoop"><type>GMainLoop</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></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 language="C">#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.</para> <para>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>
<refsect3 id="g-main-run.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>loop</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainLoop"><type>GMainLoop</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></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 language="C">#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.</para> <para>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>
<refsect3 id="g-main-quit.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>loop</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainLoop"><type>GMainLoop</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></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 language="C">#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.</para> <para>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>
<refsect3 id="g-main-is-running.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>loop</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainLoop"><type>GMainLoop</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-is-running.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the main loop is running</para>
</refsect3></refsect2>
<refsect2 id="g-main-context-new" role="function">
<title>g_main_context_new&#160;()</title>
<indexterm zone="g-main-context-new"><primary sortas="main_context_new">g_main_context_new</primary></indexterm>
<programlisting language="C"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
g_main_context_new (<parameter><type>void</type></parameter>);</programlisting>
<para>Creates a new <link linkend="GMainContext"><type>GMainContext</type></link> structure.</para>
<refsect3 id="g-main-context-new.returns" role="returns">
<title>Returns</title>
<para> the new <link linkend="GMainContext"><type>GMainContext</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-main-context-ref" role="function">
<title>g_main_context_ref&#160;()</title>
<indexterm zone="g-main-context-ref"><primary sortas="main_context_ref">g_main_context_ref</primary></indexterm>
<programlisting language="C"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
g_main_context_ref (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>);</programlisting>
<para>Increases the reference count on a <link linkend="GMainContext"><type>GMainContext</type></link> object by one.</para>
<refsect3 id="g-main-context-ref.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-ref.returns" role="returns">
<title>Returns</title>
<para> the <parameter>context</parameter>
that was passed in (since 2.6)</para>
</refsect3></refsect2>
<refsect2 id="g-main-context-unref" role="function">
<title>g_main_context_unref&#160;()</title>
<indexterm zone="g-main-context-unref"><primary sortas="main_context_unref">g_main_context_unref</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_context_unref (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>);</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>
<refsect3 id="g-main-context-unref.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-main-context-default" role="function">
<title>g_main_context_default&#160;()</title>
<indexterm zone="g-main-context-default"><primary sortas="main_context_default">g_main_context_default</primary></indexterm>
<programlisting language="C"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
g_main_context_default (<parameter><type>void</type></parameter>);</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>
<refsect3 id="g-main-context-default.returns" role="returns">
<title>Returns</title>
<para>the global default main context. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-main-context-iteration" role="function">
<title>g_main_context_iteration&#160;()</title>
<indexterm zone="g-main-context-iteration"><primary sortas="main_context_iteration">g_main_context_iteration</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_main_context_iteration (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                          <parameter><link linkend="gboolean"><type>gboolean</type></link> may_block</parameter>);</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 wait may
be interrupted for other reasons than an event source becoming ready.</para>
<refsect3 id="g-main-context-iteration.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link> (if <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the default context will be used). </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>may_block</para></entry>
<entry role="parameter_description"><para>whether the call may block.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-iteration.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if events were dispatched.</para>
</refsect3></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 language="C">#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.</para> <para>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>
<refsect3 id="g-main-iteration.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>may_block</para></entry>
<entry role="parameter_description"><para>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.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-iteration.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if more events are pending.</para>
</refsect3></refsect2>
<refsect2 id="g-main-context-pending" role="function">
<title>g_main_context_pending&#160;()</title>
<indexterm zone="g-main-context-pending"><primary sortas="main_context_pending">g_main_context_pending</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_main_context_pending (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>);</programlisting>
<para>Checks if any sources have pending events for the given context.</para>
<refsect3 id="g-main-context-pending.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link> (if <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the default context will be used). </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-pending.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if events are pending.</para>
</refsect3></refsect2>
<refsect2 id="g-main-pending" role="macro" condition="deprecated:">
<title>g_main_pending</title>
<indexterm zone="g-main-pending" role="deprecated"><primary sortas="main_pending">g_main_pending</primary></indexterm>
<programlisting language="C">#define             g_main_pending()</programlisting>
<warning><para><literal>g_main_pending</literal> is deprecated and should not be used in newly-written code.</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>
<refsect3 id="g-main-pending.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if any events are pending.</para>
<para>Deprected: 2.2: Use <link linkend="g-main-context-pending"><function>g_main_context_pending()</function></link> instead.</para>
</refsect3></refsect2>
<refsect2 id="g-main-context-find-source-by-id" role="function">
<title>g_main_context_find_source_by_id&#160;()</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 language="C"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
g_main_context_find_source_by_id (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                                  <parameter><link linkend="guint"><type>guint</type></link> source_id</parameter>);</programlisting>
<para>Finds a <link linkend="GSource"><type>GSource</type></link> given a pair of context and ID.</para>
<para>It is a programmer error to attempt to lookup a non-existent source.</para>
<para>More specifically: source IDs can be reissued after a source has been
destroyed and therefore it is never valid to use this function with a
source ID which may have already been removed.  An example is when
scheduling an idle to run in another thread with <link linkend="g-idle-add"><function>g_idle_add()</function></link>: the
idle may already have run and been removed by the time this function
is called on its (now invalid) source ID.  This source ID may have
been reissued, leading to the operation being performed against the
wrong source.</para>
<refsect3 id="g-main-context-find-source-by-id.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link> (if <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the default context will be used). </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>source_id</para></entry>
<entry role="parameter_description"><para>the source ID, as returned by <link linkend="g-source-get-id"><function>g_source_get_id()</function></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-find-source-by-id.returns" role="returns">
<title>Returns</title>
<para>the <link linkend="GSource"><type>GSource</type></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-main-context-find-source-by-user-data" role="function">
<title>g_main_context_find_source_by_user_data&#160;()</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 language="C"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
g_main_context_find_source_by_user_data
                               (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                                <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</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>
<refsect3 id="g-main-context-find-source-by-user-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>the user_data for the callback.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-find-source-by-user-data.returns" role="returns">
<title>Returns</title>
<para>the source, if one was found, otherwise <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-main-context-find-source-by-funcs-user-data" role="function">
<title>g_main_context_find_source_by_funcs_user_data&#160;()</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 language="C"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
g_main_context_find_source_by_funcs_user_data
                               (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                                <parameter><link linkend="GSourceFuncs"><type>GSourceFuncs</type></link> *funcs</parameter>,
                                <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</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>
<refsect3 id="g-main-context-find-source-by-funcs-user-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link> (if <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the default context will be used). </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>funcs</para></entry>
<entry role="parameter_description"><para>the <parameter>source_funcs</parameter>
passed to <link linkend="g-source-new"><function>g_source_new()</function></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>the user data from the callback.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-find-source-by-funcs-user-data.returns" role="returns">
<title>Returns</title>
<para>the source, if one was found, otherwise <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-main-context-wakeup" role="function">
<title>g_main_context_wakeup&#160;()</title>
<indexterm zone="g-main-context-wakeup"><primary sortas="main_context_wakeup">g_main_context_wakeup</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_context_wakeup (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>);</programlisting>
<para>If <parameter>context</parameter>
 is currently blocking in <link linkend="g-main-context-iteration"><function>g_main_context_iteration()</function></link>
waiting for a source to become ready, cause it to stop blocking
and return.  Otherwise, cause the next invocation of
<link linkend="g-main-context-iteration"><function>g_main_context_iteration()</function></link> to return without blocking.</para>
<para>This API is useful for low-level control over <link linkend="GMainContext"><type>GMainContext</type></link>; for
example, integrating it with main loop implementations such as
<link linkend="GMainLoop"><type>GMainLoop</type></link>.</para>
<para>Another related use for this function is when implementing a main
loop with a termination condition, computed from multiple threads:</para>
<informalexample><programlisting role="example"><![CDATA[
  #define NUM_TASKS 10
  static volatile gint tasks_remaining = NUM_TASKS;
  ...
 
  while (g_atomic_int_get (&tasks_remaining) != 0)
    g_main_context_iteration (NULL, TRUE);
]]></programlisting></informalexample>
<para></para>
<para>Then in a thread:</para>
<informalexample><programlisting role="example"><![CDATA[
  perform_work();

  if (g_atomic_int_dec_and_test (&tasks_remaining))
    g_main_context_wakeup (NULL);
]]></programlisting></informalexample>
<para></para>
<refsect3 id="g-main-context-wakeup.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-main-context-acquire" role="function">
<title>g_main_context_acquire&#160;()</title>
<indexterm zone="g-main-context-acquire"><primary sortas="main_context_acquire">g_main_context_acquire</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_main_context_acquire (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>);</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>
<refsect3 id="g-main-context-acquire.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-acquire.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the operation succeeded, and
this thread is now the owner of <parameter>context</parameter>
.</para>
</refsect3></refsect2>
<refsect2 id="g-main-context-release" role="function">
<title>g_main_context_release&#160;()</title>
<indexterm zone="g-main-context-release"><primary sortas="main_context_release">g_main_context_release</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_context_release (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>);</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>
<refsect3 id="g-main-context-release.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-main-context-is-owner" role="function" condition="since:2.10">
<title>g_main_context_is_owner&#160;()</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 language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_main_context_is_owner (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>);</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>
<refsect3 id="g-main-context-is-owner.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-is-owner.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if current thread is owner of <parameter>context</parameter>
.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.10">2.10</link></para></refsect2>
<refsect2 id="g-main-context-wait" role="function" condition="deprecated:2.58: Use g_main_context_is_owner() and separate locking instead.">
<title>g_main_context_wait&#160;()</title>
<indexterm zone="g-main-context-wait" role="deprecated"><primary sortas="main_context_wait">g_main_context_wait</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_main_context_wait (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                     <parameter><link linkend="GCond"><type>GCond</type></link> *cond</parameter>,
                     <parameter><link linkend="GMutex"><type>GMutex</type></link> *mutex</parameter>);</programlisting>
<warning><para><literal>g_main_context_wait</literal> has been deprecated since version 2.58 and should not be used in newly-written code.</para> <para>Use <link linkend="g-main-context-is-owner"><function>g_main_context_is_owner()</function></link> and separate locking instead.</para>
</warning>
<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>
<refsect3 id="g-main-context-wait.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>cond</para></entry>
<entry role="parameter_description"><para>a condition variable</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>mutex</para></entry>
<entry role="parameter_description"><para>a mutex, currently held</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-wait.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the operation succeeded, and
this thread is now the owner of <parameter>context</parameter>
.</para>
</refsect3></refsect2>
<refsect2 id="g-main-context-prepare" role="function">
<title>g_main_context_prepare&#160;()</title>
<indexterm zone="g-main-context-prepare"><primary sortas="main_context_prepare">g_main_context_prepare</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_main_context_prepare (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                        <parameter><link linkend="gint"><type>gint</type></link> *priority</parameter>);</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>You must have successfully acquired the context with
<link linkend="g-main-context-acquire"><function>g_main_context_acquire()</function></link> before you may call this function.</para>
<refsect3 id="g-main-context-prepare.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>priority</para></entry>
<entry role="parameter_description"><para>location to store priority of highest priority
source already ready.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-prepare.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if some source is ready to be dispatched
prior to polling.</para>
</refsect3></refsect2>
<refsect2 id="g-main-context-query" role="function">
<title>g_main_context_query&#160;()</title>
<indexterm zone="g-main-context-query"><primary sortas="main_context_query">g_main_context_query</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_main_context_query (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                      <parameter><link linkend="gint"><type>gint</type></link> max_priority</parameter>,
                      <parameter><link linkend="gint"><type>gint</type></link> *timeout_</parameter>,
                      <parameter><link linkend="GPollFD"><type>GPollFD</type></link> *fds</parameter>,
                      <parameter><link linkend="gint"><type>gint</type></link> n_fds</parameter>);</programlisting>
<para>Determines information necessary to poll this main loop.</para>
<para>You must have successfully acquired the context with
<link linkend="g-main-context-acquire"><function>g_main_context_acquire()</function></link> before you may call this function.</para>
<refsect3 id="g-main-context-query.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>max_priority</para></entry>
<entry role="parameter_description"><para>maximum priority source to check</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>timeout_</para></entry>
<entry role="parameter_description"><para>location to store timeout to be used in polling. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>fds</para></entry>
<entry role="parameter_description"><para>location to
store <link linkend="GPollFD"><type>GPollFD</type></link> records that need to be polled. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out caller-allocates</acronym>][<acronym>array</acronym> length=n_fds]</emphasis></entry></row>
<row><entry role="parameter_name"><para>n_fds</para></entry>
<entry role="parameter_description"><para>length of <parameter>fds</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>in</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-query.returns" role="returns">
<title>Returns</title>
<para> 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.</para>
</refsect3></refsect2>
<refsect2 id="g-main-context-check" role="function">
<title>g_main_context_check&#160;()</title>
<indexterm zone="g-main-context-check"><primary sortas="main_context_check">g_main_context_check</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_main_context_check (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                      <parameter><link linkend="gint"><type>gint</type></link> max_priority</parameter>,
                      <parameter><link linkend="GPollFD"><type>GPollFD</type></link> *fds</parameter>,
                      <parameter><link linkend="gint"><type>gint</type></link> n_fds</parameter>);</programlisting>
<para>Passes the results of polling back to the main loop.</para>
<para>You must have successfully acquired the context with
<link linkend="g-main-context-acquire"><function>g_main_context_acquire()</function></link> before you may call this function.</para>
<refsect3 id="g-main-context-check.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>max_priority</para></entry>
<entry role="parameter_description"><para>the maximum numerical priority of sources to check</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>fds</para></entry>
<entry role="parameter_description"><para>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>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=n_fds]</emphasis></entry></row>
<row><entry role="parameter_name"><para>n_fds</para></entry>
<entry role="parameter_description"><para>return value of <link linkend="g-main-context-query"><function>g_main_context_query()</function></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-check.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if some sources are ready to be dispatched.</para>
</refsect3></refsect2>
<refsect2 id="g-main-context-dispatch" role="function">
<title>g_main_context_dispatch&#160;()</title>
<indexterm zone="g-main-context-dispatch"><primary sortas="main_context_dispatch">g_main_context_dispatch</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_context_dispatch (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>);</programlisting>
<para>Dispatches all pending sources.</para>
<para>You must have successfully acquired the context with
<link linkend="g-main-context-acquire"><function>g_main_context_acquire()</function></link> before you may call this function.</para>
<refsect3 id="g-main-context-dispatch.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-main-context-set-poll-func" role="function">
<title>g_main_context_set_poll_func&#160;()</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 language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_context_set_poll_func (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                              <parameter><link linkend="GPollFunc"><type>GPollFunc</type></link> func</parameter>);</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>
<refsect3 id="g-main-context-set-poll-func.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>func</para></entry>
<entry role="parameter_description"><para>the function to call to poll all file descriptors</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-main-context-get-poll-func" role="function">
<title>g_main_context_get_poll_func&#160;()</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 language="C"><link linkend="GPollFunc"><returnvalue>GPollFunc</returnvalue></link>
g_main_context_get_poll_func (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>);</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>
<refsect3 id="g-main-context-get-poll-func.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-main-context-get-poll-func.returns" role="returns">
<title>Returns</title>
<para> the poll function</para>
</refsect3></refsect2>
<refsect2 id="GPollFunc" role="function">
<title>GPollFunc&#160;()</title>
<indexterm zone="GPollFunc"><primary sortas="PollFunc">GPollFunc</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
<phrase role="c_punctuation">(</phrase>*GPollFunc<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="GPollFD"><type>GPollFD</type></link> *ufds</parameter>,
              <parameter><link linkend="guint"><type>guint</type></link> nfsd</parameter>,
              <parameter><link linkend="gint"><type>gint</type></link> timeout_</parameter>);</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 <link linkend="poll"><function>poll()</function></link> system call.</para>
<refsect3 id="GPollFunc.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>ufds</para></entry>
<entry role="parameter_description"><para>an array of <link linkend="GPollFD"><type>GPollFD</type></link> elements</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>nfsd</para></entry>
<entry role="parameter_description"><para>the number of elements in <parameter>ufds</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>timeout_</para></entry>
<entry role="parameter_description"><para>the maximum time to wait for an event of the file descriptors.
A negative value indicates an infinite timeout.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="GPollFunc.returns" role="returns">
<title>Returns</title>
<para> the number of <link linkend="GPollFD"><type>GPollFD</type></link> elements which have events or errors
reported, or -1 if an error occurred.</para>
</refsect3></refsect2>
<refsect2 id="g-main-context-add-poll" role="function">
<title>g_main_context_add_poll&#160;()</title>
<indexterm zone="g-main-context-add-poll"><primary sortas="main_context_add_poll">g_main_context_add_poll</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_context_add_poll (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                         <parameter><link linkend="GPollFD"><type>GPollFD</type></link> *fd</parameter>,
                         <parameter><link linkend="gint"><type>gint</type></link> priority</parameter>);</programlisting>
<para>Adds a file descriptor to the set of file descriptors polled for
this context. This will very seldom be used directly. Instead
a typical event source will use <link linkend="g-source-add-unix-fd"><function>g_source_add_unix_fd()</function></link> instead.</para>
<refsect3 id="g-main-context-add-poll.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link> (or <link linkend="NULL:CAPS"><literal>NULL</literal></link> for the default context). </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>fd</para></entry>
<entry role="parameter_description"><para>a <link linkend="GPollFD"><type>GPollFD</type></link> structure holding information about a file
descriptor to watch.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>priority</para></entry>
<entry role="parameter_description"><para>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.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-main-context-remove-poll" role="function">
<title>g_main_context_remove_poll&#160;()</title>
<indexterm zone="g-main-context-remove-poll"><primary sortas="main_context_remove_poll">g_main_context_remove_poll</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_context_remove_poll (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                            <parameter><link linkend="GPollFD"><type>GPollFD</type></link> *fd</parameter>);</programlisting>
<para>Removes file descriptor from the set of file descriptors to be
polled for a particular context.</para>
<refsect3 id="g-main-context-remove-poll.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link> </para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>fd</para></entry>
<entry role="parameter_description"><para>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></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-main-depth" role="function">
<title>g_main_depth&#160;()</title>
<indexterm zone="g-main-depth"><primary sortas="main_depth">g_main_depth</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_main_depth (<parameter><type>void</type></parameter>);</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-iteration"><function>g_main_context_iteration()</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>
<informalexample><programlisting role="example"><![CDATA[
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>
<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>
<informalexample><programlisting role="example"><![CDATA[
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 > depth)
        {
          g_free (block->mem);
          g_free (block);
          free_list = g_list_delete_link (free_list, l);
        }
              
      l = next;
    }
  }
]]></programlisting></informalexample>
<para></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>
<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>
<refsect3 id="g-main-depth.returns" role="returns">
<title>Returns</title>
<para> The main loop recursion level in the current thread</para>
</refsect3></refsect2>
<refsect2 id="g-main-current-source" role="function" condition="since:2.12">
<title>g_main_current_source&#160;()</title>
<indexterm zone="g-main-current-source" role="2.12"><primary sortas="main_current_source">g_main_current_source</primary></indexterm>
<programlisting language="C"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
g_main_current_source (<parameter><type>void</type></parameter>);</programlisting>
<para>Returns the currently firing source for this thread.</para>
<refsect3 id="g-main-current-source.returns" role="returns">
<title>Returns</title>
<para>The currently firing source or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.12">2.12</link></para></refsect2>
<refsect2 id="g-main-set-poll-func" role="macro" condition="deprecated:2.2: Use g_main_context_set_poll_func() again">
<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 language="C">#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.</para> <para>Use <link linkend="g-main-context-set-poll-func"><function>g_main_context_set_poll_func()</function></link> again</para>
</warning>
<para>Sets the function to use for the handle polling of file descriptors
for the default main context.</para>
<refsect3 id="g-main-set-poll-func.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>func</para></entry>
<entry role="parameter_description"><para>the function to call to poll all file descriptors</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-main-context-invoke" role="function" condition="since:2.28">
<title>g_main_context_invoke&#160;()</title>
<indexterm zone="g-main-context-invoke" role="2.28"><primary sortas="main_context_invoke">g_main_context_invoke</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_context_invoke (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                       <parameter><link linkend="GSourceFunc"><type>GSourceFunc</type></link> function</parameter>,
                       <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>);</programlisting>
<para>Invokes a function in such a way that <parameter>context</parameter>
 is owned during the
invocation of <parameter>function</parameter>
.</para>
<para>If <parameter>context</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link> then the global default main context — as
returned by <link linkend="g-main-context-default"><function>g_main_context_default()</function></link> — is used.</para>
<para>If <parameter>context</parameter>
 is owned by the current thread, <parameter>function</parameter>
 is called
directly.  Otherwise, if <parameter>context</parameter>
 is the thread-default main context
of the current thread and <link linkend="g-main-context-acquire"><function>g_main_context_acquire()</function></link> succeeds, then
<parameter>function</parameter>
 is called and <link linkend="g-main-context-release"><function>g_main_context_release()</function></link> is called
afterwards.</para>
<para>In any other case, an idle source is created to call <parameter>function</parameter>
 and
that source is attached to <parameter>context</parameter>
 (presumably to be run in another
thread).  The idle source is attached with <link linkend="G-PRIORITY-DEFAULT:CAPS"><type>G_PRIORITY_DEFAULT</type></link>
priority.  If you want a different priority, use
<link linkend="g-main-context-invoke-full"><function>g_main_context_invoke_full()</function></link>.</para>
<para>Note that, as with normal idle functions, <parameter>function</parameter>
 should probably
return <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>.  If it returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, it will be continuously run in a
loop (and may prevent this call from returning).</para>
<refsect3 id="g-main-context-invoke.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>function</para></entry>
<entry role="parameter_description"><para>function to call</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>data to pass to <parameter>function</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.28">2.28</link></para></refsect2>
<refsect2 id="g-main-context-invoke-full" role="function" condition="since:2.28">
<title>g_main_context_invoke_full&#160;()</title>
<indexterm zone="g-main-context-invoke-full" role="2.28"><primary sortas="main_context_invoke_full">g_main_context_invoke_full</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_context_invoke_full (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>,
                            <parameter><link linkend="gint"><type>gint</type></link> priority</parameter>,
                            <parameter><link linkend="GSourceFunc"><type>GSourceFunc</type></link> function</parameter>,
                            <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>,
                            <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> notify</parameter>);</programlisting>
<para>Invokes a function in such a way that <parameter>context</parameter>
 is owned during the
invocation of <parameter>function</parameter>
.</para>
<para>This function is the same as <link linkend="g-main-context-invoke"><function>g_main_context_invoke()</function></link> except that it
lets you specify the priority in case <parameter>function</parameter>
 ends up being
scheduled as an idle and also lets you give a <link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> for <parameter>data</parameter>
.</para>
<para><parameter>notify</parameter>
 should not assume that it is called from any particular
thread or with any particular context acquired.</para>
<refsect3 id="g-main-context-invoke-full.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>priority</para></entry>
<entry role="parameter_description"><para>the priority at which to run <parameter>function</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>function</para></entry>
<entry role="parameter_description"><para>function to call</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>data to pass to <parameter>function</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>notify</para></entry>
<entry role="parameter_description"><para>a function to call when <parameter>data</parameter>
is no longer in use, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.28">2.28</link></para></refsect2>
<refsect2 id="g-main-context-get-thread-default" role="function" condition="since:2.22">
<title>g_main_context_get_thread_default&#160;()</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 language="C"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
g_main_context_get_thread_default (<parameter><type>void</type></parameter>);</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 or
<link linkend="g-main-context-ref-thread-default"><function>g_main_context_ref_thread_default()</function></link> to get a <link linkend="GMainContext"><type>GMainContext</type></link> to add
their <link linkend="GSources"><type>GSources</type></link> 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 you are running in the default thread.)</para>
<para>If you need to hold a reference on the context, use
<link linkend="g-main-context-ref-thread-default"><function>g_main_context_ref_thread_default()</function></link> instead.</para>
<refsect3 id="g-main-context-get-thread-default.returns" role="returns">
<title>Returns</title>
<para>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. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.22">2.22</link></para></refsect2>
<refsect2 id="g-main-context-ref-thread-default" role="function" condition="since:2.32">
<title>g_main_context_ref_thread_default&#160;()</title>
<indexterm zone="g-main-context-ref-thread-default" role="2.32"><primary sortas="main_context_ref_thread_default">g_main_context_ref_thread_default</primary></indexterm>
<programlisting language="C"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
g_main_context_ref_thread_default (<parameter><type>void</type></parameter>);</programlisting>
<para>Gets the thread-default <link linkend="GMainContext"><type>GMainContext</type></link> for this thread, as with
<link linkend="g-main-context-get-thread-default"><function>g_main_context_get_thread_default()</function></link>, but also adds a reference to
it with <link linkend="g-main-context-ref"><function>g_main_context_ref()</function></link>. In addition, unlike
<link linkend="g-main-context-get-thread-default"><function>g_main_context_get_thread_default()</function></link>, if the thread-default context
is the global default context, this will return that <link linkend="GMainContext"><type>GMainContext</type></link>
(with a ref added to it) rather than returning <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
<refsect3 id="g-main-context-ref-thread-default.returns" role="returns">
<title>Returns</title>
<para>the thread-default <link linkend="GMainContext"><type>GMainContext</type></link>. Unref
with <link linkend="g-main-context-unref"><function>g_main_context_unref()</function></link> when you are done with it. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.32">2.32</link></para></refsect2>
<refsect2 id="g-main-context-push-thread-default" role="function" condition="since:2.22">
<title>g_main_context_push_thread_default&#160;()</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 language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_context_push_thread_default (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>);</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>,
not 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 may not need to
ever call <link linkend="g-main-context-pop-thread-default"><function>g_main_context_pop_thread_default()</function></link>, assuming you want the
new <link linkend="GMainContext"><type>GMainContext</type></link> to be the default for the whole lifecycle of the
thread.</para>
<para>If you don't have control over how the new thread was created (e.g.
in the new thread isn't newly created, or if the thread life
cycle is managed by a <link linkend="GThreadPool"><type>GThreadPool</type></link>), it is always suggested to wrap
the logic that needs to use the new <link linkend="GMainContext"><type>GMainContext</type></link> 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, otherwise threads that are re-used will end up never explicitly
releasing the <link linkend="GMainContext"><type>GMainContext</type></link> reference they hold.</para>
<para>In some cases 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>
<refsect3 id="g-main-context-push-thread-default.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> for the global default context. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.22">2.22</link></para></refsect2>
<refsect2 id="g-main-context-pop-thread-default" role="function" condition="since:2.22">
<title>g_main_context_pop_thread_default&#160;()</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 language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_main_context_pop_thread_default (<parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>);</programlisting>
<para>Pops <parameter>context</parameter>
 off the thread-default context stack (verifying that
it was on the top of the stack).</para>
<refsect3 id="g-main-context-pop-thread-default.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link> object, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.22">2.22</link></para></refsect2>
<refsect2 id="g-timeout-source-new" role="function">
<title>g_timeout_source_new&#160;()</title>
<indexterm zone="g-timeout-source-new"><primary sortas="timeout_source_new">g_timeout_source_new</primary></indexterm>
<programlisting language="C"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
g_timeout_source_new (<parameter><link linkend="guint"><type>guint</type></link> interval</parameter>);</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 interval given is in terms of monotonic time, not wall clock
time.  See <link linkend="g-get-monotonic-time"><function>g_get_monotonic_time()</function></link>.</para>
<refsect3 id="g-timeout-source-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>interval</para></entry>
<entry role="parameter_description"><para>the timeout interval in milliseconds.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-timeout-source-new.returns" role="returns">
<title>Returns</title>
<para> the newly-created timeout source</para>
</refsect3></refsect2>
<refsect2 id="g-timeout-source-new-seconds" role="function" condition="since:2.14">
<title>g_timeout_source_new_seconds&#160;()</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 language="C"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
g_timeout_source_new_seconds (<parameter><link linkend="guint"><type>guint</type></link> interval</parameter>);</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>The interval given is in terms of monotonic time, not wall clock time.
See <link linkend="g-get-monotonic-time"><function>g_get_monotonic_time()</function></link>.</para>
<refsect3 id="g-timeout-source-new-seconds.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>interval</para></entry>
<entry role="parameter_description"><para>the timeout interval in seconds</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-timeout-source-new-seconds.returns" role="returns">
<title>Returns</title>
<para> the newly-created timeout source</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.14">2.14</link></para></refsect2>
<refsect2 id="g-timeout-add" role="function">
<title>g_timeout_add&#160;()</title>
<indexterm zone="g-timeout-add"><primary sortas="timeout_add">g_timeout_add</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_timeout_add (<parameter><link linkend="guint"><type>guint</type></link> interval</parameter>,
               <parameter><link linkend="GSourceFunc"><type>GSourceFunc</type></link> function</parameter>,
               <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>);</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>See <link linkend="mainloop-memory-management">memory management of sources</link> for details
on how to handle the return value and memory management of <parameter>data</parameter>
.</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 global <link linkend="GMainContext"><type>GMainContext</type></link> using <link linkend="g-source-attach"><function>g_source_attach()</function></link>, so
the callback will be invoked in whichever thread is running that main
context. You can do these steps manually if you need greater control or to
use a custom main context.</para>
<para>The interval given is in terms of monotonic time, not wall clock
time.  See <link linkend="g-get-monotonic-time"><function>g_get_monotonic_time()</function></link>.</para>
<refsect3 id="g-timeout-add.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>interval</para></entry>
<entry role="parameter_description"><para>the time between calls to the function, in milliseconds
(1/1000ths of a second)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>function</para></entry>
<entry role="parameter_description"><para>function to call</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>data to pass to <parameter>function</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-timeout-add.returns" role="returns">
<title>Returns</title>
<para> the ID (greater than 0) of the event source.</para>
</refsect3></refsect2>
<refsect2 id="g-timeout-add-full" role="function">
<title>g_timeout_add_full&#160;()</title>
<indexterm zone="g-timeout-add-full"><primary sortas="timeout_add_full">g_timeout_add_full</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_timeout_add_full (<parameter><link linkend="gint"><type>gint</type></link> priority</parameter>,
                    <parameter><link linkend="guint"><type>guint</type></link> interval</parameter>,
                    <parameter><link linkend="GSourceFunc"><type>GSourceFunc</type></link> function</parameter>,
                    <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>,
                    <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> notify</parameter>);</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>See <link linkend="mainloop-memory-management">memory management of sources</link> for details
on how to handle the return value and memory management of <parameter>data</parameter>
.</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 global <link linkend="GMainContext"><type>GMainContext</type></link> using <link linkend="g-source-attach"><function>g_source_attach()</function></link>, so
the callback will be invoked in whichever thread is running that main
context. You can do these steps manually if you need greater control or to
use a custom main context.</para>
<para>The interval given is in terms of monotonic time, not wall clock time.
See <link linkend="g-get-monotonic-time"><function>g_get_monotonic_time()</function></link>.</para>

<para><emphasis role="annotation">[<acronym>rename-to</acronym> g_timeout_add]</emphasis></para><refsect3 id="g-timeout-add-full.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>priority</para></entry>
<entry role="parameter_description"><para>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>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>interval</para></entry>
<entry role="parameter_description"><para>the time between calls to the function, in milliseconds
(1/1000ths of a second)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>function</para></entry>
<entry role="parameter_description"><para>function to call</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>data to pass to <parameter>function</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>notify</para></entry>
<entry role="parameter_description"><para>function to call when the timeout is removed, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-timeout-add-full.returns" role="returns">
<title>Returns</title>
<para> the ID (greater than 0) of the event source.</para>
</refsect3></refsect2>
<refsect2 id="g-timeout-add-seconds" role="function" condition="since:2.14">
<title>g_timeout_add_seconds&#160;()</title>
<indexterm zone="g-timeout-add-seconds" role="2.14"><primary sortas="timeout_add_seconds">g_timeout_add_seconds</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_timeout_add_seconds (<parameter><link linkend="guint"><type>guint</type></link> interval</parameter>,
                       <parameter><link linkend="GSourceFunc"><type>GSourceFunc</type></link> function</parameter>,
                       <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>);</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-timeout-add-seconds-full"><function>g_timeout_add_seconds_full()</function></link>.</para>
<para>Note that the first call of the timer may not be precise for timeouts
of one second. If you need finer precision and have such a timeout,
you may want to use <link linkend="g-timeout-add"><function>g_timeout_add()</function></link> instead.</para>
<para>See <link linkend="mainloop-memory-management">memory management of sources</link> for details
on how to handle the return value and memory management of <parameter>data</parameter>
.</para>
<para>The interval given is in terms of monotonic time, not wall clock
time.  See <link linkend="g-get-monotonic-time"><function>g_get_monotonic_time()</function></link>.</para>
<refsect3 id="g-timeout-add-seconds.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>interval</para></entry>
<entry role="parameter_description"><para>the time between calls to the function, in seconds</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>function</para></entry>
<entry role="parameter_description"><para>function to call</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>data to pass to <parameter>function</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-timeout-add-seconds.returns" role="returns">
<title>Returns</title>
<para> the ID (greater than 0) of the event source.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.14">2.14</link></para></refsect2>
<refsect2 id="g-timeout-add-seconds-full" role="function" condition="since:2.14">
<title>g_timeout_add_seconds_full&#160;()</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 language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_timeout_add_seconds_full (<parameter><link linkend="gint"><type>gint</type></link> priority</parameter>,
                            <parameter><link linkend="guint"><type>guint</type></link> interval</parameter>,
                            <parameter><link linkend="GSourceFunc"><type>GSourceFunc</type></link> function</parameter>,
                            <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>,
                            <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> notify</parameter>);</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>See <link linkend="mainloop-memory-management">memory management of sources</link> for details
on how to handle the return value and memory management of <parameter>data</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>The interval given is in terms of monotonic time, not wall clock
time.  See <link linkend="g-get-monotonic-time"><function>g_get_monotonic_time()</function></link>.</para>

<para><emphasis role="annotation">[<acronym>rename-to</acronym> g_timeout_add_seconds]</emphasis></para><refsect3 id="g-timeout-add-seconds-full.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>priority</para></entry>
<entry role="parameter_description"><para>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>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>interval</para></entry>
<entry role="parameter_description"><para>the time between calls to the function, in seconds</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>function</para></entry>
<entry role="parameter_description"><para>function to call</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>data to pass to <parameter>function</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>notify</para></entry>
<entry role="parameter_description"><para>function to call when the timeout is removed, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-timeout-add-seconds-full.returns" role="returns">
<title>Returns</title>
<para> the ID (greater than 0) of the event source.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.14">2.14</link></para></refsect2>
<refsect2 id="g-idle-source-new" role="function">
<title>g_idle_source_new&#160;()</title>
<indexterm zone="g-idle-source-new"><primary sortas="idle_source_new">g_idle_source_new</primary></indexterm>
<programlisting language="C"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
g_idle_source_new (<parameter><type>void</type></parameter>);</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>
<refsect3 id="g-idle-source-new.returns" role="returns">
<title>Returns</title>
<para> the newly-created idle source</para>
</refsect3></refsect2>
<refsect2 id="g-idle-add" role="function">
<title>g_idle_add&#160;()</title>
<indexterm zone="g-idle-add"><primary sortas="idle_add">g_idle_add</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_idle_add (<parameter><link linkend="GSourceFunc"><type>GSourceFunc</type></link> function</parameter>,
            <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>);</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>See <link linkend="mainloop-memory-management">memory management of sources</link> for details
on how to handle the return value and memory management of <parameter>data</parameter>
.</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 global <link linkend="GMainContext"><type>GMainContext</type></link> using <link linkend="g-source-attach"><function>g_source_attach()</function></link>, so
the callback will be invoked in whichever thread is running that main
context. You can do these steps manually if you need greater control or to
use a custom main context.</para>
<refsect3 id="g-idle-add.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>function</para></entry>
<entry role="parameter_description"><para>function to call </para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>data to pass to <parameter>function</parameter>
.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-idle-add.returns" role="returns">
<title>Returns</title>
<para> the ID (greater than 0) of the event source.</para>
</refsect3></refsect2>
<refsect2 id="g-idle-add-full" role="function">
<title>g_idle_add_full&#160;()</title>
<indexterm zone="g-idle-add-full"><primary sortas="idle_add_full">g_idle_add_full</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_idle_add_full (<parameter><link linkend="gint"><type>gint</type></link> priority</parameter>,
                 <parameter><link linkend="GSourceFunc"><type>GSourceFunc</type></link> function</parameter>,
                 <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>,
                 <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> notify</parameter>);</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>See <link linkend="mainloop-memory-management">memory management of sources</link> for details
on how to handle the return value and memory management of <parameter>data</parameter>
.</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 global <link linkend="GMainContext"><type>GMainContext</type></link> using <link linkend="g-source-attach"><function>g_source_attach()</function></link>, so
the callback will be invoked in whichever thread is running that main
context. You can do these steps manually if you need greater control or to
use a custom main context.</para>

<para><emphasis role="annotation">[<acronym>rename-to</acronym> g_idle_add]</emphasis></para><refsect3 id="g-idle-add-full.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>priority</para></entry>
<entry role="parameter_description"><para>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>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>function</para></entry>
<entry role="parameter_description"><para>function to call</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>data to pass to <parameter>function</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>notify</para></entry>
<entry role="parameter_description"><para>function to call when the idle is removed, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-idle-add-full.returns" role="returns">
<title>Returns</title>
<para> the ID (greater than 0) of the event source.</para>
</refsect3></refsect2>
<refsect2 id="g-idle-remove-by-data" role="function">
<title>g_idle_remove_by_data&#160;()</title>
<indexterm zone="g-idle-remove-by-data"><primary sortas="idle_remove_by_data">g_idle_remove_by_data</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_idle_remove_by_data (<parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>);</programlisting>
<para>Removes the idle function with the given data.</para>
<refsect3 id="g-idle-remove-by-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>the data for the idle source's callback.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-idle-remove-by-data.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if an idle source was found and removed.</para>
</refsect3></refsect2>
<refsect2 id="GChildWatchFunc" role="function">
<title>GChildWatchFunc&#160;()</title>
<indexterm zone="GChildWatchFunc"><primary sortas="ChildWatchFunc">GChildWatchFunc</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
<phrase role="c_punctuation">(</phrase>*GChildWatchFunc<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="GPid"><type>GPid</type></link> pid</parameter>,
                    <parameter><link linkend="gint"><type>gint</type></link> status</parameter>,
                    <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</programlisting>
<para>Prototype of a <link linkend="GChildWatchSource"><type>GChildWatchSource</type></link> callback, called when a child
process has exited.  To interpret <parameter>status</parameter>
, see the documentation
for <link linkend="g-spawn-check-exit-status"><function>g_spawn_check_exit_status()</function></link>.</para>
<refsect3 id="GChildWatchFunc.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pid</para></entry>
<entry role="parameter_description"><para>the process id of the child process</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>status</para></entry>
<entry role="parameter_description"><para>Status information about the child process, encoded
in a platform-specific manner</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>user data passed to <link linkend="g-child-watch-add"><function>g_child_watch_add()</function></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-child-watch-source-new" role="function" condition="since:2.4">
<title>g_child_watch_source_new&#160;()</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 language="C"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
g_child_watch_source_new (<parameter><link linkend="GPid"><type>GPid</type></link> pid</parameter>);</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>On POSIX platforms, the following restrictions apply to this API
due to limitations in POSIX process interfaces:</para>
<itemizedlist>
<listitem><para><parameter>pid</parameter>
 must be a child of this process</para></listitem>
<listitem><para><parameter>pid</parameter>
 must be positive</para></listitem>
<listitem><para>the application must not call <literal>waitpid</literal> with a non-positive
first argument, for instance in another thread</para></listitem>
<listitem><para>the application must not wait for <parameter>pid</parameter>
 to exit by any other
mechanism, including <literal>waitpid(pid, ...)</literal> or a second child-watch
source for the same <parameter>pid</parameter>
</para></listitem>
<listitem>
<para>the application must not ignore SIGCHILD</para>
</listitem>
</itemizedlist>
<para>If any of those conditions are not met, this and related APIs will
not work correctly. This can often be diagnosed via a GLib warning
stating that <literal>ECHILD</literal> was received by <literal>waitpid</literal>.</para>
<para>Calling <literal>waitpid</literal> for specific processes other than <parameter>pid</parameter>
 remains a
valid thing to do.</para>
<refsect3 id="g-child-watch-source-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pid</para></entry>
<entry role="parameter_description"><para>process to watch. On POSIX the positive pid of a child process. On
Windows a handle for a process (which doesn't have to be a child).</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-child-watch-source-new.returns" role="returns">
<title>Returns</title>
<para> the newly-created child watch source</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-child-watch-add" role="function" condition="since:2.4">
<title>g_child_watch_add&#160;()</title>
<indexterm zone="g-child-watch-add" role="2.4"><primary sortas="child_watch_add">g_child_watch_add</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_child_watch_add (<parameter><link linkend="GPid"><type>GPid</type></link> pid</parameter>,
                   <parameter><link linkend="GChildWatchFunc"><type>GChildWatchFunc</type></link> function</parameter>,
                   <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>);</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.
On POSIX platforms, the same restrictions mentioned for
<link linkend="g-child-watch-source-new"><function>g_child_watch_source_new()</function></link> apply to this function.</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>
<refsect3 id="g-child-watch-add.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pid</para></entry>
<entry role="parameter_description"><para>process id to watch. On POSIX the positive pid of a child
process. On Windows a handle for a process (which doesn't have to be
a child).</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>function</para></entry>
<entry role="parameter_description"><para>function to call</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>data to pass to <parameter>function</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-child-watch-add.returns" role="returns">
<title>Returns</title>
<para> the ID (greater than 0) of the event source.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-child-watch-add-full" role="function" condition="since:2.4">
<title>g_child_watch_add_full&#160;()</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 language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_child_watch_add_full (<parameter><link linkend="gint"><type>gint</type></link> priority</parameter>,
                        <parameter><link linkend="GPid"><type>GPid</type></link> pid</parameter>,
                        <parameter><link linkend="GChildWatchFunc"><type>GChildWatchFunc</type></link> function</parameter>,
                        <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>,
                        <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> notify</parameter>);</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>In many programs, you will want to call <link linkend="g-spawn-check-exit-status"><function>g_spawn_check_exit_status()</function></link>
in the callback to determine whether or not the child exited
successfully.</para>
<para>Also, 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 should invoke <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.
On POSIX platforms, the same restrictions mentioned for
<link linkend="g-child-watch-source-new"><function>g_child_watch_source_new()</function></link> apply to this function.</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><emphasis role="annotation">[<acronym>rename-to</acronym> g_child_watch_add]</emphasis></para><refsect3 id="g-child-watch-add-full.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>priority</para></entry>
<entry role="parameter_description"><para>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>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pid</para></entry>
<entry role="parameter_description"><para>process to watch. On POSIX the positive pid of a child process. On
Windows a handle for a process (which doesn't have to be a child).</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>function</para></entry>
<entry role="parameter_description"><para>function to call</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>data to pass to <parameter>function</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>notify</para></entry>
<entry role="parameter_description"><para>function to call when the idle is removed, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-child-watch-add-full.returns" role="returns">
<title>Returns</title>
<para> the ID (greater than 0) of the event source.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-poll" role="function" condition="since:2.20">
<title>g_poll&#160;()</title>
<indexterm zone="g-poll" role="2.20"><primary sortas="poll">g_poll</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_poll (<parameter><link linkend="GPollFD"><type>GPollFD</type></link> *fds</parameter>,
        <parameter><link linkend="guint"><type>guint</type></link> nfds</parameter>,
        <parameter><link linkend="gint"><type>gint</type></link> timeout</parameter>);</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 <parameter>fd</parameter>
 field indicates the file descriptor,
and the <parameter>events</parameter>
 field indicates the events to poll for. On return,
the <parameter>revents</parameter>
 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="GPollFDs"><type>GPollFDs</type></link> with <link linkend="g-io-channel-win32-make-pollfd"><function>g_io_channel_win32_make_pollfd()</function></link>.</para>
<refsect3 id="g-poll.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>fds</para></entry>
<entry role="parameter_description"><para>file descriptors to poll</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>nfds</para></entry>
<entry role="parameter_description"><para>the number of file descriptors in <parameter>fds</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>timeout</para></entry>
<entry role="parameter_description"><para>amount of time to wait, in milliseconds, or -1 to wait forever</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-poll.returns" role="returns">
<title>Returns</title>
<para> the number of entries in <parameter>fds</parameter>
whose <parameter>revents</parameter>
fields
were filled in, or 0 if the operation timed out, or -1 on error or
if the call was interrupted.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.20">2.20</link></para></refsect2>
<refsect2 id="GSourceDummyMarshal" role="function">
<title>GSourceDummyMarshal&#160;()</title>
<indexterm zone="GSourceDummyMarshal"><primary sortas="SourceDummyMarshal">GSourceDummyMarshal</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
<phrase role="c_punctuation">(</phrase>*GSourceDummyMarshal<phrase role="c_punctuation">)</phrase> (<parameter><type>void</type></parameter>);</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="g-source-new" role="function">
<title>g_source_new&#160;()</title>
<indexterm zone="g-source-new"><primary sortas="source_new">g_source_new</primary></indexterm>
<programlisting language="C"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
g_source_new (<parameter><link linkend="GSourceFuncs"><type>GSourceFuncs</type></link> *source_funcs</parameter>,
              <parameter><link linkend="guint"><type>guint</type></link> struct_size</parameter>);</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>
<refsect3 id="g-source-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source_funcs</para></entry>
<entry role="parameter_description"><para>structure containing functions that implement
the sources behavior.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>struct_size</para></entry>
<entry role="parameter_description"><para>size of the <link linkend="GSource"><type>GSource</type></link> structure to create.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-new.returns" role="returns">
<title>Returns</title>
<para> the newly-created <link linkend="GSource"><type>GSource</type></link>.</para>
</refsect3></refsect2>
<refsect2 id="g-source-ref" role="function">
<title>g_source_ref&#160;()</title>
<indexterm zone="g-source-ref"><primary sortas="source_ref">g_source_ref</primary></indexterm>
<programlisting language="C"><link linkend="GSource"><returnvalue>GSource</returnvalue></link>&#160;*
g_source_ref (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>);</programlisting>
<para>Increases the reference count on a source by one.</para>
<refsect3 id="g-source-ref.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-ref.returns" role="returns">
<title>Returns</title>
<para> <parameter>source</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-source-unref" role="function">
<title>g_source_unref&#160;()</title>
<indexterm zone="g-source-unref"><primary sortas="source_unref">g_source_unref</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_unref (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>);</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>
<refsect3 id="g-source-unref.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-source-set-funcs" role="function" condition="since:2.12">
<title>g_source_set_funcs&#160;()</title>
<indexterm zone="g-source-set-funcs" role="2.12"><primary sortas="source_set_funcs">g_source_set_funcs</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_set_funcs (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                    <parameter><link linkend="GSourceFuncs"><type>GSourceFuncs</type></link> *funcs</parameter>);</programlisting>
<para>Sets the source functions (can be used to override 
default implementations) of an unattached source.</para>
<refsect3 id="g-source-set-funcs.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>funcs</para></entry>
<entry role="parameter_description"><para>the new <link linkend="GSourceFuncs"><type>GSourceFuncs</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.12">2.12</link></para></refsect2>
<refsect2 id="g-source-attach" role="function">
<title>g_source_attach&#160;()</title>
<indexterm zone="g-source-attach"><primary sortas="source_attach">g_source_attach</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_source_attach (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                 <parameter><link linkend="GMainContext"><type>GMainContext</type></link> *context</parameter>);</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>
<refsect3 id="g-source-attach.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GMainContext"><type>GMainContext</type></link> (if <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the default context will be used). </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-attach.returns" role="returns">
<title>Returns</title>
<para> the ID (greater than 0) for the source within the
<link linkend="GMainContext"><type>GMainContext</type></link>. </para>
</refsect3></refsect2>
<refsect2 id="g-source-destroy" role="function">
<title>g_source_destroy&#160;()</title>
<indexterm zone="g-source-destroy"><primary sortas="source_destroy">g_source_destroy</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_destroy (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>);</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. It is safe to call this on sources which have already been
removed from their context.</para>
<refsect3 id="g-source-destroy.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-source-is-destroyed" role="function" condition="since:2.12">
<title>g_source_is_destroyed&#160;()</title>
<indexterm zone="g-source-is-destroyed" role="2.12"><primary sortas="source_is_destroyed">g_source_is_destroyed</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_source_is_destroyed (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>);</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>
<informalexample><programlisting role="example"><![CDATA[
static gboolean 
idle_callback (gpointer data)
{
  SomeWidget *self = data;
   
  GDK_THREADS_ENTER ();
  // do stuff with self
  self->idle_id = 0;
  GDK_THREADS_LEAVE ();
   
  return G_SOURCE_REMOVE;
}
 
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>
<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>
<informalexample><programlisting role="example"><![CDATA[
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>Calls to this function from a thread other than the one acquired by the
<link linkend="GMainContext"><type>GMainContext</type></link> the <link linkend="GSource"><type>GSource</type></link> is attached to are typically redundant, as the
source could be destroyed immediately after this function returns. However,
once a source is destroyed it cannot be un-destroyed, so this function can be
used for opportunistic checks from any thread.</para>
<refsect3 id="g-source-is-destroyed.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-is-destroyed.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the source has been destroyed</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.12">2.12</link></para></refsect2>
<refsect2 id="g-source-set-priority" role="function">
<title>g_source_set_priority&#160;()</title>
<indexterm zone="g-source-set-priority"><primary sortas="source_set_priority">g_source_set_priority</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_set_priority (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                       <parameter><link linkend="gint"><type>gint</type></link> priority</parameter>);</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>A child source always has the same priority as its parent.  It is not
permitted to change the priority of a source once it has been added
as a child of another source.</para>
<refsect3 id="g-source-set-priority.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>priority</para></entry>
<entry role="parameter_description"><para>the new priority.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-source-get-priority" role="function">
<title>g_source_get_priority&#160;()</title>
<indexterm zone="g-source-get-priority"><primary sortas="source_get_priority">g_source_get_priority</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_source_get_priority (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>);</programlisting>
<para>Gets the priority of a source.</para>
<refsect3 id="g-source-get-priority.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-get-priority.returns" role="returns">
<title>Returns</title>
<para> the priority of the source</para>
</refsect3></refsect2>
<refsect2 id="g-source-set-can-recurse" role="function">
<title>g_source_set_can_recurse&#160;()</title>
<indexterm zone="g-source-set-can-recurse"><primary sortas="source_set_can_recurse">g_source_set_can_recurse</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_set_can_recurse (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                          <parameter><link linkend="gboolean"><type>gboolean</type></link> can_recurse</parameter>);</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>
<refsect3 id="g-source-set-can-recurse.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>can_recurse</para></entry>
<entry role="parameter_description"><para>whether recursion is allowed for this source</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-source-get-can-recurse" role="function">
<title>g_source_get_can_recurse&#160;()</title>
<indexterm zone="g-source-get-can-recurse"><primary sortas="source_get_can_recurse">g_source_get_can_recurse</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_source_get_can_recurse (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>);</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>
<refsect3 id="g-source-get-can-recurse.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-get-can-recurse.returns" role="returns">
<title>Returns</title>
<para> whether recursion is allowed.</para>
</refsect3></refsect2>
<refsect2 id="g-source-get-id" role="function">
<title>g_source_get_id&#160;()</title>
<indexterm zone="g-source-get-id"><primary sortas="source_get_id">g_source_get_id</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_source_get_id (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>);</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>You can only call this function while the source is associated to a
<link linkend="GMainContext"><type>GMainContext</type></link> instance; calling this function before <link linkend="g-source-attach"><function>g_source_attach()</function></link>
or after <link linkend="g-source-destroy"><function>g_source_destroy()</function></link> yields undefined behavior. The ID returned
is unique within the <link linkend="GMainContext"><type>GMainContext</type></link> instance passed to <link linkend="g-source-attach"><function>g_source_attach()</function></link>.</para>
<refsect3 id="g-source-get-id.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-get-id.returns" role="returns">
<title>Returns</title>
<para> the ID (greater than 0) for the source</para>
</refsect3></refsect2>
<refsect2 id="g-source-get-name" role="function" condition="since:2.26">
<title>g_source_get_name&#160;()</title>
<indexterm zone="g-source-get-name" role="2.26"><primary sortas="source_get_name">g_source_get_name</primary></indexterm>
<programlisting language="C">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
g_source_get_name (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>);</programlisting>
<para>Gets a name for the source, used in debugging and profiling.  The
name may be <link linkend="NULL:CAPS"><type>NULL</type></link> if it has never been set with <link linkend="g-source-set-name"><function>g_source_set_name()</function></link>.</para>
<refsect3 id="g-source-get-name.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-get-name.returns" role="returns">
<title>Returns</title>
<para> the name of the source</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.26">2.26</link></para></refsect2>
<refsect2 id="g-source-set-name" role="function" condition="since:2.26">
<title>g_source_set_name&#160;()</title>
<indexterm zone="g-source-set-name" role="2.26"><primary sortas="source_set_name">g_source_set_name</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_set_name (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                   <parameter>const <link linkend="char"><type>char</type></link> *name</parameter>);</programlisting>
<para>Sets a name for the source, used in debugging and profiling.
The name defaults to <link linkend="NULL:CAPS"><type>NULL</type></link>.</para>
<para>The source name should describe in a human-readable way
what the source does. For example, "X11 event queue"
or "GTK+ repaint idle handler" or whatever it is.</para>
<para>It is permitted to call this function multiple times, but is not
recommended due to the potential performance impact.  For example,
one could change the name in the "check" function of a <link linkend="GSourceFuncs"><type>GSourceFuncs</type></link>
to include details like the event type in the source name.</para>
<para>Use caution if changing the name while another thread may be
accessing it with <link linkend="g-source-get-name"><function>g_source_get_name()</function></link>; that function does not copy
the value, and changing the value will free it while the other thread
may be attempting to use it.</para>
<refsect3 id="g-source-set-name.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>name</para></entry>
<entry role="parameter_description"><para>debug name for the source</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.26">2.26</link></para></refsect2>
<refsect2 id="g-source-set-name-by-id" role="function" condition="since:2.26">
<title>g_source_set_name_by_id&#160;()</title>
<indexterm zone="g-source-set-name-by-id" role="2.26"><primary sortas="source_set_name_by_id">g_source_set_name_by_id</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_set_name_by_id (<parameter><link linkend="guint"><type>guint</type></link> tag</parameter>,
                         <parameter>const <link linkend="char"><type>char</type></link> *name</parameter>);</programlisting>
<para>Sets the name of a source using its ID.</para>
<para>This is a convenience utility to set source names from the return
value of <link linkend="g-idle-add"><function>g_idle_add()</function></link>, <link linkend="g-timeout-add"><function>g_timeout_add()</function></link>, etc.</para>
<para>It is a programmer error to attempt to set the name of a non-existent
source.</para>
<para>More specifically: source IDs can be reissued after a source has been
destroyed and therefore it is never valid to use this function with a
source ID which may have already been removed.  An example is when
scheduling an idle to run in another thread with <link linkend="g-idle-add"><function>g_idle_add()</function></link>: the
idle may already have run and been removed by the time this function
is called on its (now invalid) source ID.  This source ID may have
been reissued, leading to the operation being performed against the
wrong source.</para>
<refsect3 id="g-source-set-name-by-id.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>tag</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link> ID</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>name</para></entry>
<entry role="parameter_description"><para>debug name for the source</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.26">2.26</link></para></refsect2>
<refsect2 id="g-source-get-context" role="function">
<title>g_source_get_context&#160;()</title>
<indexterm zone="g-source-get-context"><primary sortas="source_get_context">g_source_get_context</primary></indexterm>
<programlisting language="C"><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link>&#160;*
g_source_get_context (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>);</programlisting>
<para>Gets the <link linkend="GMainContext"><type>GMainContext</type></link> with which the source is associated.</para>
<para>You can call this on a source that has been destroyed, provided
that the <link linkend="GMainContext"><type>GMainContext</type></link> it was attached to still exists (in which
case it will return that <link linkend="GMainContext"><type>GMainContext</type></link>). In particular, you can
always call this function on the source returned from
<link linkend="g-main-current-source"><function>g_main_current_source()</function></link>. But calling this function on a source
whose <link linkend="GMainContext"><type>GMainContext</type></link> has been destroyed is an error.</para>
<refsect3 id="g-source-get-context.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-get-context.returns" role="returns">
<title>Returns</title>
<para>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. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>][<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-source-set-callback" role="function">
<title>g_source_set_callback&#160;()</title>
<indexterm zone="g-source-set-callback"><primary sortas="source_set_callback">g_source_set_callback</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_set_callback (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                       <parameter><link linkend="GSourceFunc"><type>GSourceFunc</type></link> func</parameter>,
                       <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>,
                       <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> notify</parameter>);</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. Cast <parameter>func</parameter>
 with <link linkend="G-SOURCE-FUNC:CAPS"><function>G_SOURCE_FUNC()</function></link> to avoid warnings about
incompatible function types.</para>
<para>See <link linkend="mainloop-memory-management">memory management of sources</link> for details
on how to handle memory management of <parameter>data</parameter>
.</para>
<para>Typically, you won't use this function. Instead use functions specific
to the type of source you are using, such as <link linkend="g-idle-add"><function>g_idle_add()</function></link> or <link linkend="g-timeout-add"><function>g_timeout_add()</function></link>.</para>
<para>It is safe to call this function multiple times on a source which has already
been attached to a context. The changes will take effect for the next time
the source is dispatched after this call returns.</para>
<refsect3 id="g-source-set-callback.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>the source</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>func</para></entry>
<entry role="parameter_description"><para>a callback function</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>the data to pass to callback function</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>notify</para></entry>
<entry role="parameter_description"><para>a function to call when <parameter>data</parameter>
is no longer in use, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="GSourceFunc" role="function">
<title>GSourceFunc&#160;()</title>
<indexterm zone="GSourceFunc"><primary sortas="SourceFunc">GSourceFunc</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
<phrase role="c_punctuation">(</phrase>*GSourceFunc<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</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>
<para>When calling <link linkend="g-source-set-callback"><function>g_source_set_callback()</function></link>, you may need to cast a function of a
different type to this type. Use <link linkend="G-SOURCE-FUNC:CAPS"><function>G_SOURCE_FUNC()</function></link> to avoid warnings about
incompatible function types.</para>
<refsect3 id="GSourceFunc.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>data passed to the function, set when the source was
created with one of the above functions</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="GSourceFunc.returns" role="returns">
<title>Returns</title>
<para> <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if the source should be removed. <link linkend="G-SOURCE-CONTINUE:CAPS"><type>G_SOURCE_CONTINUE</type></link> and
<link linkend="G-SOURCE-REMOVE:CAPS"><type>G_SOURCE_REMOVE</type></link> are more memorable names for the return value.</para>
</refsect3></refsect2>
<refsect2 id="G-SOURCE-FUNC:CAPS" role="macro" condition="since:2.58">
<title>G_SOURCE_FUNC()</title>
<indexterm zone="G-SOURCE-FUNC:CAPS" role="2.58"><primary sortas="SOURCE_FUNC">G_SOURCE_FUNC</primary></indexterm>
<programlisting language="C">#define G_SOURCE_FUNC(f) ((GSourceFunc) (void (*)(void)) (f))
</programlisting>
<para>Cast a function pointer to a <link linkend="GSourceFunc"><type>GSourceFunc</type></link>, suppressing warnings from GCC 8
onwards with <literal>-Wextra</literal> or <literal>-Wcast-function-type</literal> enabled about the function
types being incompatible.</para>
<para>For example, the correct type of callback for a source created by
<link linkend="g-child-watch-source-new"><function>g_child_watch_source_new()</function></link> is <link linkend="GChildWatchFunc"><type>GChildWatchFunc</type></link>, which accepts more arguments
than <link linkend="GSourceFunc"><type>GSourceFunc</type></link>. Casting the function with <literal>(GSourceFunc)</literal> to call
<link linkend="g-source-set-callback"><function>g_source_set_callback()</function></link> will trigger a warning, even though it will be cast
back to the correct type before it is called by the source.</para>
<refsect3 id="G-SOURCE-FUNC.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>f</para></entry>
<entry role="parameter_description"><para>a function pointer.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.58">2.58</link></para></refsect2>
<refsect2 id="g-source-set-callback-indirect" role="function">
<title>g_source_set_callback_indirect&#160;()</title>
<indexterm zone="g-source-set-callback-indirect"><primary sortas="source_set_callback_indirect">g_source_set_callback_indirect</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_set_callback_indirect (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                                <parameter><link linkend="gpointer"><type>gpointer</type></link> callback_data</parameter>,
                                <parameter><link linkend="GSourceCallbackFuncs"><type>GSourceCallbackFuncs</type></link> *callback_funcs</parameter>);</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>It is safe to call this function multiple times on a source which has already
been attached to a context. The changes will take effect for the next time
the source is dispatched after this call returns.</para>
<refsect3 id="g-source-set-callback-indirect.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>the source</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>callback_data</para></entry>
<entry role="parameter_description"><para>pointer to callback data "object"</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>callback_funcs</para></entry>
<entry role="parameter_description"><para>functions for reference counting <parameter>callback_data</parameter>
and getting the callback and data</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-source-set-ready-time" role="function" condition="since:2.36">
<title>g_source_set_ready_time&#160;()</title>
<indexterm zone="g-source-set-ready-time" role="2.36"><primary sortas="source_set_ready_time">g_source_set_ready_time</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_set_ready_time (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                         <parameter><link linkend="gint64"><type>gint64</type></link> ready_time</parameter>);</programlisting>
<para>Sets a <link linkend="GSource"><type>GSource</type></link> to be dispatched when the given monotonic time is
reached (or passed).  If the monotonic time is in the past (as it
always will be if <parameter>ready_time</parameter>
 is 0) then the source will be
dispatched immediately.</para>
<para>If <parameter>ready_time</parameter>
 is -1 then the source is never woken up on the basis
of the passage of time.</para>
<para>Dispatching the source does not reset the ready time.  You should do
so yourself, from the source dispatch function.</para>
<para>Note that if you have a pair of sources where the ready time of one
suggests that it will be delivered first but the priority for the
other suggests that it would be delivered first, and the ready time
for both sources is reached during the same main context iteration,
then the order of dispatch is undefined.</para>
<para>It is a no-op to call this function on a <link linkend="GSource"><type>GSource</type></link> which has already been
destroyed with <link linkend="g-source-destroy"><function>g_source_destroy()</function></link>.</para>
<para>This API is only intended to be used by implementations of <link linkend="GSource"><type>GSource</type></link>.
Do not call this API on a <link linkend="GSource"><type>GSource</type></link> that you did not create.</para>
<refsect3 id="g-source-set-ready-time.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>ready_time</para></entry>
<entry role="parameter_description"><para>the monotonic time at which the source will be ready,
0 for "immediately", -1 for "never"</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.36">2.36</link></para></refsect2>
<refsect2 id="g-source-get-ready-time" role="function">
<title>g_source_get_ready_time&#160;()</title>
<indexterm zone="g-source-get-ready-time"><primary sortas="source_get_ready_time">g_source_get_ready_time</primary></indexterm>
<programlisting language="C"><link linkend="gint64"><returnvalue>gint64</returnvalue></link>
g_source_get_ready_time (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>);</programlisting>
<para>Gets the "ready time" of <parameter>source</parameter>
, as set by
<link linkend="g-source-set-ready-time"><function>g_source_set_ready_time()</function></link>.</para>
<para>Any time before the current monotonic time (including 0) is an
indication that the source will fire immediately.</para>
<refsect3 id="g-source-get-ready-time.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-get-ready-time.returns" role="returns">
<title>Returns</title>
<para> the monotonic ready time, -1 for "never"</para>
</refsect3></refsect2>
<refsect2 id="g-source-add-unix-fd" role="function" condition="since:2.36">
<title>g_source_add_unix_fd&#160;()</title>
<indexterm zone="g-source-add-unix-fd" role="2.36"><primary sortas="source_add_unix_fd">g_source_add_unix_fd</primary></indexterm>
<programlisting language="C"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
g_source_add_unix_fd (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                      <parameter><link linkend="gint"><type>gint</type></link> fd</parameter>,
                      <parameter><link linkend="GIOCondition"><type>GIOCondition</type></link> events</parameter>);</programlisting>
<para>Monitors <parameter>fd</parameter>
 for the IO events in <parameter>events</parameter>
.</para>
<para>The tag returned by this function can be used to remove or modify the
monitoring of the fd using <link linkend="g-source-remove-unix-fd"><function>g_source_remove_unix_fd()</function></link> or
<link linkend="g-source-modify-unix-fd"><function>g_source_modify_unix_fd()</function></link>.</para>
<para>It is not necessary to remove the fd before destroying the source; it
will be cleaned up automatically.</para>
<para>This API is only intended to be used by implementations of <link linkend="GSource"><type>GSource</type></link>.
Do not call this API on a <link linkend="GSource"><type>GSource</type></link> that you did not create.</para>
<para>As the name suggests, this function is not available on Windows.</para>
<refsect3 id="g-source-add-unix-fd.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>fd</para></entry>
<entry role="parameter_description"><para>the fd to monitor</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>events</para></entry>
<entry role="parameter_description"><para>an event mask</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-add-unix-fd.returns" role="returns">
<title>Returns</title>
<para>an opaque tag. </para>
<para><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.36">2.36</link></para></refsect2>
<refsect2 id="g-source-remove-unix-fd" role="function" condition="since:2.36">
<title>g_source_remove_unix_fd&#160;()</title>
<indexterm zone="g-source-remove-unix-fd" role="2.36"><primary sortas="source_remove_unix_fd">g_source_remove_unix_fd</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_remove_unix_fd (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                         <parameter><link linkend="gpointer"><type>gpointer</type></link> tag</parameter>);</programlisting>
<para>Reverses the effect of a previous call to <link linkend="g-source-add-unix-fd"><function>g_source_add_unix_fd()</function></link>.</para>
<para>You only need to call this if you want to remove an fd from being
watched while keeping the same source around.  In the normal case you
will just want to destroy the source.</para>
<para>This API is only intended to be used by implementations of <link linkend="GSource"><type>GSource</type></link>.
Do not call this API on a <link linkend="GSource"><type>GSource</type></link> that you did not create.</para>
<para>As the name suggests, this function is not available on Windows.</para>
<refsect3 id="g-source-remove-unix-fd.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>tag</para></entry>
<entry role="parameter_description"><para>the tag from <link linkend="g-source-add-unix-fd"><function>g_source_add_unix_fd()</function></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.36">2.36</link></para></refsect2>
<refsect2 id="g-source-modify-unix-fd" role="function" condition="since:2.36">
<title>g_source_modify_unix_fd&#160;()</title>
<indexterm zone="g-source-modify-unix-fd" role="2.36"><primary sortas="source_modify_unix_fd">g_source_modify_unix_fd</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_modify_unix_fd (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                         <parameter><link linkend="gpointer"><type>gpointer</type></link> tag</parameter>,
                         <parameter><link linkend="GIOCondition"><type>GIOCondition</type></link> new_events</parameter>);</programlisting>
<para>Updates the event mask to watch for the fd identified by <parameter>tag</parameter>
.</para>
<para><parameter>tag</parameter>
 is the tag returned from <link linkend="g-source-add-unix-fd"><function>g_source_add_unix_fd()</function></link>.</para>
<para>If you want to remove a fd, don't set its event mask to zero.
Instead, call <link linkend="g-source-remove-unix-fd"><function>g_source_remove_unix_fd()</function></link>.</para>
<para>This API is only intended to be used by implementations of <link linkend="GSource"><type>GSource</type></link>.
Do not call this API on a <link linkend="GSource"><type>GSource</type></link> that you did not create.</para>
<para>As the name suggests, this function is not available on Windows.</para>
<refsect3 id="g-source-modify-unix-fd.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>tag</para></entry>
<entry role="parameter_description"><para>the tag from <link linkend="g-source-add-unix-fd"><function>g_source_add_unix_fd()</function></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>new_events</para></entry>
<entry role="parameter_description"><para>the new event mask to watch</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.36">2.36</link></para></refsect2>
<refsect2 id="g-source-query-unix-fd" role="function" condition="since:2.36">
<title>g_source_query_unix_fd&#160;()</title>
<indexterm zone="g-source-query-unix-fd" role="2.36"><primary sortas="source_query_unix_fd">g_source_query_unix_fd</primary></indexterm>
<programlisting language="C"><link linkend="GIOCondition"><returnvalue>GIOCondition</returnvalue></link>
g_source_query_unix_fd (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                        <parameter><link linkend="gpointer"><type>gpointer</type></link> tag</parameter>);</programlisting>
<para>Queries the events reported for the fd corresponding to <parameter>tag</parameter>
 on
<parameter>source</parameter>
 during the last poll.</para>
<para>The return value of this function is only defined when the function
is called from the check or dispatch functions for <parameter>source</parameter>
.</para>
<para>This API is only intended to be used by implementations of <link linkend="GSource"><type>GSource</type></link>.
Do not call this API on a <link linkend="GSource"><type>GSource</type></link> that you did not create.</para>
<para>As the name suggests, this function is not available on Windows.</para>
<refsect3 id="g-source-query-unix-fd.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>tag</para></entry>
<entry role="parameter_description"><para>the tag from <link linkend="g-source-add-unix-fd"><function>g_source_add_unix_fd()</function></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-query-unix-fd.returns" role="returns">
<title>Returns</title>
<para> the conditions reported on the fd</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.36">2.36</link></para></refsect2>
<refsect2 id="g-source-add-poll" role="function">
<title>g_source_add_poll&#160;()</title>
<indexterm zone="g-source-add-poll"><primary sortas="source_add_poll">g_source_add_poll</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_add_poll (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                   <parameter><link linkend="GPollFD"><type>GPollFD</type></link> *fd</parameter>);</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>This API is only intended to be used by implementations of <link linkend="GSource"><type>GSource</type></link>.
Do not call this API on a <link linkend="GSource"><type>GSource</type></link> that you did not create.</para>
<para>Using this API forces the linear scanning of event sources on each
main loop iteration.  Newly-written event sources should try to use
<link linkend="g-source-add-unix-fd"><function>g_source_add_unix_fd()</function></link> instead of this API.</para>
<refsect3 id="g-source-add-poll.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link> </para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>fd</para></entry>
<entry role="parameter_description"><para>a <link linkend="GPollFD"><type>GPollFD</type></link> structure holding information about a file
descriptor to watch.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-source-remove-poll" role="function">
<title>g_source_remove_poll&#160;()</title>
<indexterm zone="g-source-remove-poll"><primary sortas="source_remove_poll">g_source_remove_poll</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_remove_poll (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                      <parameter><link linkend="GPollFD"><type>GPollFD</type></link> *fd</parameter>);</programlisting>
<para>Removes a file descriptor from the set of file descriptors polled for
this source. </para>
<para>This API is only intended to be used by implementations of <link linkend="GSource"><type>GSource</type></link>.
Do not call this API on a <link linkend="GSource"><type>GSource</type></link> that you did not create.</para>
<refsect3 id="g-source-remove-poll.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link> </para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>fd</para></entry>
<entry role="parameter_description"><para>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>.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-source-add-child-source" role="function" condition="since:2.28">
<title>g_source_add_child_source&#160;()</title>
<indexterm zone="g-source-add-child-source" role="2.28"><primary sortas="source_add_child_source">g_source_add_child_source</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_add_child_source (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                           <parameter><link linkend="GSource"><type>GSource</type></link> *child_source</parameter>);</programlisting>
<para>Adds <parameter>child_source</parameter>
 to <parameter>source</parameter>
 as a "polled" source; when <parameter>source</parameter>
 is
added to a <link linkend="GMainContext"><type>GMainContext</type></link>, <parameter>child_source</parameter>
 will be automatically added
with the same priority, when <parameter>child_source</parameter>
 is triggered, it will
cause <parameter>source</parameter>
 to dispatch (in addition to calling its own
callback), and when <parameter>source</parameter>
 is destroyed, it will destroy
<parameter>child_source</parameter>
 as well. (<parameter>source</parameter>
 will also still be dispatched if
its own prepare/check functions indicate that it is ready.)</para>
<para>If you don't need <parameter>child_source</parameter>
 to do anything on its own when it
triggers, you can call <link linkend="g-source-set-dummy-callback"><function>g_source_set_dummy_callback()</function></link> on it to set a
callback that does nothing (except return <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if appropriate).</para>
<para><parameter>source</parameter>
 will hold a reference on <parameter>child_source</parameter>
 while <parameter>child_source</parameter>

is attached to it.</para>
<para>This API is only intended to be used by implementations of <link linkend="GSource"><type>GSource</type></link>.
Do not call this API on a <link linkend="GSource"><type>GSource</type></link> that you did not create.</para>
<refsect3 id="g-source-add-child-source.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>child_source</para></entry>
<entry role="parameter_description"><para>a second <link linkend="GSource"><type>GSource</type></link> that <parameter>source</parameter>
should "poll"</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.28">2.28</link></para></refsect2>
<refsect2 id="g-source-remove-child-source" role="function" condition="since:2.28">
<title>g_source_remove_child_source&#160;()</title>
<indexterm zone="g-source-remove-child-source" role="2.28"><primary sortas="source_remove_child_source">g_source_remove_child_source</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_remove_child_source (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                              <parameter><link linkend="GSource"><type>GSource</type></link> *child_source</parameter>);</programlisting>
<para>Detaches <parameter>child_source</parameter>
 from <parameter>source</parameter>
 and destroys it.</para>
<para>This API is only intended to be used by implementations of <link linkend="GSource"><type>GSource</type></link>.
Do not call this API on a <link linkend="GSource"><type>GSource</type></link> that you did not create.</para>
<refsect3 id="g-source-remove-child-source.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>child_source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link> previously passed to
<link linkend="g-source-add-child-source"><function>g_source_add_child_source()</function></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.28">2.28</link></para></refsect2>
<refsect2 id="g-source-get-time" role="function" condition="since:2.28">
<title>g_source_get_time&#160;()</title>
<indexterm zone="g-source-get-time" role="2.28"><primary sortas="source_get_time">g_source_get_time</primary></indexterm>
<programlisting language="C"><link linkend="gint64"><returnvalue>gint64</returnvalue></link>
g_source_get_time (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>);</programlisting>
<para>Gets the time to be used when checking this source. The advantage of
calling this function over calling <link linkend="g-get-monotonic-time"><function>g_get_monotonic_time()</function></link> directly is
that when checking multiple sources, GLib can cache a single value
instead of having to repeatedly get the system monotonic time.</para>
<para>The time here is the system monotonic time, if available, or some
other reasonable alternative otherwise.  See <link linkend="g-get-monotonic-time"><function>g_get_monotonic_time()</function></link>.</para>
<refsect3 id="g-source-get-time.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-get-time.returns" role="returns">
<title>Returns</title>
<para> the monotonic time in microseconds</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.28">2.28</link></para></refsect2>
<refsect2 id="g-source-get-current-time" role="function" condition="deprecated:2.28: use g_source_get_time() instead">
<title>g_source_get_current_time&#160;()</title>
<indexterm zone="g-source-get-current-time" role="deprecated"><primary sortas="source_get_current_time">g_source_get_current_time</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_source_get_current_time (<parameter><link linkend="GSource"><type>GSource</type></link> *source</parameter>,
                           <parameter><link linkend="GTimeVal"><type>GTimeVal</type></link> *timeval</parameter>);</programlisting>
<warning><para><literal>g_source_get_current_time</literal> has been deprecated since version 2.28 and should not be used in newly-written code.</para> <para>use <link linkend="g-source-get-time"><function>g_source_get_time()</function></link> instead</para>
</warning>
<para>This function ignores <parameter>source</parameter>
 and is otherwise the same as
<link linkend="g-get-current-time"><function>g_get_current_time()</function></link>.</para>
<refsect3 id="g-source-get-current-time.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a <link linkend="GSource"><type>GSource</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>timeval</para></entry>
<entry role="parameter_description"><para><link linkend="GTimeVal"><type>GTimeVal</type></link> structure in which to store current time.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-source-remove" role="function">
<title>g_source_remove&#160;()</title>
<indexterm zone="g-source-remove"><primary sortas="source_remove">g_source_remove</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_source_remove (<parameter><link linkend="guint"><type>guint</type></link> tag</parameter>);</programlisting>
<para>Removes the source with the given ID from the default main context. 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>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>It is a programmer error to attempt to remove a non-existent source.</para>
<para>More specifically: source IDs can be reissued after a source has been
destroyed and therefore it is never valid to use this function with a
source ID which may have already been removed.  An example is when
scheduling an idle to run in another thread with <link linkend="g-idle-add"><function>g_idle_add()</function></link>: the
idle may already have run and been removed by the time this function
is called on its (now invalid) source ID.  This source ID may have
been reissued, leading to the operation being performed against the
wrong source.</para>
<refsect3 id="g-source-remove.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>tag</para></entry>
<entry role="parameter_description"><para>the ID of the source to remove.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-remove.returns" role="returns">
<title>Returns</title>
<para> For historical reasons, this function always returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link></para>
</refsect3></refsect2>
<refsect2 id="g-source-remove-by-funcs-user-data" role="function">
<title>g_source_remove_by_funcs_user_data&#160;()</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 language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_source_remove_by_funcs_user_data (<parameter><link linkend="GSourceFuncs"><type>GSourceFuncs</type></link> *funcs</parameter>,
                                    <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</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>
<refsect3 id="g-source-remove-by-funcs-user-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>funcs</para></entry>
<entry role="parameter_description"><para>The <parameter>source_funcs</parameter>
passed to <link linkend="g-source-new"><function>g_source_new()</function></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>the user data for the callback</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-remove-by-funcs-user-data.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if a source was found and removed. </para>
</refsect3></refsect2>
<refsect2 id="g-source-remove-by-user-data" role="function">
<title>g_source_remove_by_user_data&#160;()</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 language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_source_remove_by_user_data (<parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</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>
<refsect3 id="g-source-remove-by-user-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>the user_data for the callback.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-source-remove-by-user-data.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if a source was found and removed. </para>
</refsect3></refsect2>
<refsect2 id="GClearHandleFunc" role="function" condition="since:2.56">
<title>GClearHandleFunc&#160;()</title>
<indexterm zone="GClearHandleFunc" role="2.56"><primary sortas="ClearHandleFunc">GClearHandleFunc</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
<phrase role="c_punctuation">(</phrase>*GClearHandleFunc<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="guint"><type>guint</type></link> handle_id</parameter>);</programlisting>
<para>Specifies the type of function passed to <link linkend="g-clear-handle-id"><function>g_clear_handle_id()</function></link>.
The implementation is expected to free the resource identified
by <parameter>handle_id</parameter>
; for instance, if <parameter>handle_id</parameter>
 is a <link linkend="GSource"><type>GSource</type></link> ID,
<link linkend="g-source-remove"><function>g_source_remove()</function></link> can be used.</para>
<refsect3 id="GClearHandleFunc.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>handle_id</para></entry>
<entry role="parameter_description"><para>the handle ID to clear</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.56">2.56</link></para></refsect2>
<refsect2 id="g-clear-handle-id" role="function" condition="since:2.56">
<title>g_clear_handle_id&#160;()</title>
<indexterm zone="g-clear-handle-id" role="2.56"><primary sortas="clear_handle_id">g_clear_handle_id</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_clear_handle_id (<parameter><link linkend="guint"><type>guint</type></link> *tag_ptr</parameter>,
                   <parameter><link linkend="GClearHandleFunc"><type>GClearHandleFunc</type></link> clear_func</parameter>);</programlisting>
<para>Clears a numeric handler, such as a <link linkend="GSource"><type>GSource</type></link> ID.</para>
<para><parameter>tag_ptr</parameter>
 must be a valid pointer to the variable holding the handler.</para>
<para>If the ID is zero then this function does nothing.
Otherwise, <link linkend="clear-func"><function>clear_func()</function></link> is called with the ID as a parameter, and the tag is
set to zero.</para>
<para>A macro is also included that allows this function to be used without
pointer casts.</para>

<para><emphasis role="annotation">[<acronym>skip</acronym>]</emphasis></para><refsect3 id="g-clear-handle-id.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>tag_ptr</para></entry>
<entry role="parameter_description"><para>a pointer to the handler ID. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>clear_func</para></entry>
<entry role="parameter_description"><para>the function to call to clear the handler. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.56">2.56</link></para></refsect2>

</refsect1>
<refsect1 id="glib-The-Main-Event-Loop.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GMainLoop" role="struct">
<title>GMainLoop</title>
<indexterm zone="GMainLoop"><primary sortas="MainLoop">GMainLoop</primary></indexterm>
<programlisting language="C">typedef struct _GMainLoop GMainLoop;</programlisting>
<para>The <literal>GMainLoop</literal> struct is an opaque data type
representing the main event loop of a GLib or GTK+ application.</para>
</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 language="C">#define G_PRIORITY_HIGH            -100
</programlisting>
<para>Use this for high priority event sources.</para>
<para>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 language="C">#define G_PRIORITY_DEFAULT          0
</programlisting>
<para>Use this for default priority event sources.</para>
<para>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 language="C">#define G_PRIORITY_HIGH_IDLE        100
</programlisting>
<para>Use this for high priority idle functions.</para>
<para>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 language="C">#define G_PRIORITY_DEFAULT_IDLE     200
</programlisting>
<para>Use this for default priority idle functions.</para>
<para>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 language="C">#define G_PRIORITY_LOW              300
</programlisting>
<para>Use this for very low priority background tasks.</para>
<para>It is not used within GLib or GTK+.</para>
</refsect2>
<refsect2 id="G-SOURCE-CONTINUE:CAPS" role="macro" condition="since:2.32">
<title>G_SOURCE_CONTINUE</title>
<indexterm zone="G-SOURCE-CONTINUE:CAPS" role="2.32"><primary sortas="SOURCE_CONTINUE">G_SOURCE_CONTINUE</primary></indexterm>
<programlisting language="C">#define G_SOURCE_CONTINUE       TRUE
</programlisting>
<para>Use this macro as the return value of a <link linkend="GSourceFunc"><type>GSourceFunc</type></link> to leave
the <link linkend="GSource"><type>GSource</type></link> in the main loop.</para>
<para role="since">Since: <link linkend="api-index-2.32">2.32</link></para></refsect2>
<refsect2 id="G-SOURCE-REMOVE:CAPS" role="macro" condition="since:2.32">
<title>G_SOURCE_REMOVE</title>
<indexterm zone="G-SOURCE-REMOVE:CAPS" role="2.32"><primary sortas="SOURCE_REMOVE">G_SOURCE_REMOVE</primary></indexterm>
<programlisting language="C">#define G_SOURCE_REMOVE         FALSE
</programlisting>
<para>Use this macro as the return value of a <link linkend="GSourceFunc"><type>GSourceFunc</type></link> to remove
the <link linkend="GSource"><type>GSource</type></link> from the main loop.</para>
<para role="since">Since: <link linkend="api-index-2.32">2.32</link></para></refsect2>
<refsect2 id="GMainContext" role="struct">
<title>GMainContext</title>
<indexterm zone="GMainContext"><primary sortas="MainContext">GMainContext</primary></indexterm>
<programlisting language="C">typedef struct _GMainContext GMainContext;</programlisting>
<para>The <literal>GMainContext</literal> struct is an opaque data
type representing a set of sources to be handled in a main loop.</para>
</refsect2>
<refsect2 id="GPid" role="typedef">
<title>GPid</title>
<indexterm zone="GPid"><primary sortas="Pid">GPid</primary></indexterm>
<programlisting language="C">typedef int GPid;
</programlisting>
<para>A type which is used to hold a process identification.</para>
<para>On UNIX, processes are identified by a process id (an integer),
while Windows uses process handles (which are pointers).</para>
<para>GPid is used in GLib only for descendant processes spawned with
the g_spawn functions.</para>
</refsect2>
<refsect2 id="G-PID-FORMAT:CAPS" role="macro" condition="since:2.50">
<title>G_PID_FORMAT</title>
<indexterm zone="G-PID-FORMAT:CAPS" role="2.50"><primary sortas="PID_FORMAT">G_PID_FORMAT</primary></indexterm>
<programlisting language="C">#define G_PID_FORMAT "i"
</programlisting>
<para>A format specifier that can be used in <link linkend="printf"><function>printf()</function></link>-style format strings
when printing a <link linkend="GPid"><type>GPid</type></link>.</para>
<para role="since">Since: <link linkend="api-index-2.50">2.50</link></para></refsect2>
<refsect2 id="GPollFD" role="struct">
<title>struct GPollFD</title>
<indexterm zone="GPollFD"><primary sortas="PollFD">GPollFD</primary></indexterm>
<programlisting language="C">struct GPollFD {
#if defined (G_OS_WIN32) &amp;&amp; GLIB_SIZEOF_VOID_P == 8
#endif
#else
  gint		fd;
#endif
  gushort 	events;
  gushort 	revents;
};
</programlisting>
<para>Represents a file descriptor, which events to poll for, and which events
occurred.</para>
<refsect3 id="GPollFD.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><link linkend="gint"><type>gint</type></link>&#160;<structfield id="GPollFD.fd">fd</structfield>;</para></entry>
<entry role="struct_member_description"><para>the file descriptor to poll (or a HANDLE on Win32)</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="gushort"><type>gushort</type></link>&#160;<structfield id="GPollFD.events">events</structfield>;</para></entry>
<entry role="struct_member_description"><para>a bitwise combination 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>.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="gushort"><type>gushort</type></link>&#160;<structfield id="GPollFD.revents">revents</structfield>;</para></entry>
<entry role="struct_member_description"><para>a bitwise combination of flags from <link linkend="GIOCondition"><type>GIOCondition</type></link>, returned
from the <link linkend="poll"><function>poll()</function></link> function to indicate which events occurred.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>
<refsect2 id="G-POLLFD-FORMAT:CAPS" role="macro">
<title>G_POLLFD_FORMAT</title>
<indexterm zone="G-POLLFD-FORMAT:CAPS"><primary sortas="POLLFD_FORMAT">G_POLLFD_FORMAT</primary></indexterm>
<programlisting language="C">#define G_POLLFD_FORMAT "%d"
</programlisting>
<para>A format specifier that can be used in <link linkend="printf"><function>printf()</function></link>-style format strings
when printing the <parameter>fd</parameter>
 member of a <link linkend="GPollFD"><type>GPollFD</type></link>.</para>
</refsect2>
<refsect2 id="GSource" role="struct">
<title>struct GSource</title>
<indexterm zone="GSource"><primary sortas="Source">GSource</primary></indexterm>
<programlisting language="C">struct GSource {
};
</programlisting>
<para>The <literal>GSource</literal> struct is an opaque data type
representing an event source.</para>
</refsect2>
<refsect2 id="GSourceFuncs" role="struct">
<title>struct GSourceFuncs</title>
<indexterm zone="GSourceFuncs"><primary sortas="SourceFuncs">GSourceFuncs</primary></indexterm>
<programlisting language="C">struct GSourceFuncs {
  gboolean (*prepare)  (GSource    *source,
                        gint       *timeout_);
  gboolean (*check)    (GSource    *source);
  gboolean (*dispatch) (GSource    *source,
                        GSourceFunc callback,
                        gpointer    user_data);
  void     (*finalize) (GSource    *source); /* Can be NULL */
};
</programlisting>
<para>The <literal>GSourceFuncs</literal> 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>
<refsect3 id="GSourceFuncs.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><structfield id="GSourceFuncs.prepare">prepare</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>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 &gt;= 0.  Since 2.36 this may
be <link linkend="NULL:CAPS"><literal>NULL</literal></link>, in which case the effect is as if the function always returns
<link linkend="FALSE:CAPS"><literal>FALSE</literal></link> with a timeout of -1.  If <parameter>prepare</parameter>
returns a
timeout and the source also has a ready time set, then the
lower of the two will be used.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GSourceFuncs.check">check</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>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.  Since 2.36 this may
be <link linkend="NULL:CAPS"><literal>NULL</literal></link>, in which case the effect is as if the function always returns
<link linkend="FALSE:CAPS"><literal>FALSE</literal></link>.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GSourceFuncs.dispatch">dispatch</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>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, or if a ready time
has been reached. The <parameter>dispatch</parameter>
function receives a callback function and
user 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. The
return value of the <parameter>dispatch</parameter>
function should be <link linkend="G-SOURCE-REMOVE:CAPS"><type>G_SOURCE_REMOVE</type></link> if the
source should be removed or <link linkend="G-SOURCE-CONTINUE:CAPS"><type>G_SOURCE_CONTINUE</type></link> to keep it.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GSourceFuncs.finalize">finalize</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Called when the source is finalized. At this point, the source
will have been destroyed, had its callback cleared, and have been removed
from its <link linkend="GMainContext"><type>GMainContext</type></link>, but it will still have its final reference count,
so methods can be called on it from within this function.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>
<refsect2 id="GSourceCallbackFuncs" role="struct">
<title>struct GSourceCallbackFuncs</title>
<indexterm zone="GSourceCallbackFuncs"><primary sortas="SourceCallbackFuncs">GSourceCallbackFuncs</primary></indexterm>
<programlisting language="C">struct GSourceCallbackFuncs {
  void (*ref)   (gpointer     cb_data);
  void (*unref) (gpointer     cb_data);
  void (*get)   (gpointer     cb_data,
                 GSource     *source, 
                 GSourceFunc *func,
                 gpointer    *data);
};
</programlisting>
<para>The <literal>GSourceCallbackFuncs</literal> struct contains
functions for managing callback objects.</para>
<refsect3 id="GSourceCallbackFuncs.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><structfield id="GSourceCallbackFuncs.ref">ref</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Called when a reference is added to the callback object</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GSourceCallbackFuncs.unref">unref</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Called when a reference to the callback object is dropped</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GSourceCallbackFuncs.get">get</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Called to extract the callback function and data from the
callback object.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>

</refsect1>

</refentry>
