main.sgml

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

<refentry id="glib-The-Main-Event-Loop">
<refmeta>
<refentrytitle>The Main Event Loop</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>The Main Event Loop</refname><refpurpose>manages all available sources of events.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


struct      <link linkend="GMainLoop">GMainLoop</link>;
<link linkend="GMainLoop">GMainLoop</link>*  <link linkend="g-main-loop-new">g_main_loop_new</link>                 (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="gboolean">gboolean</link> is_running);
<link linkend="GMainLoop">GMainLoop</link>*  <link linkend="g-main-loop-ref">g_main_loop_ref</link>                 (<link linkend="GMainLoop">GMainLoop</link> *loop);
void        <link linkend="g-main-loop-unref">g_main_loop_unref</link>               (<link linkend="GMainLoop">GMainLoop</link> *loop);
void        <link linkend="g-main-loop-run">g_main_loop_run</link>                 (<link linkend="GMainLoop">GMainLoop</link> *loop);
void        <link linkend="g-main-loop-quit">g_main_loop_quit</link>                (<link linkend="GMainLoop">GMainLoop</link> *loop);
<link linkend="gboolean">gboolean</link>    <link linkend="g-main-loop-is-running">g_main_loop_is_running</link>          (<link linkend="GMainLoop">GMainLoop</link> *loop);
<link linkend="GMainContext">GMainContext</link>* <link linkend="g-main-loop-get-context">g_main_loop_get_context</link>       (<link linkend="GMainLoop">GMainLoop</link> *loop);
#define     <link linkend="g-main-new">g_main_new</link>                      (is_running)
#define     <link linkend="g-main-destroy">g_main_destroy</link>                  (loop)
#define     <link linkend="g-main-run">g_main_run</link>                      (loop)
#define     <link linkend="g-main-quit">g_main_quit</link>                     (loop)
#define     <link linkend="g-main-is-running">g_main_is_running</link>               (loop)

#define     <link linkend="G-PRIORITY-HIGH-CAPS">G_PRIORITY_HIGH</link>
#define     <link linkend="G-PRIORITY-DEFAULT-CAPS">G_PRIORITY_DEFAULT</link>
#define     <link linkend="G-PRIORITY-HIGH-IDLE-CAPS">G_PRIORITY_HIGH_IDLE</link>
#define     <link linkend="G-PRIORITY-DEFAULT-IDLE-CAPS">G_PRIORITY_DEFAULT_IDLE</link>
#define     <link linkend="G-PRIORITY-LOW-CAPS">G_PRIORITY_LOW</link>

