main.sgml

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

<!-- ##### SECTION Title ##### -->
The Main Event Loop

<!-- ##### SECTION Short_Description ##### -->
manages all available sources of events.

<!-- ##### SECTION Long_Description ##### -->
  <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 g_source_add().
  </para>
  <para>
    To allow multiple independent sets of sources to be handled in
    different threads, each source is associated with a #GMainContext.
    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,
    #G_PRIORITY_DEFAULT, 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 #GMainLoop data type represents a main event loop.  A #GMainLoop
    is created with g_main_loop_new(). After adding the initial event sources,
    g_main_loop_run() 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
    g_main_loop_quit() to exit the main loop, and g_main_loop_run() returns.
  </para>
  <para>
    It is possible to create new instances of #GMainLoop recursively.
    This is often used in GTK+ applications when showing modal dialog
    boxes. Note that event sources are associated with a particular
    #GMainContext, and will be checked and dispatched for all main
    loops associated with that #GMainContext.
  </para>
  <para>
    GTK+ contains wrappers of many of these functions, e.g. gtk_main(),
    gtk_main_quit(), gtk_events_pending(), gtk_idle_add(),
    gtk_timeout_add() and gtk_input_add_full(). 
  </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 #GSource
      structure. The derived type of source is represented by a
      structure that has the #GSource structure as a first element,
      and other elements specific to the new source type. To create
      an instance of the new source type, call g_source_new() passing
      in the size of the derived structure and a table of functions.
      These #GSourceFuncs 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 #GSourceFuncs 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 g_source_add_poll().
    </para>
  </refsect2>
  <refsect2>
    <title>Customizing the main loop iteration</title>
    <para>
      Single iterations of a #GMainContext can be run with
      g_main_context_iteration(). In some cases, more detailed control
      of exactly how the details of the main loop work is desired,
      for instance, when integrating the #GMainLoop with an external
      main loop. In such cases, you can call the component functions
      of g_main_context_iteration() directly. These functions
      are g_main_context_prepare(), g_main_context_query(),
      g_main_context_check() and g_main_context_dispatch().
    </para>
    <para>
      The operation of these functions can best be seen in terms
      of a state diagram, as shown in <xref linkend="mainloop-states">.
    </para>
    <figure id="mainloop-states">
      <title>States of a Main Context</title>
      <graphic fileref="mainloop-states.gif" format="gif"></graphic>
    </figure>
  </refsect2>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### STRUCT GMainLoop ##### -->
<para>
The <structname>GMainLoop</structname> struct is an opaque data type 
representing the main event loop of a GLib or GTK+ application.
</para>


<!-- ##### FUNCTION g_main_loop_new ##### -->
<para>

</para>

@context: 
@is_running: 
@Returns: 


<!-- ##### FUNCTION g_main_loop_ref ##### -->
<para>

</para>

@loop: 
@Returns: 


<!-- ##### FUNCTION g_main_loop_unref ##### -->
<para>

</para>

@loop: 


<!-- ##### FUNCTION g_main_loop_run ##### -->
<para>

</para>

@loop: 


<!-- ##### FUNCTION g_main_loop_quit ##### -->
<para>

</para>

@loop: 


<!-- ##### FUNCTION g_main_loop_is_running ##### -->
<para>

</para>

@loop: 
@Returns: 


<!-- ##### FUNCTION g_main_loop_get_context ##### -->
<para>

</para>

@loop: 
@Returns: 


<!-- ##### MACRO g_main_new ##### -->
<para>
Creates a new #GMainLoop for the default main loop. A compatibility
macro, see g_main_loop_new().
</para>

@is_running: set to %TRUE to indicate that the loop is running. This is not
very important since calling g_main_run() will set this to %TRUE anyway.
@Returns: a new #GMainLoop.


<!-- ##### MACRO g_main_destroy ##### -->
<para>
Frees the memory allocated for the #GMainLoop. A compatibility macro, see
g_main_loop_destroy().
</para>

@loop: a #GMainLoop.


<!-- ##### MACRO g_main_run ##### -->
<para>
Runs a main loop until it stops running. A compatibility macro, see g_main_loop_run().
</para>

@loop: a #GMainLoop.


<!-- ##### MACRO g_main_quit ##### -->
<para>
Stops the #GMainLoop. If g_main_run() was called to run the #GMainLoop,
it will now return. A compatibility macro, see g_main_loop_quit().
</para>

