--- /dev/null
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: mainloop-stages.eps
+%%Creator: fig2dev Version 3.2 Patchlevel 3c
+%%CreationDate: Wed Nov 29 12:23:52 2000
+%%For: otaylor@fresnel.labs.redhat.com (Owen Taylor)
+%%BoundingBox: 0 0 503 291
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+newpath 0 291 moveto 0 0 lineto 503 0 lineto 503 291 lineto closepath clip newpath
+-106.0 402.0 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+ 4 -2 roll dup 1 exch sub 3 -1 roll mul add
+ 4 -2 roll dup 1 exch sub 3 -1 roll mul add
+ 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+ bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+ 4 -2 roll mul srgb} bind def
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+$F2psBegin
+%%Page: 1 1
+10 setmiterlimit
+ 0.06000 0.06000 sc
+%
+% Fig objects follow
+%
+/Times-Roman ff 270.00 scf sf
+9300 6225 m
+gs 1 -1 sc (Initial[n+1]) dup sw pop 2 div neg 0 rm col0 sh gr
+/Times-Roman ff 270.00 scf sf
+9300 6540 m
+gs 1 -1 sc (\(Recursion\)) dup sw pop 2 div neg 0 rm col0 sh gr
+% Polyline
+15.000 slw
+ [60] 0 sd
+n 1905 6000 m 1800 6000 1800 6420 105 arcto 4 {pop} repeat
+ 1800 6525 3120 6525 105 arcto 4 {pop} repeat
+ 3225 6525 3225 6105 105 arcto 4 {pop} repeat
+ 3225 6000 1905 6000 105 arcto 4 {pop} repeat
+ cp gs col0 s gr [] 0 sd
+% Polyline
+ [60] 0 sd
+gs clippath
+3865 5498 m 3806 5431 l 3688 5535 l 3808 5490 l 3747 5602 l cp
+3184 5976 m 3243 6043 l 3361 5939 l 3242 5985 l 3302 5872 l cp
+eoclip
+n 3225 6000 m
+ 3825 5475 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+n 3302 5872 m 3242 5985 l 3361 5939 l 3302 5872 l cp gs 0.00 setgray ef gr col0 s
+% arrowhead
+n 3747 5602 m 3808 5490 l 3688 5535 l 3747 5602 l cp gs 0.00 setgray ef gr col0 s
+% Polyline
+n 4980 5775 m 4875 5775 4875 6270 105 arcto 4 {pop} repeat
+ 4875 6375 6870 6375 105 arcto 4 {pop} repeat
+ 6975 6375 6975 5880 105 arcto 4 {pop} repeat
+ 6975 5775 4980 5775 105 arcto 4 {pop} repeat
+ cp gs col0 s gr
+% Polyline
+ [60] 0 sd
+gs clippath
+8457 5969 m 8515 5900 l 8394 5799 l 8458 5911 l 8337 5868 l cp
+8042 5505 m 7984 5574 l 8105 5675 l 8042 5564 l 8162 5606 l cp
+eoclip
+n 8025 5550 m
+ 8475 5925 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+n 8162 5606 m 8042 5564 l 8105 5675 l 8162 5606 l cp gs 0.00 setgray ef gr col0 s
+% arrowhead
+n 8337 5868 m 8458 5911 l 8394 5799 l 8337 5868 l cp gs 0.00 setgray ef gr col0 s
+% Polyline
+ [60] 0 sd
+n 8580 5850 m 8475 5850 8475 6570 105 arcto 4 {pop} repeat
+ 8475 6675 10020 6675 105 arcto 4 {pop} repeat
+ 10125 6675 10125 5955 105 arcto 4 {pop} repeat
+ 10125 5850 8580 5850 105 arcto 4 {pop} repeat
+ cp gs col0 s gr [] 0 sd
+% Polyline
+n 7155 3825 m 7050 3825 7050 4320 105 arcto 4 {pop} repeat
+ 7050 4425 9045 4425 105 arcto 4 {pop} repeat
+ 9150 4425 9150 3930 105 arcto 4 {pop} repeat
+ 9150 3825 7155 3825 105 arcto 4 {pop} repeat
+ cp gs col0 s gr
+% Polyline
+n 5055 2100 m 4950 2100 4950 2595 105 arcto 4 {pop} repeat
+ 4950 2700 6945 2700 105 arcto 4 {pop} repeat
+ 7050 2700 7050 2205 105 arcto 4 {pop} repeat
+ 7050 2100 5055 2100 105 arcto 4 {pop} repeat
+ cp gs col0 s gr
+% Polyline
+n 2730 3900 m 2625 3900 2625 4395 105 arcto 4 {pop} repeat
+ 2625 4500 4620 4500 105 arcto 4 {pop} repeat
+ 4725 4500 4725 4005 105 arcto 4 {pop} repeat
+ 4725 3900 2730 3900 105 arcto 4 {pop} repeat
+ cp gs col0 s gr
+% Polyline
+ [60] 0 sd
+n 8580 1875 m 8475 1875 8475 2295 105 arcto 4 {pop} repeat
+ 8475 2400 9645 2400 105 arcto 4 {pop} repeat
+ 9750 2400 9750 1980 105 arcto 4 {pop} repeat
+ 9750 1875 8580 1875 105 arcto 4 {pop} repeat
+ cp gs col0 s gr [] 0 sd
+% Polyline
+ [60] 0 sd
+gs clippath
+8518 2419 m 8451 2358 l 8345 2474 l 8460 2416 l 8412 2534 l cp
+8003 2848 m 8070 2909 l 8176 2793 l 8062 2852 l 8109 2733 l cp
+eoclip
+n 8047 2868 m
+ 8475 2400 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+n 8109 2733 m 8062 2852 l 8176 2793 l 8109 2733 l cp gs 0.00 setgray ef gr col0 s
+% arrowhead
+n 8412 2534 m 8460 2416 l 8345 2474 l 8412 2534 l cp gs 0.00 setgray ef gr col0 s
+% Polyline
+2 slj
+gs clippath
+3340 4475 m 3252 4494 l 3286 4648 l 3305 4522 l 3374 4629 l cp
+eoclip
+n 4875 6075 m 4874 6075 l 4872 6074 l 4868 6073 l 4861 6072 l 4852 6070 l
+ 4839 6067 l 4824 6064 l 4805 6059 l 4783 6054 l 4759 6048 l
+ 4731 6041 l 4701 6033 l 4669 6025 l 4635 6015 l 4600 6004 l
+ 4563 5993 l 4526 5981 l 4487 5967 l 4448 5953 l 4408 5937 l
+ 4367 5920 l 4326 5901 l 4284 5881 l 4241 5859 l 4198 5835 l
+ 4154 5809 l 4109 5781 l 4063 5749 l 4016 5715 l 3968 5678 l
+ 3920 5638 l 3872 5595 l 3825 5550 l 3780 5503 l 3737 5455 l
+ 3697 5407 l 3660 5359 l 3626 5312 l 3594 5266 l 3566 5221 l
+ 3540 5177 l 3516 5134 l 3494 5091 l 3474 5049 l 3455 5008 l
+ 3438 4967 l 3422 4927 l 3408 4888 l 3394 4849 l 3382 4812 l
+ 3371 4775 l 3360 4740 l 3350 4706 l 3342 4674 l 3334 4644 l
+ 3327 4616 l 3321 4592 l 3316 4570 l 3311 4551 l 3308 4536 l
+ 3305 4523 l 3303 4514 l
+ 3300 4500 l gs col0 s gr gr
+
+% arrowhead
+0 slj
+n 3374 4629 m 3305 4522 l 3286 4648 l 3374 4629 l cp gs 0.00 setgray ef gr col0 s
+% Polyline
+2 slj
+gs clippath
+6943 6114 m 6978 6197 l 7123 6135 l 6995 6141 l 7087 6052 l cp
+eoclip
+n 8475 4500 m 8475 4501 l 8475 4503 l 8475 4508 l 8475 4515 l 8474 4525 l
+ 8474 4538 l 8473 4553 l 8472 4573 l 8470 4594 l 8468 4619 l
+ 8465 4646 l 8462 4675 l 8457 4706 l 8452 4739 l 8445 4773 l
+ 8437 4808 l 8427 4845 l 8416 4882 l 8403 4921 l 8388 4961 l
+ 8370 5002 l 8350 5045 l 8326 5090 l 8299 5137 l 8268 5186 l
+ 8232 5237 l 8192 5290 l 8148 5345 l 8100 5400 l 8057 5445 l
+ 8013 5490 l 7968 5533 l 7923 5573 l 7878 5612 l 7833 5649 l
+ 7789 5684 l 7745 5717 l 7701 5749 l 7658 5779 l 7615 5807 l
+ 7573 5834 l 7531 5861 l 7489 5886 l 7447 5910 l 7407 5933 l
+ 7366 5955 l 7327 5977 l 7288 5997 l 7250 6017 l 7214 6035 l
+ 7180 6052 l 7147 6068 l 7117 6083 l 7090 6096 l 7065 6108 l
+ 7043 6118 l 7025 6127 l 7010 6134 l 6998 6140 l 6989 6144 l
+
+ 6975 6150 l gs col0 s gr gr
+
+% arrowhead
+0 slj
+n 7087 6052 m 6995 6141 l 7123 6135 l 7087 6052 l cp gs 0.00 setgray ef gr col0 s
+% Polyline
+2 slj
+gs clippath
+8433 3848 m 8521 3831 l 8493 3676 l 8471 3803 l 8404 3693 l cp
+eoclip
+n 7050 2400 m 7051 2400 l 7054 2401 l 7058 2401 l 7066 2403 l 7076 2404 l
+ 7090 2407 l 7107 2410 l 7127 2414 l 7150 2418 l 7177 2424 l
+ 7206 2430 l 7238 2437 l 7271 2445 l 7306 2454 l 7343 2463 l
+ 7381 2474 l 7419 2486 l 7458 2499 l 7498 2513 l 7538 2528 l
+ 7579 2545 l 7621 2564 l 7663 2585 l 7706 2608 l 7750 2634 l
+ 7795 2662 l 7841 2694 l 7887 2728 l 7933 2766 l 7980 2807 l
+ 8025 2850 l 8068 2895 l 8109 2942 l 8147 2988 l 8181 3034 l
+ 8213 3080 l 8241 3125 l 8267 3169 l 8290 3212 l 8311 3254 l
+ 8330 3296 l 8347 3337 l 8362 3377 l 8376 3417 l 8389 3456 l
+ 8401 3494 l 8412 3532 l 8421 3569 l 8430 3604 l 8438 3637 l
+ 8445 3669 l 8451 3698 l 8457 3725 l 8461 3748 l 8465 3768 l
+ 8468 3785 l 8471 3799 l 8472 3809 l
+ 8475 3825 l gs col0 s gr gr
+
+% arrowhead
+0 slj
+n 8404 3693 m 8471 3803 l 8493 3676 l 8404 3693 l cp gs 0.00 setgray ef gr col0 s
+% Polyline
+2 slj
+gs clippath
+4970 2442 m 4959 2353 l 4803 2372 l 4928 2403 l 4814 2461 l cp
+eoclip
+n 3375 3900 m 3375 3899 l 3376 3897 l 3377 3892 l 3378 3886 l 3380 3876 l
+ 3383 3863 l 3386 3848 l 3391 3828 l 3396 3806 l 3402 3781 l
+ 3409 3753 l 3417 3722 l 3425 3689 l 3435 3655 l 3446 3619 l
+ 3457 3581 l 3469 3543 l 3483 3504 l 3497 3464 l 3513 3423 l
+ 3530 3383 l 3549 3341 l 3569 3299 l 3591 3257 l 3615 3214 l
+ 3641 3170 l 3669 3125 l 3701 3080 l 3735 3034 l 3772 2988 l
+ 3812 2941 l 3855 2895 l 3900 2850 l 3950 2804 l 4001 2762 l
+ 4052 2723 l 4102 2687 l 4152 2655 l 4201 2625 l 4248 2599 l
+ 4295 2576 l 4340 2555 l 4385 2536 l 4429 2519 l 4472 2504 l
+ 4515 2490 l 4557 2477 l 4598 2466 l 4638 2456 l 4677 2447 l
+ 4715 2439 l 4751 2432 l 4784 2426 l 4815 2420 l 4843 2415 l
+ 4868 2411 l 4890 2408 l 4908 2406 l 4922 2404 l 4933 2402 l
+
+ 4950 2400 l gs col0 s gr gr
+
+% arrowhead
+0 slj
+n 4814 2461 m 4928 2403 l 4803 2372 l 4814 2461 l cp gs 0.00 setgray ef gr col0 s
+/Times-Roman ff 360.00 scf sf
+5925 6225 m
+gs 1 -1 sc (Initial[n]) dup sw pop 2 div neg 0 rm col0 sh gr
+/Times-Roman ff 360.00 scf sf
+8100 4275 m
+gs 1 -1 sc (Dispatching) dup sw pop 2 div neg 0 rm col0 sh gr
+/Times-Roman ff 360.00 scf sf
+3675 4350 m
+gs 1 -1 sc (Prepared) dup sw pop 2 div neg 0 rm col0 sh gr
+/Times-Roman ff 360.00 scf sf
+5925 2550 m
+gs 1 -1 sc (Polling) dup sw pop 2 div neg 0 rm col0 sh gr
+/Times-Roman ff 270.00 scf sf
+4050 3300 m
+gs 1 -1 sc (query\(\)) col0 sh gr
+/Times-Roman ff 270.00 scf sf
+7800 3225 m
+gs 1 -1 sc (check\(\)) dup sw pop neg 0 rm col0 sh gr
+/Times-Roman ff 270.00 scf sf
+2475 6375 m
+gs 1 -1 sc (Working) dup sw pop 2 div neg 0 rm col0 sh gr
+/Times-Roman ff 270.00 scf sf
+3900 5400 m
+gs 1 -1 sc (prepare\(\)) col0 sh gr
+/Times-Roman ff 270.00 scf sf
+8025 5325 m
+gs 1 -1 sc (dispatch\(\)) dup sw pop neg 0 rm col0 sh gr
+/Times-Roman ff 270.00 scf sf
+9150 2250 m
+gs 1 -1 sc (Working) dup sw pop 2 div neg 0 rm col0 sh gr
+$F2psEnd
+rs
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 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_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_quit() to exit the main loop, and g_main_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 elemeent,
+ 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>
-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>
-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_new(). After adding the initial event
-sources, g_main_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_quit() to exit the main loop, and g_main_run() returns.
+
</para>
+
+<!-- ##### STRUCT GMainLoop ##### -->
<para>
-It is possible to create new instances of #GMainLoop recursively.
-This is often used in GTK+ applications when showing modal dialog boxes.
-However, all event sources are global; they are not tied to a particular
-#GMainLoop.
+The #GMainLoop struct is an opaque data type representing the main event loop
+of a GLib or GTK+ application.
</para>
+
+
+<!-- ##### FUNCTION g_main_loop_new ##### -->
<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().
-In a GTK+ application, these wrapper functions should be used instead.
+
</para>
-<!-- ##### SECTION See_Also ##### -->
+@context:
+@is_running:
+@Returns:
+
+
+<!-- ##### FUNCTION g_main_loop_destroy ##### -->
<para>
</para>
-<!-- ##### STRUCT GMainLoop ##### -->
+@loop:
+
+
+<!-- ##### FUNCTION g_main_loop_run ##### -->
<para>
-The #GMainLoop struct is an opaque data type representing the main event loop
-of a GLib or GTK+ application.
+
</para>
+@loop:
-<!-- ##### FUNCTION g_main_new ##### -->
+
+<!-- ##### FUNCTION g_main_loop_quit ##### -->
<para>
-Creates a new #GMainLoop.
+
</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.
+@loop:
-<!-- ##### FUNCTION g_main_destroy ##### -->
+<!-- ##### FUNCTION g_main_loop_is_running ##### -->
<para>
-Frees the memory allocated for the #GMainLoop.
+
</para>
-@loop: a #GMainLoop.
+@loop:
+@Returns:
-<!-- ##### FUNCTION g_main_run ##### -->
+<!-- ##### MACRO g_main_new ##### -->
<para>
-Runs a main loop until it stops running, which occurs when g_main_quit()
-is called.
+Creates a new #GMainLoop for the default main loop. A compatibility
+macro, see g_main_loop_new().
</para>
-@loop: a #GMainLoop.
+@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.
-<!-- ##### FUNCTION g_main_is_running ##### -->
+<!-- ##### MACRO g_main_destroy ##### -->
<para>
-Returns TRUE if the main loop is running.
+Frees the memory allocated for the #GMainLoop. A compatibility macro, see
+g_main_loop_destroy().
</para>
@loop: a #GMainLoop.
-@Returns: TRUE if the main loop is running.
-<!-- ##### FUNCTION g_main_pending ##### -->
+<!-- ##### MACRO g_main_run ##### -->
<para>
-Returns TRUE if any events are pending (i.e. ready to be processed).
+Runs a main loop until it stops running. A compatibility macro, see g_main_loop_run().
</para>
-@Returns: TRUE if any events are pending.
+@loop: a #GMainLoop.
-<!-- ##### FUNCTION g_main_iteration ##### -->
+<!-- ##### MACRO g_main_quit ##### -->
<para>
-Runs a single iteration of the main loop.
-This will check which event sources are ready to be processed, and will
-process the highest priority event sources which are ready.
+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>
-@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.
+@loop: a #GMainLoop.
-<!-- ##### FUNCTION g_main_quit ##### -->
+<!-- ##### MACRO g_main_is_running ##### -->
<para>
-Stops the #GMainLoop. If g_main_run() was called to run the #GMainLoop,
-it will now return.
+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 ##### -->
-<!-- ##### FUNCTION g_timeout_add ##### -->
+<!-- ##### STRUCT GMainContext ##### -->
<para>
-Sets a function to be called at regular intervals, with the default priority,
-#G_PRIORITY_DEFAULT.
-The function is called repeatedly until it returns FALSE, at which point
-the timeout is automatically destroyed and the function will not be called
-again.
-The first call to the function will be at the end of the first @interval.
+
</para>
+
+
+<!-- ##### FUNCTION g_main_context_get ##### -->
<para>
-Note that timeout functions may be delayed, due to the processing of other
-event sources. Thus they should not be relied on for precise timing.
-After each call to the timeout function, the time of the next
-timeout is recalculated based on the current time and the given interval
-(it does not try to 'catch up' time lost in delays).
+
</para>
-@interval: the time between calls to @function, in milliseconds (1/1000ths
-of a second.)
-@function: the function to call at each interval.
-@data: data to pass to @function.
-@Returns: the id of the event source.
+@thread:
+@Returns:
-<!-- ##### FUNCTION g_timeout_add_full ##### -->
+<!-- ##### FUNCTION g_main_context_default ##### -->
<para>
-Sets a function to be called at regular intervals, with the given priority.
-The function is called repeatedly until it returns FALSE, at which point
-the timeout is automatically destroyed and the function will not be called
-again.
-The @notify function is called when the timeout is destroyed.
-The first call to the function will be at the end of the first @interval.
+
</para>
+
+@Returns:
+
+
+<!-- ##### FUNCTION g_main_context_iteration ##### -->
<para>
-Note that timeout functions may be delayed, due to the processing of other
-event sources. Thus they should not be relied on for precise timing.
-After each call to the timeout function, the time of the next
-timeout is recalculated based on the current time and the given interval
-(it does not try to 'catch up' time lost in delays).
+
</para>
-@priority: the priority of the function. See #G_PRIORITY_DEFAULT,
-#G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH, #G_PRIORITY_HIGH_IDLE, and
-#G_PRIORITY_LOW.
-@interval: the time between calls to the function, in milliseconds (1/1000ths
-of a second.)
-@function: the function to call at each interval.
-@data: data to pass to @function (and @notify).
-@notify: the function to call when the timeout is destroyed, or NULL.
-@Returns: the id of event source.
+@context:
+@may_block:
+@Returns:
-<!-- ##### USER_FUNCTION GSourceFunc ##### -->
+<!-- ##### MACRO g_main_iteration ##### -->
<para>
-Specifies the type of function passed to g_timeout_add(), g_timeout_add_full(),
-g_idle_add(), and g_idle_add_full().
+Runs a single iteration for the default #GMainContext.
+A compatibility macro, see g_main_context_iteration().
</para>
-@data: data passed to the function, set when the source was created with one
-of the above functions.
-@Returns: it should return FALSE if the source should be removed.
+@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_idle_add ##### -->
+<!-- ##### FUNCTION g_main_context_pending ##### -->
<para>
-Adds a function to be called whenever there are no higher priority events
-pending. The function is given the default idle priority,
-#G_PRIORITY_DEFAULT_IDLE.
-If the function returns FALSE it is automatically removed from the list of
-event sources and will not be called again.
+
</para>
-@function: the function to call.
-@data: data to pass to the function.
-@Returns: the id of the event source.
+@context:
+@Returns:
-<!-- ##### FUNCTION g_idle_add_full ##### -->
+<!-- ##### MACRO g_main_pending ##### -->
<para>
-Adds a function to be called whenever there are no higher priority events
-pending.
-If the function returns FALSE it is automatically removed from the list of
-event sources and will not be called again.
+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>
-@priority: the priority of the idle function, which should be somewhere around
-#G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
-@function: the function to call.
-@data: data to pass to the function.
-@destroy: the function to call when the timeout is destroyed, or NULL.
-@Returns: the id of the event source.
+@Returns: %TRUE if any events are pending.
-<!-- ##### FUNCTION g_idle_remove_by_data ##### -->
+<!-- ##### FUNCTION g_main_context_find_source_by_id ##### -->
<para>
-Removes the idle function with the given data.
+
</para>
-@data: the data which is passed to the idle function.
-@Returns: TRUE if the idle function was found.
+@context:
+@id:
+@Returns:
-<!-- ##### FUNCTION g_main_add_poll ##### -->
+<!-- ##### FUNCTION g_main_context_find_source_by_user_data ##### -->
<para>
-Adds a file descriptor to be polled.
-This is usually combined with g_source_add() to add an event source.
-The event source's check function will typically test the revents
-field in the #GPollFD struct and return TRUE if events need to be processed.
+
</para>
-@fd: a #GPollFD, which is a file descriptor together with a bitwise
-combination of #GIOCondition flags determining which events to poll for.
-@priority: the priority of the poll, which should be the same as the priority
-used for g_source_add() to ensure that the file descriptor is polled whenever
-the results may be needed.
-See #G_PRIORITY_DEFAULT, #G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH,
-#G_PRIORITY_HIGH_IDLE, and #G_PRIORITY_LOW.
+@context:
+@user_data:
+@Returns:
-<!-- ##### STRUCT GPollFD ##### -->
+<!-- ##### FUNCTION g_main_context_find_source_by_funcs_user_data ##### -->
<para>
-<informaltable pgwide=1 frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
+</para>
-<row>
-<entry>#gint fd;</entry>
-<entry>the file descriptor to poll (or a HANDLE on Win32 platforms).</entry>
-</row>
+@context:
+@funcs:
+@user_data:
+@Returns:
+<!-- # Unused Parameters # -->
+@source_data:
-<row>
-<entry>#gushort events;</entry>
-<entry>a bitwise combination of flags from #GIOCondition, specifying which
-events should be polled for. Typically for reading from a file descriptor
-you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use
-%G_IO_OUT | %G_IO_ERR.
-</entry>
-</row>
-<row>
-<entry>#gushort revents;</entry>
-<entry>a bitwise combination of flags from #GIOCondition, returned from the
-poll() function to indicate which events occurred.
-</entry>
-</row>
-</tbody></tgroup></informaltable>
+<!-- ##### FUNCTION g_main_context_prepare ##### -->
+<para>
</para>
-@fd:
-@events:
-@revents:
+@context:
+@priority:
+@Returns:
-<!-- ##### FUNCTION g_main_remove_poll ##### -->
+
+<!-- ##### FUNCTION g_main_context_query ##### -->
<para>
-Removes a file descriptor from the list being polled.
+
</para>
-@fd: the #GPollFD to remove.
+@context:
+@max_priority:
+@timeout:
+@fds:
+@n_fds:
+@Returns:
-<!-- ##### FUNCTION g_main_set_poll_func ##### -->
+<!-- ##### FUNCTION g_main_context_check ##### -->
<para>
-Sets the function to use to handle polling of file descriptors.
-It will be used instead of the <function>poll()</function> system call
-(or GLib's replacement function, which is used where
-<function>poll()</function> isn't available).
+
</para>
+
+@context:
+@max_priority:
+@fds:
+@n_fds:
+@Returns:
+
+
+<!-- ##### FUNCTION g_main_context_dispatch ##### -->
<para>
-This function could possibly be used to integrate the GLib event loop
-with an external event loop.
+
</para>
-@func: the function to call to poll all file descriptors.
+@context:
+
+<!-- ##### FUNCTION g_main_context_set_poll_func ##### -->
+<para>
+
+</para>
-<!-- ##### FUNCTION g_main_win32_get_poll_func ##### -->
+@context:
+@func:
+
+
+<!-- ##### FUNCTION g_main_context_get_poll_func ##### -->
<para>
</para>
+@context:
@Returns:
@ufds: an array of #GPollFD elements.
@nfsd: the number of elements in @ufds.
@timeout: the maximum time to wait for an event of the file descriptors.
+ A negative value indicates an infinite timeout.
@Returns: the number of #GPollFD elements which have events or errors reported,
or -1 if an error occurred.
-<!-- ##### FUNCTION g_source_add ##### -->
+<!-- ##### FUNCTION g_main_context_add_poll ##### -->
+<para>
+
+</para>
+
+@context:
+@fd:
+@priority:
+
+
+<!-- ##### FUNCTION g_main_context_remove_poll ##### -->
+<para>
+
+</para>
+
+@context:
+@fd:
+
+
+<!-- ##### MACRO g_main_set_poll_func ##### -->
+<para>
+Sets the function to use for the handle polling of file descriptors
+for the default main context. This is a compatability macro, see
+g_main_context_set_poll_func() for full details.
+</para>
+
+@func: the function to call to poll all file descriptors.
+
+
+<!-- ##### FUNCTION g_timeout_source_new ##### -->
+<para>
+
+</para>
+
+@interval:
+@Returns:
+
+
+<!-- ##### FUNCTION g_timeout_add ##### -->
+<para>
+</para>
+
+@interval:
+@function:
+@data:
+@Returns:
+
+
+<!-- ##### FUNCTION g_timeout_add_full ##### -->
+<para>
+</para>
+
+@priority:
+@interval:
+@function:
+@data:
+@notify:
+@Returns:
+
+
+<!-- ##### FUNCTION g_idle_source_new ##### -->
<para>
-Adds an event source to the main loop.
+
</para>
-@priority: the priority of the event source. See #G_PRIORITY_DEFAULT,
-#G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH, #G_PRIORITY_HIGH_IDLE, and
-#G_PRIORITY_LOW.
-@can_recurse: if it is safe to call the source functions recursively.
-@funcs: the functions to handle the source.
-@source_data: data specific to the type of event source.
-@user_data: user data which will be passed to the user function handling the
-source.
-@notify: the function to call when the source is destroyed.
-@Returns: the id of the event source.
+@Returns:
+
+
+<!-- ##### FUNCTION g_idle_add ##### -->
+<para>
+</para>
+
+@function:
+@data:
+@Returns:
+
+
+<!-- ##### FUNCTION g_idle_add_full ##### -->
+<para>
+</para>
+
+@priority:
+@function:
+@data:
+@notify:
+@Returns:
+<!-- # Unused Parameters # -->
+@destroy:
+
+
+<!-- ##### FUNCTION g_idle_remove_by_data ##### -->
+<para>
+</para>
+
+@data:
+@Returns:
+
+
+<!-- ##### STRUCT GPollFD ##### -->
+<para>
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#gint fd;</entry>
+<entry>the file descriptor to poll (or a HANDLE on Win32 platforms).</entry>
+</row>
+
+<row>
+<entry>#gushort events;</entry>
+<entry>a bitwise combination of flags from #GIOCondition, specifying which
+events should be polled for. Typically for reading from a file descriptor
+you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use
+%G_IO_OUT | %G_IO_ERR.
+</entry>
+</row>
+
+<row>
+<entry>#gushort revents;</entry>
+<entry>a bitwise combination of flags from #GIOCondition, returned from the
+poll() function to indicate which events occurred.
+</entry>
+</row>
+</tbody></tgroup></informaltable>
+
+</para>
+
+@fd:
+@events:
+@revents:
+
+<!-- ##### STRUCT GSource ##### -->
+<para>
+
+</para>
<!-- ##### STRUCT GSourceFuncs ##### -->
<entry>
Called before all the file descriptors are polled.
If the source can determine that it is ready here (without waiting for the
-results of the poll() call) it should return TRUE.
+results of the poll() call) it should return %TRUE.
It can also return a @timeout value which should be the maximum timeout
(in milliseconds) which should be passed to the poll() call.
The actual timeout used will be -1 if all sources returned -1, or it will
<entry>check</entry>
<entry>
Called after all the file descriptors are polled.
-The source should return TRUE if it is ready to be processed.
+The source should return %TRUE if it is ready to be dispatched.
Note that some time may have passed since the previous prepare function was
called, so the source should be checked again here.
</entry>
<row>
<entry>dispatch</entry>
<entry>
-Called to process the event source, after it has returned TRUE in either
-its @prepare or its @check function.
+Called to dispatch the event source, after it has returned %TRUE in
+either its @prepare or its @check function. The @dispatch function is
+passed in a callback function and data. The callback function may be
+%NULL if the source was never connected using g_source_connect(). The
+@dispatch function should call the callback function with data and
+whatever additional parameters are needed for this type of event source.
</entry>
</row>
<row>
<entry>destroy</entry>
<entry>
-Called when the source is destroyed. It will be called with the user data
-parameter passed to the g_source_add() and related functions.
+Called when the source is destroyed.
</entry>
</row>
</tbody></tgroup></informaltable>
@dispatch:
@destroy:
-<!-- ##### FUNCTION g_source_remove ##### -->
+<!-- ##### STRUCT GSourceCallbackFuncs ##### -->
<para>
-Removes the event source with the given id.
-The id is returned when the source is created, either directly with
-g_source_add(), or indirectly with g_idle_add(), g_idle_add_full(),
-g_timeout_add() and g_timeout_add_full().
+
</para>
-@tag: the id of the event source to remove.
-@Returns: TRUE if the source was found and removed.
+@ref:
+@unref:
+@get:
+<!-- ##### FUNCTION g_source_new ##### -->
+<para>
-<!-- ##### FUNCTION g_source_remove_by_funcs_user_data ##### -->
+</para>
+
+@source_funcs:
+@struct_size:
+@Returns:
+
+
+<!-- ##### FUNCTION g_source_ref ##### -->
+<para>
+
+</para>
+
+@source:
+@Returns:
+
+
+<!-- ##### FUNCTION g_source_unref ##### -->
<para>
-Removes the first event source found with the given #GSourceFuncs and user
-data.
+
</para>
+
+@source:
+
+
+<!-- ##### FUNCTION g_source_add ##### -->
<para>
-Event sources are sorted with the highest priority first. Sources with equal
-priority are stored in the order in which they were added.
</para>
-@funcs: the #GSourceFuncs of the source to remove.
-@user_data: the user data of the source to remove.
-@Returns: TRUE if an event source was found and removed.
+@source:
+@context:
+@Returns:
-<!-- ##### FUNCTION g_source_remove_by_source_data ##### -->
+<!-- ##### FUNCTION g_source_destroy ##### -->
<para>
-Removes the first event source found with the given source data.
+
</para>
+
+@source:
+
+
+<!-- ##### FUNCTION g_source_set_priority ##### -->
<para>
-Event sources are sorted with the highest priority first. Sources with equal
-priority are stored in the order in which they were added.
+
</para>
-@source_data: the source data, which contains information specific to the
-type of source.
-@Returns: TRUE if an event source was found and removed.
+@source:
+@priority:
-<!-- ##### FUNCTION g_source_remove_by_user_data ##### -->
+<!-- ##### FUNCTION g_source_get_priority ##### -->
<para>
-Removes the first event source found with the given user data.
+
</para>
+
+@source:
+@Returns:
+
+
+<!-- ##### FUNCTION g_source_set_can_recurse ##### -->
<para>
-Event sources are sorted with the highest priority first. Sources with equal
-priority are stored in the order in which they were added.
+
</para>
-@user_data: the user data of the source to remove.
-@Returns: TRUE if an event source was found and removed.
+@source:
+@can_recurse:
+
+
+<!-- ##### FUNCTION g_source_get_can_recurse ##### -->
+<para>
+
+</para>
+
+@source:
+@Returns:
+
+
+<!-- ##### FUNCTION g_source_get_id ##### -->
+<para>
+
+</para>
+
+@source:
+@Returns:
+
+
+<!-- ##### FUNCTION g_source_get_context ##### -->
+<para>
+
+</para>
+
+@source:
+@Returns:
+
+
+<!-- ##### FUNCTION g_source_connect ##### -->
+<para>
+
+</para>
+
+@source:
+@func:
+@data:
+@notify:
+
+
+<!-- ##### USER_FUNCTION GSourceFunc ##### -->
+<para>
+Specifies the type of function passed to g_timeout_add(), g_timeout_add_full(),
+g_idle_add(), and g_idle_add_full().
+</para>
+
+@data: data passed to the function, set when the source was created with one
+of the above functions.
+@Returns: it should return FALSE if the source should be removed.
+
+
+<!-- ##### FUNCTION g_source_connect_indirect ##### -->
+<para>
+
+</para>
+
+@source:
+@callback_data:
+@callback_funcs:
+
+
+<!-- ##### FUNCTION g_source_add_poll ##### -->
+<para>
+
+</para>
+
+@source:
+@fd:
+
+
+<!-- ##### FUNCTION g_source_remove_poll ##### -->
+<para>
+
+</para>
+
+@source:
+@fd:
+
+
+<!-- ##### FUNCTION g_source_get_current_time ##### -->
+<para>
+
+</para>
+
+@source:
+@timeval:
+
+
+<!-- ##### FUNCTION g_source_remove ##### -->
+<para>
+</para>
+
+@tag:
+@Returns:
+
+
+<!-- ##### FUNCTION g_source_remove_by_funcs_user_data ##### -->
+<para>
+</para>
+
+@funcs:
+@user_data:
+@Returns:
+
+
+<!-- ##### FUNCTION g_source_remove_by_user_data ##### -->
+<para>
+</para>
+
+@user_data:
+@Returns:
+
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../glib-docs.sgml" "book" "refsect2" "")
+End:
+-->
projects / dana / cg-glib.git / commitdiff
