The Main Event Loop

struct GMainLoop

struct GMainLoop;

The GMainLoop struct is an opaque data type representing the main event loop of a GLib or GTK+ application.

g_main_new ()

GMainLoop*  g_main_new                      (gboolean is_running);

Creates a new GMainLoop.

g_main_destroy ()

void        g_main_destroy                  (GMainLoop *loop);

Frees the memory allocated for the GMainLoop.

g_main_run ()

void        g_main_run                      (GMainLoop *loop);

Runs a main loop until it stops running, which occurs when g_main_quit() is called.

g_main_is_running ()

gboolean    g_main_is_running               (GMainLoop *loop);

Returns TRUE if the main loop is running.

g_main_pending ()

gboolean    g_main_pending                  (void);

Returns TRUE if any events are pending (i.e. ready to be processed).

g_main_iteration ()

gboolean    g_main_iteration                (gboolean may_block);

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.

g_main_quit ()

void        g_main_quit                     (GMainLoop *loop);

Stops the GMainLoop. If g_main_run() was called to run the GMainLoop, it will now return.

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_timeout_add ()

guint       g_timeout_add                   (guint interval,
                                             GSourceFunc function,
                                             gpointer data);

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.

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 ()

guint       g_timeout_add_full              (gint priority,
                                             guint interval,
                                             GSourceFunc function,
                                             gpointer data,
                                             GDestroyNotify notify);

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).

GSourceFunc ()

gboolean    (*GSourceFunc)                  (gpointer data);

Specifies the type of function passed to g_timeout_add(), g_timeout_add_full(), g_idle_add(), and g_idle_add_full().

g_idle_add ()

guint       g_idle_add                      (GSourceFunc function,
                                             gpointer data);

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.

g_idle_add_full ()

guint       g_idle_add_full                 (gint priority,
                                             GSourceFunc function,
                                             gpointer data,
                                             GDestroyNotify destroy);

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 ()

gboolean    g_idle_remove_by_data           (gpointer data);

Removes the idle function with the given data.

g_main_add_poll ()

void        g_main_add_poll                 (GPollFD *fd,
                                             gint priority);

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.

struct GPollFD

struct GPollFD
{
  gint		fd;
  gushort 	events;
  gushort 	revents;
};

g_main_remove_poll ()

void        g_main_remove_poll              (GPollFD *fd);

Removes a file descriptor from the list being polled.

g_main_set_poll_func ()

void        g_main_set_poll_func            (GPollFunc 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 ()

gint        (*GPollFunc)                    (GPollFD *ufds,
                                             guint nfsd,
                                             gint timeout);

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_source_add ()

guint       g_source_add                    (gint priority,
                                             gboolean can_recurse,
                                             GSourceFuncs *funcs,
                                             gpointer source_data,
                                             gpointer user_data,
                                             GDestroyNotify notify);

Adds an event source to the main loop.

struct GSourceFuncs

struct GSourceFuncs
{
  gboolean (*prepare)  (gpointer  source_data, 
			GTimeVal *current_time,
			gint     *timeout,
			gpointer  user_data);
  gboolean (*check)    (gpointer  source_data,
			GTimeVal *current_time,
			gpointer  user_data);
  gboolean (*dispatch) (gpointer  source_data, 
			GTimeVal *current_time,
			gpointer  user_data);
  GDestroyNotify destroy;
};

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.

g_source_remove ()

gboolean    g_source_remove                 (guint tag);

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().

g_source_remove_by_funcs_user_data ()

gboolean    g_source_remove_by_funcs_user_data
                                            (GSourceFuncs *funcs,
                                             gpointer user_data);

Removes the first event source found with the given GSourceFuncs and user data.

Event sources are sorted with the highest priority first. Sources with equal priority are stored in the order in which they were added.

g_source_remove_by_source_data ()

gboolean    g_source_remove_by_source_data  (gpointer source_data);

Removes the first event source found with the given source data.

Event sources are sorted with the highest priority first. Sources with equal priority are stored in the order in which they were added.

g_source_remove_by_user_data ()

gboolean    g_source_remove_by_user_data    (gpointer user_data);

Removes the first event source found with the given user data.

Event sources are sorted with the highest priority first. Sources with equal priority are stored in the order in which they were added.