@loop: a #GMainLoop.


<!-- ##### MACRO g_main_is_running ##### -->
<para>
Checks if the main loop is running. A compatibility macro, see
g_main_loop_is_running().    
</para>

@loop: a #GMainLoop.
@Returns: %TRUE if the main loop is running.


<!-- ##### MACRO G_PRIORITY_HIGH ##### -->
<para>
Use this for high priority event sources.
It is not used within GLib or GTK+.
</para>



<!-- ##### MACRO G_PRIORITY_DEFAULT ##### -->
<para>
Use this for default priority event sources.
In GLib this priority is used when adding timeout functions with
g_timeout_add().
In GDK this priority is used for events from the X server.
</para>



<!-- ##### MACRO G_PRIORITY_HIGH_IDLE ##### -->
<para>
Use this for high priority idle functions.
GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, and
#G_PRIORITY_HIGH_IDLE + 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>



<!-- ##### MACRO G_PRIORITY_DEFAULT_IDLE ##### -->
<para>
Use this for default priority idle functions.
In GLib this priority is used when adding idle functions with g_idle_add().
</para>



<!-- ##### MACRO G_PRIORITY_LOW ##### -->
<para>
Use this for very low priority background tasks.
It is not used within GLib or GTK+.
</para>



<!-- ##### STRUCT GMainContext ##### -->
<para>
The <structname>GMainContext</structname> struct is an opaque data type 
representing a set of sources to be handled in a main loop. 
</para>


<!-- ##### FUNCTION g_main_context_new ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION g_main_context_ref ##### -->
<para>

</para>

@context: 


<!-- ##### FUNCTION g_main_context_unref ##### -->
<para>

</para>

@context: 


<!-- ##### FUNCTION g_main_context_default ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION g_main_context_iteration ##### -->
<para>

</para>

@context: 
@may_block: 
@Returns: 


<!-- ##### MACRO g_main_iteration ##### -->
<para>
Runs a single iteration for the default #GMainContext.
A compatibility macro, see g_main_context_iteration().
</para>

@may_block: set to %TRUE 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 %FALSE it will return immediately if no event source is ready to be
processed.
@Returns: %TRUE if more events are pending.


<!-- ##### FUNCTION g_main_context_pending ##### -->
<para>

</para>

@context: 
@Returns: 


<!-- ##### MACRO g_main_pending ##### -->
<para>
Checks if any events are pending for the default #GMainContext
(i.e. ready to be processed).  A compatibility macro, see
g_main_context_pending().
</para>

@Returns: %TRUE if any events are pending.


<!-- ##### FUNCTION g_main_context_find_source_by_id ##### -->
<para>

</para>

@context: 
@source_id: 
@Returns: 
<!-- # Unused Parameters # -->
@id: 


<!-- ##### FUNCTION g_main_context_find_source_by_user_data ##### -->
<para>

</para>

@context: 
@user_data: 
@Returns: 


<!-- ##### FUNCTION g_main_context_find_source_by_funcs_user_data ##### -->
<para>

</para>

@context: 
@funcs: 
@user_data: 
@Returns: 


<!-- ##### FUNCTION g_main_context_wakeup ##### -->
<para>

</para>

@context: 


<!-- ##### FUNCTION g_main_context_acquire ##### -->
<para>

</para>

@context: 
@Returns: 


<!-- ##### FUNCTION g_main_context_release ##### -->
<para>

</para>

@context: 


<!-- ##### FUNCTION g_main_context_wait ##### -->
<para>

</para>

@context: 
@cond: 
@mutex: 
@Returns: 


<!-- ##### FUNCTION g_main_context_prepare ##### -->
<para>

</para>

@context: 
@priority: 
@Returns: 


<!-- ##### FUNCTION g_main_context_query ##### -->
<para>

</para>

@context: 
@max_priority: 
@timeout: 
@fds: 
@n_fds: 
@Returns: 


<!-- ##### FUNCTION g_main_context_check ##### -->
<para>

</para>

@context: 
@max_priority: 
@fds: 
@n_fds: 
@Returns: 


<!-- ##### FUNCTION g_main_context_dispatch ##### -->
<para>

</para>

@context: 


<!-- ##### FUNCTION g_main_context_set_poll_func ##### -->
<para>