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_attach().
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 to it 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_loop_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_loop_quit() to exit the main loop, and g_main_loop_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 some of these functions, e.g. gtk_main(),
50 gtk_main_quit() and gtk_events_pending().
53 <title>Creating new sources types</title>
55 One of the unusual features of the GTK+ main loop functionality
56 is that new types of event source can be created and used in
57 addition to the builtin type of event source. A new event source
58 type is used for handling GDK events. A new source type is
59 created by <firstterm>deriving</firstterm> from the #GSource
60 structure. The derived type of source is represented by a
61 structure that has the #GSource structure as a first element,
62 and other elements specific to the new source type. To create
63 an instance of the new source type, call g_source_new() passing
64 in the size of the derived structure and a table of functions.
65 These #GSourceFuncs determine the behavior of the new source
69 New source types basically interact with with the main context
70 in two ways. Their prepare function in #GSourceFuncs can set
71 a timeout to determine the maximum amount of time that the
72 main loop will sleep before checking the source again. In
73 addition, or as well, the source can add file descriptors to
74 the set that the main context checks using g_source_add_poll().
78 <title>Customizing the main loop iteration</title>
80 Single iterations of a #GMainContext can be run with
81 g_main_context_iteration(). In some cases, more detailed control
82 of exactly how the details of the main loop work is desired,
83 for instance, when integrating the #GMainLoop with an external
84 main loop. In such cases, you can call the component functions
85 of g_main_context_iteration() directly. These functions
86 are g_main_context_prepare(), g_main_context_query(),
87 g_main_context_check() and g_main_context_dispatch().
90 The operation of these functions can best be seen in terms
91 of a state diagram, as shown in <xref linkend="mainloop-states"/>.
93 <figure id="mainloop-states">
94 <title>States of a Main Context</title>
95 <graphic fileref="mainloop-states.gif" format="GIF"></graphic>
99 <!-- ##### SECTION See_Also ##### -->
104 <!-- ##### SECTION Stability_Level ##### -->
107 <!-- ##### STRUCT GMainLoop ##### -->
109 The <structname>GMainLoop</structname> struct is an opaque data type
110 representing the main event loop of a GLib or GTK+ application.
114 <!-- ##### FUNCTION g_main_loop_new ##### -->
124 <!-- ##### FUNCTION g_main_loop_ref ##### -->
133 <!-- ##### FUNCTION g_main_loop_unref ##### -->
141 <!-- ##### FUNCTION g_main_loop_run ##### -->
149 <!-- ##### FUNCTION g_main_loop_quit ##### -->
157 <!-- ##### FUNCTION g_main_loop_is_running ##### -->
166 <!-- ##### FUNCTION g_main_loop_get_context ##### -->
175 <!-- ##### MACRO g_main_new ##### -->
177 Creates a new #GMainLoop for the default main loop.
180 @is_running: set to %TRUE to indicate that the loop is running. This is not
181 very important since calling g_main_run() will set this to %TRUE anyway.
182 @Returns: a new #GMainLoop.
183 @Deprecated: Use g_main_loop_new() instead.
186 <!-- ##### MACRO g_main_destroy ##### -->
188 Frees the memory allocated for the #GMainLoop.
192 @Deprecated: Use g_main_loop_unref() instead.
195 <!-- ##### MACRO g_main_run ##### -->
197 Runs a main loop until it stops running.
201 @Deprecated: Use g_main_loop_run() instead.
204 <!-- ##### MACRO g_main_quit ##### -->
206 Stops the #GMainLoop. If g_main_run() was called to run the #GMainLoop,
211 @Deprecated: Use g_main_loop_quit() instead.
214 <!-- ##### MACRO g_main_is_running ##### -->
216 Checks if the main loop is running.
220 @Returns: %TRUE if the main loop is running.
221 @Deprecated: USe g_main_loop_is_running() instead.
224 <!-- ##### MACRO G_PRIORITY_HIGH ##### -->
226 Use this for high priority event sources.
227 It is not used within GLib or GTK+.
232 <!-- ##### MACRO G_PRIORITY_DEFAULT ##### -->
234 Use this for default priority event sources.
235 In GLib this priority is used when adding timeout functions with
237 In GDK this priority is used for events from the X server.
242 <!-- ##### MACRO G_PRIORITY_HIGH_IDLE ##### -->
244 Use this for high priority idle functions.
245 GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, and
246 #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is done to
247 ensure that any pending resizes are processed before any pending redraws,
248 so that widgets are not redrawn twice unnecessarily.)
253 <!-- ##### MACRO G_PRIORITY_DEFAULT_IDLE ##### -->
255 Use this for default priority idle functions.
256 In GLib this priority is used when adding idle functions with g_idle_add().
261 <!-- ##### MACRO G_PRIORITY_LOW ##### -->
263 Use this for very low priority background tasks.
264 It is not used within GLib or GTK+.
269 <!-- ##### STRUCT GMainContext ##### -->
271 The <structname>GMainContext</structname> struct is an opaque data type
272 representing a set of sources to be handled in a main loop.
276 <!-- ##### FUNCTION g_main_context_new ##### -->
284 <!-- ##### FUNCTION g_main_context_ref ##### -->
293 <!-- ##### FUNCTION g_main_context_unref ##### -->
301 <!-- ##### FUNCTION g_main_context_default ##### -->
309 <!-- ##### FUNCTION g_main_context_iteration ##### -->
319 <!-- ##### MACRO g_main_iteration ##### -->
321 Runs a single iteration for the default #GMainContext.
324 @may_block: set to %TRUE if it should block (i.e. wait) until an event source
325 becomes ready. It will return after an event source has been processed.
326 If set to %FALSE it will return immediately if no event source is ready to be
328 @Returns: %TRUE if more events are pending.
329 @Deprecated: Use g_main_context_iteration() instead.
332 <!-- ##### FUNCTION g_main_context_pending ##### -->
341 <!-- ##### MACRO g_main_pending ##### -->
343 Checks if any events are pending for the default #GMainContext
344 (i.e. ready to be processed).
347 @Returns: %TRUE if any events are pending.
348 @Deprecated: Use g_main_context_pending() instead.
351 <!-- ##### FUNCTION g_main_context_find_source_by_id ##### -->
359 <!-- # Unused Parameters # -->
363 <!-- ##### FUNCTION g_main_context_find_source_by_user_data ##### -->
373 <!-- ##### FUNCTION g_main_context_find_source_by_funcs_user_data ##### -->
384 <!-- ##### FUNCTION g_main_context_wakeup ##### -->
392 <!-- ##### FUNCTION g_main_context_acquire ##### -->
401 <!-- ##### FUNCTION g_main_context_release ##### -->
409 <!-- ##### FUNCTION g_main_context_wait ##### -->
420 <!-- ##### FUNCTION g_main_context_prepare ##### -->
430 <!-- ##### FUNCTION g_main_context_query ##### -->
443 <!-- ##### FUNCTION g_main_context_check ##### -->
455 <!-- ##### FUNCTION g_main_context_dispatch ##### -->
463 <!-- ##### FUNCTION g_main_context_set_poll_func ##### -->
472 <!-- ##### FUNCTION g_main_context_get_poll_func ##### -->
481 <!-- ##### USER_FUNCTION GPollFunc ##### -->
483 Specifies the type of function passed to g_main_context_set_poll_func().
484 The semantics of the function should match those of the
485 <function>poll()</function> system call.
488 @ufds: an array of #GPollFD elements.
489 @nfsd: the number of elements in @ufds.
490 @timeout_: the maximum time to wait for an event of the file descriptors.
491 A negative value indicates an infinite timeout.
492 @Returns: the number of #GPollFD elements which have events or errors reported,
493 or -1 if an error occurred.
496 <!-- ##### FUNCTION g_main_context_add_poll ##### -->
506 <!-- ##### FUNCTION g_main_context_remove_poll ##### -->
515 <!-- ##### FUNCTION g_main_depth ##### -->
523 <!-- ##### MACRO g_main_set_poll_func ##### -->
525 Sets the function to use for the handle polling of file descriptors
526 for the default main context.
529 @func: the function to call to poll all file descriptors.
530 @Deprecated: Use g_main_context_set_poll_func() instead.
533 <!-- ##### FUNCTION g_timeout_source_new ##### -->
542 <!-- ##### FUNCTION g_timeout_add ##### -->
552 <!-- ##### FUNCTION g_timeout_add_full ##### -->
564 <!-- ##### FUNCTION g_idle_source_new ##### -->
572 <!-- ##### FUNCTION g_idle_add ##### -->
581 <!-- ##### FUNCTION g_idle_add_full ##### -->
592 <!-- ##### FUNCTION g_idle_remove_by_data ##### -->
600 <!-- ##### TYPEDEF GPid ##### -->
602 A type which is used to hold a process identification.
603 On Unix, processes are identified by a process id (an
604 integer), while Windows uses process handles (which are
609 <!-- ##### USER_FUNCTION GChildWatchFunc ##### -->
611 The type of functions to be called when a child exists.
614 @pid: the process id of the child process
615 @status: Status information about the child process,
616 see waitpid(2) for more information about this field
617 @data: user data passed to g_child_watch_add()
620 <!-- ##### FUNCTION g_child_watch_source_new ##### -->
629 <!-- ##### FUNCTION g_child_watch_add ##### -->
640 <!-- ##### FUNCTION g_child_watch_add_full ##### -->
653 <!-- ##### STRUCT GPollFD ##### -->
656 <informaltable pgwide="1" frame="none" role="struct">
657 <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
661 <entry>#gint fd;</entry>
662 <entry>the file descriptor to poll (or a <type>HANDLE</type> on Win32 platforms).</entry>
666 <entry>#gushort events;</entry>
667 <entry>a bitwise combination of flags from #GIOCondition, specifying which
668 events should be polled for. Typically for reading from a file descriptor
669 you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use
670 %G_IO_OUT | %G_IO_ERR.
675 <entry>#gushort revents;</entry>
676 <entry>a bitwise combination of flags from #GIOCondition, returned from the
677 <function>poll()</function> function to indicate which events occurred.
680 </tbody></tgroup></informaltable>
688 <!-- ##### STRUCT GSource ##### -->
690 The <structname>GSource</structname> struct is an opaque data type representing
695 <!-- ##### USER_FUNCTION GSourceDummyMarshal ##### -->
697 This is just a placeholder for #GClosureMarshal, which cannot be used here
698 for dependency reasons.
703 <!-- ##### STRUCT GSourceFuncs ##### -->
705 The #GSourceFuncs struct contains a table of functions used to handle
706 event sources in a generic manner.
708 <informaltable pgwide="1" frame="none" role="struct">
709 <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
713 <entry>prepare</entry>
715 Called before all the file descriptors are polled.
716 If the source can determine that it is ready here (without waiting for the
717 results of the <function>poll()</function> call) it should return %TRUE.
718 It can also return a @timeout_ value which should be the maximum timeout
719 (in milliseconds) which should be passed to the <function>poll()</function> call.
720 The actual timeout used will be -1 if all sources returned -1, or it will
721 be the minimum of all the @timeout_ values returned which were >= 0.
728 Called after all the file descriptors are polled.
729 The source should return %TRUE if it is ready to be dispatched.
730 Note that some time may have passed since the previous prepare function was
731 called, so the source should be checked again here.
736 <entry>dispatch</entry>
738 Called to dispatch the event source, after it has returned %TRUE in
739 either its @prepare or its @check function. The @dispatch function is
740 passed in a callback function and data. The callback function may be
741 %NULL if the source was never connected to a callback using
742 g_source_set_callback(). The @dispatch function should call the
743 callback function with @user_data and whatever additional parameters are
744 needed for this type of event source.
749 <entry>finalize</entry>
751 Called when the source is finalized.
754 </tbody></tgroup></informaltable>
758 For idle sources, the prepare and check functions always return %TRUE to
759 indicate that the source is always ready to be processed.
760 The prepare function also returns a timeout value of 0 to ensure that the
761 <function>poll()</function> call doesn't block (since that would be time
762 wasted which could have been spent running the idle function).
765 For timeout sources, the prepare and check functions both return %TRUE if the
766 timeout interval has expired. The prepare function also returns a timeout
767 value to ensure that the <function>poll()</function> call doesn't block too
768 long and miss the next timeout.
771 For file descriptor sources, the prepare function typically returns %FALSE,
772 since it must wait until <function>poll()</function> has been called before
773 it knows whether any events need to be processed. It sets the returned
774 timeout to -1 to indicate that it doesn't mind how long the
775 <function>poll()</function> call blocks.
776 In the check function, it tests the results of the <function>poll()</function>
777 call to see if the required condition has been met, and returns %TRUE if so.
787 <!-- ##### STRUCT GSourceCallbackFuncs ##### -->
789 The <structname>GSourceCallbackFuncs</structname> struct contains
790 functions for managing callback objects.
793 @ref: Called when a reference is added to the callback object.
794 @unref: Called when a reference to the callback object is dropped.
795 @get: Called to extract the callback function and data from the callback object.
797 <!-- ##### FUNCTION g_source_new ##### -->
807 <!-- ##### FUNCTION g_source_ref ##### -->
816 <!-- ##### FUNCTION g_source_unref ##### -->
824 <!-- ##### FUNCTION g_source_attach ##### -->
834 <!-- ##### FUNCTION g_source_destroy ##### -->
842 <!-- ##### FUNCTION g_source_set_priority ##### -->
851 <!-- ##### FUNCTION g_source_get_priority ##### -->
860 <!-- ##### FUNCTION g_source_set_can_recurse ##### -->
869 <!-- ##### FUNCTION g_source_get_can_recurse ##### -->
878 <!-- ##### FUNCTION g_source_get_id ##### -->
887 <!-- ##### FUNCTION g_source_get_context ##### -->
896 <!-- ##### FUNCTION g_source_set_callback ##### -->
907 <!-- ##### USER_FUNCTION GSourceFunc ##### -->
909 Specifies the type of function passed to g_timeout_add(), g_timeout_add_full(),
910 g_idle_add(), and g_idle_add_full().
913 @data: data passed to the function, set when the source was created with one
914 of the above functions.
915 @Returns: it should return %FALSE if the source should be removed.
918 <!-- ##### FUNCTION g_source_set_callback_indirect ##### -->
928 <!-- ##### FUNCTION g_source_add_poll ##### -->
937 <!-- ##### FUNCTION g_source_remove_poll ##### -->
946 <!-- ##### FUNCTION g_source_get_current_time ##### -->
955 <!-- ##### FUNCTION g_source_remove ##### -->
963 <!-- ##### FUNCTION g_source_remove_by_funcs_user_data ##### -->
972 <!-- ##### FUNCTION g_source_remove_by_user_data ##### -->
982 sgml-parent-document: ("../glib-docs.sgml" "book" "refsect2" "")