main.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry> a <link linkend="GMainContext">GMainContext</link> (if <literal>NULL</literal>, the default context will be used)
</entry></row>
<row><entry align="right"><parameter>source_id</parameter>&nbsp;:</entry>
<entry> the source ID, as returned by <link linkend="g-source-get-id">g_source_get_id</link>()
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the <link linkend="GSource">GSource</link> if found, otherwise, <literal>NULL</literal>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-main-context-find-source-by-user-data">g_main_context_find_source_by_user_data ()</title>
<programlisting><link linkend="GSource">GSource</link>*    g_main_context_find_source_by_user_data
                                            (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Finds a source with the given user data for the callback.  If
multiple sources exist with the same user data, the first
one found will be returned.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry> a <link linkend="GMainContext">GMainContext</link>
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> the user_data for the callback.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the source, if one was found, otherwise <literal>NULL</literal>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-main-context-find-source-by-funcs-user-data">g_main_context_find_source_by_funcs_user_data ()</title>
<programlisting><link linkend="GSource">GSource</link>*    g_main_context_find_source_by_funcs_user_data
                                            (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="GSourceFuncs">GSourceFuncs</link> *funcs,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Finds a source with the given source functions and user data.  If
multiple sources exist with the same source function and user data,
the first one found will be returned.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry> a <link linkend="GMainContext">GMainContext</link> (if <literal>NULL</literal>, the default context will be used).
</entry></row>
<row><entry align="right"><parameter>funcs</parameter>&nbsp;:</entry>
<entry> the <parameter>source_funcs</parameter> passed to <link linkend="g-source-new">g_source_new</link>().
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> the user data from the callback.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the source, if one was found, otherwise <literal>NULL</literal>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-main-context-wakeup">g_main_context_wakeup ()</title>
<programlisting>void        g_main_context_wakeup           (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
If <parameter>context</parameter> is currently waiting in a <function><link linkend="poll">poll</link>()</function>, interrupt
the <function><link linkend="poll">poll</link>()</function>, and continue the iteration process.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry> a <link linkend="GMainContext">GMainContext</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-main-context-acquire">g_main_context_acquire ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_main_context_acquire          (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Tries to become the owner of the specified context.
If some other context is the owner of the context,
returns <literal>FALSE</literal> immediately. Ownership is properly
recursive: the owner can require ownership again
and will release ownership when <link linkend="g-main-context-release">g_main_context_release</link>()
is called as many times as <link linkend="g-main-context-acquire">g_main_context_acquire</link>().
</para>
<para>
You must be the owner of a context before you
can call <link linkend="g-main-context-prepare">g_main_context_prepare</link>(), <link linkend="g-main-context-query">g_main_context_query</link>(),
<link linkend="g-main-context-check">g_main_context_check</link>(), <link linkend="g-main-context-dispatch">g_main_context_dispatch</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry> a <link linkend="GMainContext">GMainContext</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the operation succeeded, and
  this thread is now the owner of <parameter>context</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-main-context-release">g_main_context_release ()</title>
<programlisting>void        g_main_context_release          (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
<para>
Releases ownership of a context previously acquired by this thread
with <link linkend="g-main-context-acquire">g_main_context_acquire</link>(). If the context was acquired multiple
times, the only release ownership when <link linkend="g-main-context-release">g_main_context_release</link>()
is called as many times as it was acquired.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry> a <link linkend="GMainContext">GMainContext</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-main-context-wait">g_main_context_wait ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_main_context_wait             (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="GCond">GCond</link> *cond,
                                             <link linkend="GMutex">GMutex</link> *mutex);</programlisting>
<para>
Tries to become the owner of the specified context,
as with <link linkend="g-main-context-acquire">g_main_context_acquire</link>(). But if another thread
is the owner, atomically drop <parameter>mutex</parameter> and wait on <parameter>cond</parameter> until 
that owner releases ownership or until <parameter>cond</parameter> is signaled, then
try again (once) to become the owner.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry> a <link linkend="GMainContext">GMainContext</link>
</entry></row>
<row><entry align="right"><parameter>cond</parameter>&nbsp;:</entry>
<entry> a condition variable
</entry></row>
<row><entry align="right"><parameter>mutex</parameter>&nbsp;:</entry>
<entry> a mutex, currently held
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the operation succeeded, and
  this thread is now the owner of <parameter>context</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-main-context-prepare">g_main_context_prepare ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_main_context_prepare          (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="gint">gint</link> *priority);</programlisting>
<para>
Prepares to poll sources within a main loop. The resulting information
for polling is determined by calling <link linkend="g-main-context-query">g_main_context_query</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry> a <link linkend="GMainContext">GMainContext</link>
</entry></row>
<row><entry align="right"><parameter>priority</parameter>&nbsp;:</entry>
<entry> location to store priority of highest priority
           source already ready.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if some source is ready to be dispatched
              prior to polling.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-main-context-query">g_main_context_query ()</title>
<programlisting><link linkend="gint">gint</link>        g_main_context_query            (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="gint">gint</link> max_priority,
                                             <link linkend="gint">gint</link> *timeout,
                                             <link linkend="GPollFD">GPollFD</link> *fds,
                                             <link linkend="gint">gint</link> n_fds);</programlisting>
<para>
Determines information necessary to poll this main loop.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry> a <link linkend="GMainContext">GMainContext</link>
</entry></row>
<row><entry align="right"><parameter>max_priority</parameter>&nbsp;:</entry>
<entry> maximum priority source to check
</entry></row>
<row><entry align="right"><parameter>timeout</parameter>&nbsp;:</entry>
<entry> location to store timeout to be used in polling
</entry></row>
<row><entry align="right"><parameter>fds</parameter>&nbsp;:</entry>
<entry> location to store <link linkend="GPollFD">GPollFD</link> records that need to be polled.
</entry></row>
<row><entry align="right"><parameter>n_fds</parameter>&nbsp;:</entry>
<entry> length of <parameter>fds</parameter>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> 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.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-main-context-check">g_main_context_check ()</title>
<programlisting><link linkend="gint">gint</link>        g_main_context_check            (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="gint">gint</link> max_priority,
                                             <link linkend="GPollFD">GPollFD</link> *fds,
                                             <link linkend="gint">gint</link> n_fds);</programlisting>
<para>
Passes the results of polling back to the main loop.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry> a <link linkend="GMainContext">GMainContext</link>
</entry></row>
<row><entry align="right"><parameter>max_priority</parameter>&nbsp;:</entry>
<entry> the maximum numerical priority of sources to check