struct      <link linkend="GMainContext">GMainContext</link>;
<link linkend="GMainContext">GMainContext</link>* <link linkend="g-main-context-new">g_main_context_new</link>            (void);
void        <link linkend="g-main-context-ref">g_main_context_ref</link>              (<link linkend="GMainContext">GMainContext</link> *context);
void        <link linkend="g-main-context-unref">g_main_context_unref</link>            (<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="GMainContext">GMainContext</link>* <link linkend="g-main-context-default">g_main_context_default</link>        (void);
<link linkend="gboolean">gboolean</link>    <link linkend="g-main-context-iteration">g_main_context_iteration</link>        (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="gboolean">gboolean</link> may_block);
#define     <link linkend="g-main-iteration">g_main_iteration</link>                (may_block)
<link linkend="gboolean">gboolean</link>    <link linkend="g-main-context-pending">g_main_context_pending</link>          (<link linkend="GMainContext">GMainContext</link> *context);
#define     <link linkend="g-main-pending">g_main_pending</link>                  ()
<link linkend="GSource">GSource</link>*    <link linkend="g-main-context-find-source-by-id">g_main_context_find_source_by_id</link>
                                            (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="guint">guint</link> source_id);
<link linkend="GSource">GSource</link>*    <link linkend="g-main-context-find-source-by-user-data">g_main_context_find_source_by_user_data</link>
                                            (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="gpointer">gpointer</link> user_data);
<link linkend="GSource">GSource</link>*    <link linkend="g-main-context-find-source-by-funcs-user-data">g_main_context_find_source_by_funcs_user_data</link>
                                            (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="GSourceFuncs">GSourceFuncs</link> *funcs,
                                             <link linkend="gpointer">gpointer</link> user_data);
void        <link linkend="g-main-context-wakeup">g_main_context_wakeup</link>           (<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="gboolean">gboolean</link>    <link linkend="g-main-context-acquire">g_main_context_acquire</link>          (<link linkend="GMainContext">GMainContext</link> *context);
void        <link linkend="g-main-context-release">g_main_context_release</link>          (<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="gboolean">gboolean</link>    <link linkend="g-main-context-wait">g_main_context_wait</link>             (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="GCond">GCond</link> *cond,
                                             <link linkend="GMutex">GMutex</link> *mutex);
<link linkend="gboolean">gboolean</link>    <link linkend="g-main-context-prepare">g_main_context_prepare</link>          (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="gint">gint</link> *priority);
<link linkend="gint">gint</link>        <link linkend="g-main-context-query">g_main_context_query</link>            (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="gint">gint</link> max_priority,
                                             <link linkend="gint">gint</link> *timeout,
                                             <link linkend="GPollFD">GPollFD</link> *fds,
                                             <link linkend="gint">gint</link> n_fds);
<link linkend="gint">gint</link>        <link linkend="g-main-context-check">g_main_context_check</link>            (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="gint">gint</link> max_priority,
                                             <link linkend="GPollFD">GPollFD</link> *fds,
                                             <link linkend="gint">gint</link> n_fds);
void        <link linkend="g-main-context-dispatch">g_main_context_dispatch</link>         (<link linkend="GMainContext">GMainContext</link> *context);
void        <link linkend="g-main-context-set-poll-func">g_main_context_set_poll_func</link>    (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="GPollFunc">GPollFunc</link> func);
<link linkend="GPollFunc">GPollFunc</link>   <link linkend="g-main-context-get-poll-func">g_main_context_get_poll_func</link>    (<link linkend="GMainContext">GMainContext</link> *context);
<link linkend="gint">gint</link>        (<link linkend="GPollFunc">*GPollFunc</link>)                    (<link linkend="GPollFD">GPollFD</link> *ufds,
                                             <link linkend="guint">guint</link> nfsd,
                                             <link linkend="gint">gint</link> timeout);
void        <link linkend="g-main-context-add-poll">g_main_context_add_poll</link>         (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="GPollFD">GPollFD</link> *fd,
                                             <link linkend="gint">gint</link> priority);
void        <link linkend="g-main-context-remove-poll">g_main_context_remove_poll</link>      (<link linkend="GMainContext">GMainContext</link> *context,
                                             <link linkend="GPollFD">GPollFD</link> *fd);
#define     <link linkend="g-main-set-poll-func">g_main_set_poll_func</link>            (func)

<link linkend="GSource">GSource</link>*    <link linkend="g-timeout-source-new">g_timeout_source_new</link>            (<link linkend="guint">guint</link> interval);
<link linkend="guint">guint</link>       <link linkend="g-timeout-add">g_timeout_add</link>                   (<link linkend="guint">guint</link> interval,
                                             <link linkend="GSourceFunc">GSourceFunc</link> function,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="guint">guint</link>       <link linkend="g-timeout-add-full">g_timeout_add_full</link>              (<link linkend="gint">gint</link> priority,
                                             <link linkend="guint">guint</link> interval,
                                             <link linkend="GSourceFunc">GSourceFunc</link> function,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> notify);

<link linkend="GSource">GSource</link>*    <link linkend="g-idle-source-new">g_idle_source_new</link>               (void);
<link linkend="guint">guint</link>       <link linkend="g-idle-add">g_idle_add</link>                      (<link linkend="GSourceFunc">GSourceFunc</link> function,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="guint">guint</link>       <link linkend="g-idle-add-full">g_idle_add_full</link>                 (<link linkend="gint">gint</link> priority,
                                             <link linkend="GSourceFunc">GSourceFunc</link> function,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> notify);
<link linkend="gboolean">gboolean</link>    <link linkend="g-idle-remove-by-data">g_idle_remove_by_data</link>           (<link linkend="gpointer">gpointer</link> data);

struct      <link linkend="GPollFD">GPollFD</link>;

struct      <link linkend="GSource">GSource</link>;
struct      <link linkend="GSourceFuncs">GSourceFuncs</link>;
struct      <link linkend="GSourceCallbackFuncs">GSourceCallbackFuncs</link>;
void        (<link linkend="GSourceDummyMarshal">*GSourceDummyMarshal</link>)          (void);
<link linkend="GSource">GSource</link>*    <link linkend="g-source-new">g_source_new</link>                    (<link linkend="GSourceFuncs">GSourceFuncs</link> *source_funcs,
                                             <link linkend="guint">guint</link> struct_size);
<link linkend="GSource">GSource</link>*    <link linkend="g-source-ref">g_source_ref</link>                    (<link linkend="GSource">GSource</link> *source);
void        <link linkend="g-source-unref">g_source_unref</link>                  (<link linkend="GSource">GSource</link> *source);
<link linkend="guint">guint</link>       <link linkend="g-source-attach">g_source_attach</link>                 (<link linkend="GSource">GSource</link> *source,
                                             <link linkend="GMainContext">GMainContext</link> *context);
void        <link linkend="g-source-destroy">g_source_destroy</link>                (<link linkend="GSource">GSource</link> *source);
void        <link linkend="g-source-set-priority">g_source_set_priority</link>           (<link linkend="GSource">GSource</link> *source,
                                             <link linkend="gint">gint</link> priority);
<link linkend="gint">gint</link>        <link linkend="g-source-get-priority">g_source_get_priority</link>           (<link linkend="GSource">GSource</link> *source);
void        <link linkend="g-source-set-can-recurse">g_source_set_can_recurse</link>        (<link linkend="GSource">GSource</link> *source,
                                             <link linkend="gboolean">gboolean</link> can_recurse);
<link linkend="gboolean">gboolean</link>    <link linkend="g-source-get-can-recurse">g_source_get_can_recurse</link>        (<link linkend="GSource">GSource</link> *source);
<link linkend="guint">guint</link>       <link linkend="g-source-get-id">g_source_get_id</link>                 (<link linkend="GSource">GSource</link> *source);
<link linkend="GMainContext">GMainContext</link>* <link linkend="g-source-get-context">g_source_get_context</link>          (<link linkend="GSource">GSource</link> *source);
void        <link linkend="g-source-set-callback">g_source_set_callback</link>           (<link linkend="GSource">GSource</link> *source,
                                             <link linkend="GSourceFunc">GSourceFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> notify);
<link linkend="gboolean">gboolean</link>    (<link linkend="GSourceFunc">*GSourceFunc</link>)                  (<link linkend="gpointer">gpointer</link> data);
void        <link linkend="g-source-set-callback-indirect">g_source_set_callback_indirect</link>  (<link linkend="GSource">GSource</link> *source,
                                             <link linkend="gpointer">gpointer</link> callback_data,
                                             <link linkend="GSourceCallbackFuncs">GSourceCallbackFuncs</link> *callback_funcs);
void        <link linkend="g-source-add-poll">g_source_add_poll</link>               (<link linkend="GSource">GSource</link> *source,
                                             <link linkend="GPollFD">GPollFD</link> *fd);
void        <link linkend="g-source-remove-poll">g_source_remove_poll</link>            (<link linkend="GSource">GSource</link> *source,
                                             <link linkend="GPollFD">GPollFD</link> *fd);
void        <link linkend="g-source-get-current-time">g_source_get_current_time</link>       (<link linkend="GSource">GSource</link> *source,
                                             <link linkend="GTimeVal">GTimeVal</link> *timeval);
<link linkend="gboolean">gboolean</link>    <link linkend="g-source-remove">g_source_remove</link>                 (<link linkend="guint">guint</link> tag);
<link linkend="gboolean">gboolean</link>    <link linkend="g-source-remove-by-funcs-user-data">g_source_remove_by_funcs_user_data</link>
                                            (<link linkend="GSourceFuncs">GSourceFuncs</link> *funcs,
                                             <link linkend="gpointer">gpointer</link> user_data);
<link linkend="gboolean">gboolean</link>    <link linkend="g-source-remove-by-user-data">g_source_remove_by_user_data</link>    (<link linkend="gpointer">gpointer</link> user_data);

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
  <para>
    The main event loop manages all the available sources of events for
    GLib and GTK+ applications. These events can come from any number of
    different types of sources such as file descriptors (plain files,
    pipes or sockets) and timeouts.  New types of event sources can also
    be added using <link linkend="g-source-add">g_source_add</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">GMainContext</link>.
    A <link linkend="GMainContext">GMainContext</link> can only be running in a single thread, but
    sources can be added to it and removed from it from other threads.
  </para>
  <para>
    Each event source is assigned a priority.  The default priority,
    <link linkend="G-PRIORITY-DEFAULT-CAPS">G_PRIORITY_DEFAULT</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">GMainLoop</link> data type represents a main event loop.  A <link linkend="GMainLoop">GMainLoop</link>
    is created with <link linkend="g-main-loop-new">g_main_loop_new</link>(). After adding the initial event sources,
    <link linkend="g-main-loop-run">g_main_loop_run</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">g_main_loop_quit</link>() to exit the main loop, and <link linkend="g-main-loop-run">g_main_loop_run</link>() returns.
  </para>
  <para>
    It is possible to create new instances of <link linkend="GMainLoop">GMainLoop</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">GMainContext</link>, and will be checked and dispatched for all main
    loops associated with that <link linkend="GMainContext">GMainContext</link>.
  </para>
  <para>
    GTK+ contains wrappers of many of these functions, e.g. <link linkend="gtk-main">gtk_main</link>(),
    <link linkend="gtk-main-quit">gtk_main_quit</link>(), <link linkend="gtk-events-pending">gtk_events_pending</link>(), <link linkend="gtk-idle-add">gtk_idle_add</link>(),
    <link linkend="gtk-timeout-add">gtk_timeout_add</link>() and <link linkend="gtk-input-add-full">gtk_input_add_full</link>(). 
  </para>
  <refsect2>
    <title>Creating new sources types</title>
    <para>
      One of the unusual features of the GTK+ main loop functionality
      is that new types of event source can be created and used in
      addition to the builtin type of event source. A new event source
      type is used for handling GDK events. A new source type is
      created by <firstterm>deriving</firstterm> from the <link linkend="GSource">GSource</link>
      structure. The derived type of source is represented by a
      structure that has the <link linkend="GSource">GSource</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">g_source_new</link>() passing
      in the size of the derived structure and a table of functions.
      These <link linkend="GSourceFuncs">GSourceFuncs</link> determine the behavior of the new source
      types.
    </para>
    <para>
      New source types basically interact with with the main context
      in two ways. Their prepare function in <link linkend="GSourceFuncs">GSourceFuncs</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">g_source_add_poll</link>().
    </para>
  </refsect2>
  <refsect2>
    <title>Customizing the main loop iteration</title>
    <para>
      Single iterations of a <link linkend="GMainContext">GMainContext</link> can be run with
      <link linkend="g-main-context-iteration">g_main_context_iteration</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">GMainLoop</link> with an external
      main loop. In such cases, you can call the component functions
      of <link linkend="g-main-context-iteration">g_main_context_iteration</link>() directly. These functions
      are <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>() and <link linkend="g-main-context-dispatch">g_main_context_dispatch</link>().
    </para>
    <para>
      The operation of these functions can best be seen in terms
      of a state diagram, as shown in <xref linkend="mainloop-states">.