Description
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().
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.
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.
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.
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.
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.
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().
Creating new sources types
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 deriving 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.
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().
Details
struct GMainLoop
The GMainLoop struct is an opaque data type representing the main event loop
of a GLib or GTK+ application.
g_main_loop_new ()
Create a new GMainLoop structure
g_main_loop_ref ()
Increase the reference count on a GMainLoop object by one.
g_main_loop_unref ()
Decreases the reference count on a GMainLoop object by one. If
the result is zero, free the loop and free all associated memory.
g_main_loop_run ()
Run a main loop until g_main_quit() is called on the loop.
If this is called for the thread of the loop's GMainContext,
it will process events from the loop, otherwise it will
simply wait.
g_main_loop_is_running ()
Check to see if the main loop is currently being run via g_main_run()
g_main_new()
#define g_main_new(is_running) |
Warning |
g_main_new is deprecated and should not be used in newly-written code. |
Creates a new GMainLoop for the default main loop. A compatibility
macro, see g_main_loop_new().
g_main_destroy()
#define g_main_destroy(loop) |
Warning |
g_main_destroy is deprecated and should not be used in newly-written code. |
Frees the memory allocated for the GMainLoop. A compatibility macro, see
g_main_loop_destroy().
g_main_run()
Warning |
g_main_run is deprecated and should not be used in newly-written code. |
Runs a main loop until it stops running. A compatibility macro, see g_main_loop_run().
g_main_quit()
#define g_main_quit(loop) |
Warning |
g_main_quit is deprecated and should not be used in newly-written code. |
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().
g_main_is_running()
#define g_main_is_running(loop) |
Warning |
g_main_is_running is deprecated and should not be used in newly-written code. |
Checks if the main loop is running. A compatibility macro, see
g_main_loop_is_running().
G_PRIORITY_HIGH
#define G_PRIORITY_HIGH -100 |
Use this for high priority event sources.
It is not used within GLib or GTK+.
G_PRIORITY_DEFAULT
#define G_PRIORITY_DEFAULT 0 |
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 Windows server.
G_PRIORITY_HIGH_IDLE
#define G_PRIORITY_HIGH_IDLE 100 |
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.)
G_PRIORITY_DEFAULT_IDLE
#define G_PRIORITY_DEFAULT_IDLE 200 |
Use this for default priority idle functions.
In GLib this priority is used when adding idle functions with g_idle_add().
G_PRIORITY_LOW
#define G_PRIORITY_LOW 300 |
Use this for very low priority background tasks.
It is not used within GLib or GTK+.
g_main_context_get ()
Retrieves the main loop context for a particular thread. This
will create the main context for the thread if none previously
existed. The context will exist until the thread terminates.
g_main_context_default ()
Return the default main context. This is the main context used
for main loop functions when a main loop is not explicitly
specified.
g_main_context_iteration ()
Run a single iteration for the given main loop. This involves
checking to see if any event sources are ready to be processed,
then if no events sources are ready and may_block is TRUE, waiting
for a source to become ready, then dispatching the highest priority
events sources that are ready. Note that even when may_block is TRUE,
it is still possible for g_main_context_iteration() to return
FALSE, since the the wait may be interrupted for other
reasons than an event source becoming ready.
g_main_iteration()
#define g_main_iteration(may_block) |
Warning |
g_main_iteration is deprecated and should not be used in newly-written code. |
Runs a single iteration for the default GMainContext.
A compatibility macro, see g_main_context_iteration().
g_main_context_pending ()
Check if any sources have pending events for the given context.
g_main_pending()
Warning |
g_main_pending is deprecated and should not be used in newly-written code. |
Checks if any events are pending for the default GMainContext
(i.e. ready to be processed). A compatibility macro, see
g_main_context_pending().
g_main_context_find_source_by_id ()
Finds a GSource given a pair of context and ID
g_main_context_find_source_by_user_data ()
Finds a source with the given user data for the callback. If
multiple sources exist with the same user data, the first
one found will be returned.
g_main_context_find_source_by_funcs_user_data ()
Finds a source with the given source functions and user data. If
multiple sources exist with the same source function and user data,
the first one found will be returned.
g_main_context_prepare ()
Prepares to poll sources within a main loop. The resulting information
for polling is determined by calling g_main_context_query().
g_main_context_query ()
Determines information necessary to poll this main loop.
g_main_context_check ()
Pass the results of polling back to the main loop.
g_main_context_dispatch ()
Dispatch all pending sources()
g_main_context_set_poll_func ()
Sets the function to use to handle polling of file descriptors. It
will be used instead of the poll() system call (or GLib's
replacement function, which is used where poll() isn't available).
This function could possibly be used to integrate the GLib event
loop with an external event loop.
GPollFunc ()
Specifies the type of function passed to g_main_set_poll_func().
The semantics of the function should match those of the
poll() system call.
g_main_context_add_poll ()
Add a file descriptor to the set of file descriptors polled * for
this context. This will very seldom be used directly. Instead
a typical event source will use g_source_add_poll() instead.
g_main_context_remove_poll ()
Remove file descriptor from the set of file descriptors to be
polled for a particular context.
g_main_set_poll_func()
#define g_main_set_poll_func(func) |
Warning |
g_main_set_poll_func is deprecated and should not be used in newly-written code. |
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.
g_timeout_source_new ()
Create a new timeout source.
The source will not initially be associated with any GMainContext
and must be added to one with g_source_attach() before it will be
executed.
g_timeout_add ()
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 notify
function is called when the timeout is destroyed. The first call
to the function will be at the end of the first interval.
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).
g_timeout_add_full ()
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.
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).
g_idle_source_new ()
Create a new idle source.
The source will not initially be associated with any GMainContext
and must be added to one with g_source_attach() before it will be
executed.
g_idle_add ()
Adds a function to be called whenever there are no higher priority
events pending to the default main loop. 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.
g_idle_add_full ()
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.
g_idle_remove_by_data ()
Removes the idle function with the given data.
struct GPollFD
struct GPollFD
{
gint fd;
gushort events;
gushort revents;
}; |
struct GSource
struct GSource
{
/*< private >*/
gpointer callback_data;
GSourceCallbackFuncs *callback_funcs;
GSourceFuncs *source_funcs;
guint ref_count;
GMainContext *context;
gint priority;
guint flags;
guint id;
GSList *poll_fds;
GSource *prev;
GSource *next;
}; |
struct GSourceFuncs
struct GSourceFuncs
{
gboolean (*prepare) (GSource *source,
gint *timeout);
gboolean (*check) (GSource *source);
gboolean (*dispatch) (GSource *source,
GSourceFunc callback,
gpointer user_data);
void (*destroy) (GSource *source); /* Can be NULL */
}; |
The GSourceFuncs struct contains a table of functions used to handle
event sources in a generic manner.
For idle sources, the prepare and check functions always return TRUE to
indicate that the source is always ready to be processed.
The prepare function also returns a timeout value of 0 to ensure that the
poll() call doesn't block (since that would be time wasted which could have
been spent running the idle function).
For timeout sources, the prepare and check functions both return TRUE if the
timeout interval has expired.
The prepare function also returns a timeout value to ensure that the poll()
call doesn't block too long and miss the next timeout.
For file descriptor sources, the prepare function typically returns FALSE,
since it must wait until poll() has been called before it knows whether any
events need to be processed. It sets the returned timeout to -1 to indicate
that it doesn't mind how long the poll() call blocks.
In the check function, it tests the results of the poll() call to see if
the required condition has been met, and returns TRUE if so.
struct GSourceCallbackFuncs
struct GSourceCallbackFuncs
{
void (*ref) (gpointer cb_data);
void (*unref) (gpointer cb_data);
void (*get) (gpointer cb_data,
GSourceFunc *func,
gpointer *data);
}; |
g_source_new ()
Create a new GSource structure. The size is specified to
allow creating structures derived from GSource that contain
additional data. The size passed in must be at least
sizeof(GSource).
The source will not initially be associated with any GMainContext
and must be added to one with g_source_add() before it will be
executed.
g_source_ref ()
Increases the reference count on a source by one.
g_source_unref ()
void g_source_unref (GSource *source); |
Decreases the reference count of a source by one. If the
resulting reference count is zero the source and associated
memory will be destroyed.
g_source_attach ()
Adds a GSource to a context so that it will be executed within
that context.
g_source_destroy ()
void g_source_destroy (GSource *source); |
Remove a source from its GMainContext, if any, and mark it as
destroyed. The source cannot be subsequently added to another
context.
g_source_set_priority ()
void g_source_set_priority (GSource *source,
gint priority); |
Set the priority of a source. While the main loop is being
run, a source will
g_source_get_priority ()
Gets the priority of a surce
g_source_set_can_recurse ()
Sets whether a source can be called recursively. If can_recurse is
TRUE, then while the source is being dispatched then this source
will be processed normally. Otherwise, all processing of this
source is blocked until the dispatch function returns.
g_source_get_can_recurse ()
Checks whether a source is allowed to be called recursively.
see g_source_set_can_recurse.
g_source_get_id ()
Return the numeric ID for a particular source. The ID of a source
is unique within a particular main loop context. The reverse
mapping from ID to source is done by g_main_context_find_source_by_id().
g_source_get_context ()
Get the GMainContext with which the source is associated.
Calling this function on a destroyed source is an error.
g_source_set_callback ()
Set the callback function for a source.
g_source_set_callback_indirect ()
Set the callback function storing the data as a refcounted callback
"object". This is used to implement g_source_set_callback_closure()
and internally. Note that calling g_source_set_callback_indirect() assumes
an initial reference count on callback_data, and thus
callback_funcs->unref will eventually be called once more
than callback_funcs->ref.
g_source_add_poll ()
Add a file descriptor to the set of file descriptors polled for
this source. This is usually combined with g_source_new() 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.
g_source_remove_poll ()
Remove a file descriptor from the set of file descriptors polled for
this source.
g_source_get_current_time ()
Gets the "current time" to be used when checking
this source. The advantage of calling this function over
calling g_get_current_time() directly is that when
checking multiple sources, GLib can cache a single value
instead of having to repeatedly get the system time.
g_source_remove_by_funcs_user_data ()
Removes a source from the default main loop context given the
source functions and user data. If multiple sources exist with the
same source functions and user data, only one will be destroyed.
g_source_remove_by_user_data ()
Removes a source from the default main loop context given the user
data for the callback. If multiple sources exist with the same user
data, only one will be destroyed.