1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 manages all available sources of events.
7 <!-- ##### SECTION Long_Description ##### -->
9 The main event loop manages all the available sources of events for
10 GLib and GTK+ applications. These events can come from any number of
11 different types of sources such as file descriptors (plain files,
12 pipes or sockets) and timeouts. New types of event sources can also
13 be added using g_source_add().
16 To allow multiple independent sets of sources to be handled in
17 different threads, each source is associated with a #GMainContext.
18 A #GMainContext can only be running in a single thread, but
19 sources can be added and removed from it from other threads.
22 Each event source is assigned a priority. The default priority,
23 #G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher
24 priorities. Values greater than 0 denote lower priorities. Events
25 from high priority sources are always processed before events from
26 lower priority sources.
29 Idle functions can also be added, and assigned a priority. These will
30 be run whenever no events with a higher priority are ready to be
34 The #GMainLoop data type represents a main event loop. A #GMainLoop
35 is created with g_main_loop_new(). After adding the initial event sources,
36 g_main_run() is called. This continuously checks for new events from
37 each of the event sources and dispatches them. Finally, the
38 processing of an event from one of the sources leads to a call to
39 g_main_quit() to exit the main loop, and g_main_run() returns.
42 It is possible to create new instances of #GMainLoop recursively.
43 This is often used in GTK+ applications when showing modal dialog
44 boxes. Note that event sources are associated with a particular
45 #GMainContext, and will be checked and dispatched for all main
46 loops associated with that #GMainContext.
49 GTK+ contains wrappers of many of these functions, e.g. gtk_main(),
50 gtk_main_quit(), gtk_events_pending(), gtk_idle_add(),
51 gtk_timeout_add() and gtk_input_add_full().
54 <title>Creating new sources types</title>
56 One of the unusual features of the GTK+ main loop functionality
57 is that new types of event source can be created and used in
58 addition to the builtin type of event source. A new event source
59 type is used for handling GDK events. A new source type is
60 created by <firstterm>deriving</firstterm> from the #GSource
61 structure. The derived type of source is represented by a
62 structure that has the #GSource structure as a first elemeent,
63 and other elements specific to the new source type. To create
64 an instance of the new source type, call g_source_new() passing
65 in the size of the derived structure and a table of functions.
66 These #GSourceFuncs determine the behavior of the new source
70 New source types basically interact with with the main context
71 in two ways. Their prepare function in #GSourceFuncs can set
72 a timeout to determine the maximum amount of time that the
73 main loop will sleep before checking the source again. In
74 addition, or as well, the source can add file descriptors to
75 the set that the main context checks using g_source_add_poll().
79 <title>Customizing the main loop iteration</title>
81 Single iterations of a #GMainContext can be run with
82 g_main_context_iteration(). In some cases, more detailed control
83 of exactly how the details of the main loop work is desired,
84 for instance, when integrating the #GMainLoop with an external
85 main loop. In such cases, you can call the component functions
86 of g_main_context_iteration() directly. These functions
87 are g_main_context_prepare(), g_main_context_query(),
88 g_main_context_check() and g_main_context_dispatch().
91 The operation of these functions can best be seen in terms
92 of a state diagram, as shown in <xref linkend="mainloop-states">.
94 <figure id="mainloop-states">
95 <title>States of a Main Context</title>
96 <graphic fileref="mainloop-states.gif" format="gif"></graphic>
100 <!-- ##### SECTION See_Also ##### -->
105 <!-- ##### STRUCT GMainLoop ##### -->
107 The #GMainLoop struct is an opaque data type representing the main event loop
108 of a GLib or GTK+ application.
112 <!-- ##### FUNCTION g_main_new ##### -->
114 Creates a new #GMainLoop for the default main loop. A compatibility
115 macro, see g_main_loop_new().
118 @is_running: set to TRUE to indicate that the loop is running. This is not
119 very important since calling g_main_run() will set this to TRUE anyway.
120 @Returns: a new #GMainLoop.
123 <!-- ##### FUNCTION g_main_destroy ##### -->
125 Frees the memory allocated for the #GMainLoop. A compatibility macro, see
126 g_main_loop_destroy().
132 <!-- ##### FUNCTION g_main_run ##### -->
134 Runs a main loop until it stops running. A compatibility macro, see g_main_loop_run().
140 <!-- ##### FUNCTION g_main_quit ##### -->
142 Stops the #GMainLoop. If g_main_run() was called to run the #GMainLoop,
143 it will now return. A compatibility macro, see g_main_loop_quit().
149 <!-- ##### FUNCTION g_main_is_running ##### -->
151 Checks if the main loop is running. A compatibility macro, see
152 g_main_loop_is_running().
156 @Returns: %TRUE if the main loop is running.
159 <!-- ##### MACRO G_PRIORITY_HIGH ##### -->
161 Use this for high priority event sources.
162 It is not used within GLib or GTK+.
167 <!-- ##### MACRO G_PRIORITY_DEFAULT ##### -->
169 Use this for default priority event sources.
170 In GLib this priority is used when adding timeout functions with
172 In GDK this priority is used for events from the X Windows server.
177 <!-- ##### MACRO G_PRIORITY_HIGH_IDLE ##### -->
179 Use this for high priority idle functions.
180 GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, and
181 #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is done to
182 ensure that any pending resizes are processed before any pending redraws,
183 so that widgets are not redrawn twice unnecessarily.)
188 <!-- ##### MACRO G_PRIORITY_DEFAULT_IDLE ##### -->
190 Use this for default priority idle functions.
191 In GLib this priority is used when adding idle functions with g_idle_add().
196 <!-- ##### MACRO G_PRIORITY_LOW ##### -->
198 Use this for very low priority background tasks.
199 It is not used within GLib or GTK+.
204 <!-- ##### FUNCTION g_main_iteration ##### -->
206 Runs a single iteration for the default #GMainContext.
207 A compatibility macro, see g_main_context_iteration().
210 @may_block: set to TRUE if it should block (i.e. wait) until an event source
211 becomes ready. It will return after an event source has been processed.
212 If set to FALSE it will return immediately if no event source is ready to be
214 @Returns: TRUE if more events are pending.
217 <!-- ##### FUNCTION g_main_pending ##### -->
219 Checks if any events are pending for the default #GMainContext
220 (i.e. ready to be processed). A compatibility macro, see
221 g_main_context_pending().
224 @Returns: %TRUE if any events are pending.
227 <!-- ##### USER_FUNCTION GPollFunc ##### -->
229 Specifies the type of function passed to g_main_set_poll_func().
230 The semantics of the function should match those of the
231 <function>poll()</function> system call.
234 @ufds: an array of #GPollFD elements.
235 @nfsd: the number of elements in @ufds.
236 @timeout: the maximum time to wait for an event of the file descriptors.
237 A negative value indicates an infinite timeout.
238 @Returns: the number of #GPollFD elements which have events or errors reported,
239 or -1 if an error occurred.
242 <!-- ##### FUNCTION g_main_set_poll_func ##### -->
244 Sets the function to use for the handle polling of file descriptors
245 for the default main context. This is a compatability macro, see
246 g_main_context_set_poll_func() for full details.
249 @func: the function to call to poll all file descriptors.
252 <!-- ##### FUNCTION g_timeout_add ##### -->
262 <!-- ##### FUNCTION g_timeout_add_full ##### -->
274 <!-- ##### FUNCTION g_idle_add ##### -->
283 <!-- ##### FUNCTION g_idle_add_full ##### -->
292 <!-- # Unused Parameters # -->
296 <!-- ##### FUNCTION g_idle_remove_by_data ##### -->
304 <!-- ##### STRUCT GPollFD ##### -->
307 <informaltable pgwide=1 frame="none" role="struct">
308 <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
312 <entry>#gint fd;</entry>
313 <entry>the file descriptor to poll (or a HANDLE on Win32 platforms).</entry>
317 <entry>#gushort events;</entry>
318 <entry>a bitwise combination of flags from #GIOCondition, specifying which
319 events should be polled for. Typically for reading from a file descriptor
320 you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use
321 %G_IO_OUT | %G_IO_ERR.
326 <entry>#gushort revents;</entry>
327 <entry>a bitwise combination of flags from #GIOCondition, returned from the
328 poll() function to indicate which events occurred.
331 </tbody></tgroup></informaltable>
339 <!-- ##### STRUCT GSourceFuncs ##### -->
341 The #GSourceFuncs struct contains a table of functions used to handle
342 event sources in a generic manner.
344 <informaltable pgwide=1 frame="none" role="struct">
345 <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
349 <entry>prepare</entry>
351 Called before all the file descriptors are polled.
352 If the source can determine that it is ready here (without waiting for the
353 results of the poll() call) it should return %TRUE.
354 It can also return a @timeout value which should be the maximum timeout
355 (in milliseconds) which should be passed to the poll() call.
356 The actual timeout used will be -1 if all sources returned -1, or it will
357 be the minimum of all the @timeout values returned which were >= 0.
364 Called after all the file descriptors are polled.
365 The source should return %TRUE if it is ready to be dispatched.
366 Note that some time may have passed since the previous prepare function was
367 called, so the source should be checked again here.
372 <entry>dispatch</entry>
374 Called to dispatch the event source, after it has returned %TRUE in
375 either its @prepare or its @check function. The @dispatch function is
376 passed in a callback function and data. The callback function may be
377 %NULL if the source was never connected using g_source_connect(). The
378 @dispatch function should call the callback function with data and
379 whatever additional parameters are needed for this type of event source.
384 <entry>destroy</entry>
386 Called when the source is destroyed.
389 </tbody></tgroup></informaltable>
393 For idle sources, the prepare and check functions always return TRUE to
394 indicate that the source is always ready to be processed.
395 The prepare function also returns a timeout value of 0 to ensure that the
396 poll() call doesn't block (since that would be time wasted which could have
397 been spent running the idle function).
400 For timeout sources, the prepare and check functions both return TRUE if the
401 timeout interval has expired.
402 The prepare function also returns a timeout value to ensure that the poll()
403 call doesn't block too long and miss the next timeout.
406 For file descriptor sources, the prepare function typically returns FALSE,
407 since it must wait until poll() has been called before it knows whether any
408 events need to be processed. It sets the returned timeout to -1 to indicate
409 that it doesn't mind how long the poll() call blocks.
410 In the check function, it tests the results of the poll() call to see if
411 the required condition has been met, and returns TRUE if so.
419 <!-- ##### FUNCTION g_source_add ##### -->
430 <!-- # Unused Parameters # -->
435 <!-- ##### USER_FUNCTION GSourceFunc ##### -->
437 Specifies the type of function passed to g_timeout_add(), g_timeout_add_full(),
438 g_idle_add(), and g_idle_add_full().
441 @data: data passed to the function, set when the source was created with one
442 of the above functions.
443 @Returns: it should return FALSE if the source should be removed.
446 <!-- ##### FUNCTION g_source_remove ##### -->
454 <!-- ##### FUNCTION g_source_remove_by_funcs_user_data ##### -->
463 <!-- ##### FUNCTION g_source_remove_by_user_data ##### -->
474 sgml-parent-document: ("../glib-docs.sgml" "book" "refsect2" "")