[glib] Move main loop docs inline
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib] Move main loop docs inline
- Date: Sun, 11 Jul 2010 03:58:36 +0000 (UTC)
commit 358b9d6ac750c3d35b259df2b59353d004a32ace
Author: Matthias Clasen <mclasen redhat com>
Date: Sat Jul 10 23:53:36 2010 -0400
Move main loop docs inline
docs/reference/glib/tmpl/main.sgml | 288 +++++-----------------------
glib/gmain.c | 76 ++++++++
glib/gmain.h | 374 ++++++++++++++++++++++++++++--------
glib/gpoll.h | 30 +++-
4 files changed, 448 insertions(+), 320 deletions(-)
---
diff --git a/docs/reference/glib/tmpl/main.sgml b/docs/reference/glib/tmpl/main.sgml
index 30563cb..506bb7a 100644
--- a/docs/reference/glib/tmpl/main.sgml
+++ b/docs/reference/glib/tmpl/main.sgml
@@ -2,99 +2,12 @@
The Main Event Loop
<!-- ##### SECTION Short_Description ##### -->
-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_attach().
- </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 to it 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_loop_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_loop_quit() to exit the main loop, and g_main_loop_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 some of these functions, e.g. gtk_main(),
- gtk_main_quit() and gtk_events_pending().
- </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 element,
- 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 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>
+<para>
+
+</para>
<!-- ##### SECTION See_Also ##### -->
<para>
@@ -109,8 +22,7 @@ manages all available sources of events
<!-- ##### STRUCT GMainLoop ##### -->
<para>
-The <structname>GMainLoop</structname> struct is an opaque data type
-representing the main event loop of a GLib or GTK+ application.
+
</para>
@@ -177,102 +89,82 @@ representing the main event loop of a GLib or GTK+ application.
<!-- ##### MACRO g_main_new ##### -->
<para>
-Creates a new #GMainLoop for the default main loop.
+
</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.
- Deprecated: 2.2: Use g_main_loop_new() instead.
+ is_running:
<!-- ##### MACRO g_main_destroy ##### -->
<para>
-Frees the memory allocated for the #GMainLoop.
+
</para>
- loop: a #GMainLoop.
- Deprecated: 2.2: Use g_main_loop_unref() instead.
+ loop:
<!-- ##### MACRO g_main_run ##### -->
<para>
-Runs a main loop until it stops running.
+
</para>
- loop: a #GMainLoop.
- Deprecated: 2.2: Use g_main_loop_run() instead.
+ loop:
<!-- ##### MACRO g_main_quit ##### -->
<para>
-Stops the #GMainLoop. If g_main_run() was called to run the #GMainLoop,
-it will now return.
+
</para>
- loop: a #GMainLoop.
- Deprecated: 2.2: Use g_main_loop_quit() instead.
+ loop:
<!-- ##### MACRO g_main_is_running ##### -->
<para>
-Checks if the main loop is running.
+
</para>
- loop: a #GMainLoop.
- Returns: %TRUE if the main loop is running.
- Deprecated: 2.2: USe g_main_loop_is_running() instead.
+ loop:
<!-- ##### MACRO G_PRIORITY_HIGH ##### -->
<para>
-Use this for high priority event sources.
-It is not used within GLib or GTK+.
+
</para>
<!-- ##### MACRO G_PRIORITY_DEFAULT ##### -->
<para>
-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 server.
+
</para>
<!-- ##### MACRO G_PRIORITY_HIGH_IDLE ##### -->
<para>
-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.)
+
</para>
<!-- ##### MACRO G_PRIORITY_DEFAULT_IDLE ##### -->
<para>
-Use this for default priority idle functions.
-In GLib this priority is used when adding idle functions with g_idle_add().
+
</para>
<!-- ##### MACRO G_PRIORITY_LOW ##### -->
<para>
-Use this for very low priority background tasks.
-It is not used within GLib or GTK+.
+
</para>
<!-- ##### STRUCT GMainContext ##### -->
<para>
-The <structname>GMainContext</structname> struct is an opaque data type
-representing a set of sources to be handled in a main loop.
+
</para>
@@ -323,15 +215,10 @@ representing a set of sources to be handled in a main loop.
<!-- ##### MACRO g_main_iteration ##### -->
<para>
-Runs a single iteration for the default #GMainContext.
+
</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.
- Deprecated: 2.2: Use g_main_context_iteration() instead.
+ may_block:
<!-- ##### FUNCTION g_main_context_pending ##### -->
@@ -345,12 +232,9 @@ processed.
<!-- ##### MACRO g_main_pending ##### -->
<para>
-Checks if any events are pending for the default #GMainContext
-(i.e. ready to be processed).
+
</para>
- Returns: %TRUE if any events are pending.
- Deprecated: 2.2: Use g_main_context_pending() instead.
<!-- ##### FUNCTION g_main_context_find_source_by_id ##### -->
@@ -492,17 +376,13 @@ Checks if any events are pending for the default #GMainContext
<!-- ##### USER_FUNCTION GPollFunc ##### -->
<para>
-Specifies the type of function passed to g_main_context_set_poll_func().
-The semantics of the function should match those of the
-<function>poll()</function> system call.
+
</para>
- 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.
+ ufds:
+ nfsd:
+ timeout_:
+ Returns:
<!-- ##### FUNCTION g_main_context_add_poll ##### -->
@@ -544,12 +424,10 @@ or -1 if an error occurred.
<!-- ##### MACRO g_main_set_poll_func ##### -->
<para>
-Sets the function to use for the handle polling of file descriptors
-for the default main context.
+
</para>
- func: the function to call to poll all file descriptors.
- Deprecated: 2.2: Use g_main_context_set_poll_func() instead.
+ func:
<!-- ##### FUNCTION g_main_context_get_thread_default ##### -->
@@ -680,22 +558,18 @@ for the default main context.
<!-- ##### TYPEDEF GPid ##### -->
<para>
-A type which is used to hold a process identification.
-On Unix, processes are identified by a process id (an
-integer), while Windows uses process handles (which are
-pointers).
+
</para>
<!-- ##### USER_FUNCTION GChildWatchFunc ##### -->
<para>
-The type of functions to be called when a child exists.
+
</para>
- pid: the process id of the child process
- status: Status information about the child process,
- see waitpid(2) for more information about this field
- data: user data passed to g_child_watch_add()
+ pid:
+ status:
+ data:
<!-- ##### FUNCTION g_child_watch_source_new ##### -->
@@ -734,32 +608,6 @@ The type of functions to be called when a child exists.
<!-- ##### 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 <type>HANDLE</type> 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
-<function>poll()</function> function to indicate which events occurred.
-</entry>
-</row>
-</tbody></tgroup></informaltable>
-
</para>
@fd:
@@ -787,8 +635,7 @@ you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use
<!-- ##### STRUCT GSource ##### -->
<para>
-The <structname>GSource</structname> struct is an opaque data type representing
-an event source.
+
</para>
@@ -803,63 +650,24 @@ for dependency reasons.
<!-- ##### STRUCT GSourceFuncs ##### -->
<para>
-The #GSourceFuncs struct contains a table of functions used to handle
-event sources in a generic manner.
-</para>
-<para>
-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).
-</para>
-<para>
-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.
-</para>
-<para>
-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.
-</para>
-
- prepare: 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.
-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
-be the minimum of all the @timeout_ values returned which were >= 0.
- check: Called after all the file descriptors are polled.
-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.
- dispatch: 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 to a callback using
-g_source_set_callback(). The @dispatch function should call the
-callback function with @user_data and whatever additional parameters are
-needed for this type of event source.
- finalize: Called when the source is finalized.
+
+</para>
+
+ prepare:
+ check:
+ dispatch:
+ finalize:
@closure_callback:
@closure_marshal:
<!-- ##### STRUCT GSourceCallbackFuncs ##### -->
<para>
-The <structname>GSourceCallbackFuncs</structname> struct contains
-functions for managing callback objects.
+
</para>
- ref: Called when a reference is added to the callback object.
- unref: Called when a reference to the callback object is dropped.
- get: Called to extract the callback function and data from the callback object.
+ ref:
+ unref:
+ get:
<!-- ##### FUNCTION g_source_new ##### -->
<para>
diff --git a/glib/gmain.c b/glib/gmain.c
index ce703cb..d87f820 100644
--- a/glib/gmain.c
+++ b/glib/gmain.c
@@ -78,6 +78,82 @@
#endif
+/**
+ * SECTION:main
+ * @title: The Main Event Loop
+ * @short_description: manages all available sources of events
+ *
+ * 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_attach().
+ *
+ * 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 to it 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_loop_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_loop_quit() to
+ * exit the main loop, and g_main_loop_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 some of these functions, e.g. gtk_main(),
+ * gtk_main_quit() and gtk_events_pending().
+ *
+ * <refsect2><title>Creating new source types</title>
+ * <para>One of the unusual features of the #GMainLoop 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 element, 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 type.</para>
+ * <para>New source types basically interact 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>
+ */
+
/* Types */
typedef struct _GTimeoutSource GTimeoutSource;
diff --git a/glib/gmain.h b/glib/gmain.h
index 3012cd1..24c6171 100644
--- a/glib/gmain.h
+++ b/glib/gmain.h
@@ -8,7 +8,7 @@
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
@@ -30,16 +30,112 @@
G_BEGIN_DECLS
-typedef struct _GMainContext GMainContext; /* Opaque */
-typedef struct _GMainLoop GMainLoop; /* Opaque */
-typedef struct _GSource GSource;
-typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs;
-typedef struct _GSourceFuncs GSourceFuncs;
+/**
+ * GMainContext:
+ *
+ * The <structname>GMainContext</structname> struct is an opaque data
+ * type representing a set of sources to be handled in a main loop.
+ */
+typedef struct _GMainContext GMainContext;
+
+/**
+ * GMainLoop:
+ *
+ * The <structname>GMainLoop</structname> struct is an opaque data type
+ * representing the main event loop of a GLib or GTK+ application.
+ */
+typedef struct _GMainLoop GMainLoop;
+
+/**
+ * GSource:
+ *
+ * The <structname>GSource</structname> struct is an opaque data type
+ * representing an event source.
+ */
+typedef struct _GSource GSource;
+
+/**
+ * GSourceCallbackFuncs:
+ * @ref: Called when a reference is added to the callback object
+ * @unref: Called when a reference to the callback object is dropped
+ * @get: Called to extract the callback function and data from the
+ * callback object.
+
+ * The <structname>GSourceCallbackFuncs</structname> struct contains
+ * functions for managing callback objects.
+ */
+typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs;
+
+/**
+ * GSourceFuncs:
+ * @prepare: 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. 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 be the minimum of all the
+ * @timeout_ values returned which were >= 0.
+ * @check: Called after all the file descriptors are polled. 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.
+ * @dispatch: 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 to a callback
+ * using g_source_set_callback(). The @dispatch function should call the
+ * callback function with @user_data and whatever additional parameters
+ * are needed for this type of event source.
+ * @finalize: Called when the source is finalized.
+ * @closure_callback:
+ * @closure_marshal:
+ *
+ * The <structname>GSourceFuncs</structname> 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.
+ */
+typedef struct _GSourceFuncs GSourceFuncs;
+
+/**
+ * GPid:
+ *
+ * A type which is used to hold a process identification.
+ *
+ * On UNIX, processes are identified by a process id (an integer),
+ * while Windows uses process handles (which are pointers).
+ */
typedef gboolean (*GSourceFunc) (gpointer data);
+
+/**
+ * GChildWatchFunc:
+ * @pid: the process id of the child process
+ * @status: Status information about the child process,
+ * see waitpid(2) for more information about this field
+ * @data: user data passed to g_child_watch_add()
+ *
+ * The type of functions to be called when a child exists.
+ */
typedef void (*GChildWatchFunc) (GPid pid,
- gint status,
- gpointer data);
+ gint status,
+ gpointer data);
struct _GSource
{
/*< private >*/
@@ -69,9 +165,9 @@ struct _GSourceCallbackFuncs
void (*ref) (gpointer cb_data);
void (*unref) (gpointer cb_data);
void (*get) (gpointer cb_data,
- GSource *source,
- GSourceFunc *func,
- gpointer *data);
+ GSource *source,
+ GSourceFunc *func,
+ gpointer *data);
};
typedef void (*GSourceDummyMarshal) (void);
@@ -79,25 +175,70 @@ typedef void (*GSourceDummyMarshal) (void);
struct _GSourceFuncs
{
gboolean (*prepare) (GSource *source,
- gint *timeout_);
+ gint *timeout_);
gboolean (*check) (GSource *source);
gboolean (*dispatch) (GSource *source,
- GSourceFunc callback,
- gpointer user_data);
+ GSourceFunc callback,
+ gpointer user_data);
void (*finalize) (GSource *source); /* Can be NULL */
/* For use by g_source_set_closure */
- GSourceFunc closure_callback;
+ GSourceFunc closure_callback;
GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
};
/* Standard priorities */
+/**
+ * G_PRIORITY_HIGH:
+ *
+ * Use this for high priority event sources.
+ *
+ * It is not used within GLib or GTK+.
+ */
#define G_PRIORITY_HIGH -100
+
+/**
+ * G_PRIORITY_DEFAULT:
+ *
+ * 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 server.
+ */
#define G_PRIORITY_DEFAULT 0
+
+/**
+ * G_PRIORITY_HIGH_IDLE:
+ *
+ * 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.)
+ */
#define G_PRIORITY_HIGH_IDLE 100
+
+/**
+ * G_PRIORITY_DEFAULT_IDLE:
+ *
+ * Use this for default priority idle functions.
+ *
+ * In GLib this priority is used when adding idle functions with
+ * g_idle_add().
+ */
#define G_PRIORITY_DEFAULT_IDLE 200
-#define G_PRIORITY_LOW 300
+
+/**
+ * G_PRIORITY_LOW:
+ *
+ * Use this for very low priority background tasks.
+ *
+ * It is not used within GLib or GTK+.
+ */
+#define G_PRIORITY_LOW 300
/* GMainContext: */
@@ -107,18 +248,18 @@ void g_main_context_unref (GMainContext *context);
GMainContext *g_main_context_default (void);
gboolean g_main_context_iteration (GMainContext *context,
- gboolean may_block);
+ gboolean may_block);
gboolean g_main_context_pending (GMainContext *context);
/* For implementation of legacy interfaces
*/
GSource *g_main_context_find_source_by_id (GMainContext *context,
- guint source_id);
+ guint source_id);
GSource *g_main_context_find_source_by_user_data (GMainContext *context,
- gpointer user_data);
+ gpointer user_data);
GSource *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
- GSourceFuncs *funcs,
- gpointer user_data);
+ GSourceFuncs *funcs,
+ gpointer user_data);
/* Low level functions for implementing custom main loops.
*/
@@ -127,33 +268,33 @@ gboolean g_main_context_acquire (GMainContext *context);
void g_main_context_release (GMainContext *context);
gboolean g_main_context_is_owner (GMainContext *context);
gboolean g_main_context_wait (GMainContext *context,
- GCond *cond,
- GMutex *mutex);
+ GCond *cond,
+ GMutex *mutex);
gboolean g_main_context_prepare (GMainContext *context,
- gint *priority);
+ gint *priority);
gint g_main_context_query (GMainContext *context,
- gint max_priority,
- gint *timeout_,
- GPollFD *fds,
- gint n_fds);
+ gint max_priority,
+ gint *timeout_,
+ GPollFD *fds,
+ gint n_fds);
gint g_main_context_check (GMainContext *context,
- gint max_priority,
- GPollFD *fds,
- gint n_fds);
+ gint max_priority,
+ GPollFD *fds,
+ gint n_fds);
void g_main_context_dispatch (GMainContext *context);
void g_main_context_set_poll_func (GMainContext *context,
- GPollFunc func);
+ GPollFunc func);
GPollFunc g_main_context_get_poll_func (GMainContext *context);
/* Low level functions for use by source implementations
*/
void g_main_context_add_poll (GMainContext *context,
- GPollFD *fd,
- gint priority);
+ GPollFD *fd,
+ gint priority);
void g_main_context_remove_poll (GMainContext *context,
- GPollFD *fd);
+ GPollFD *fd);
gint g_main_depth (void);
GSource *g_main_current_source (void);
@@ -167,7 +308,7 @@ GMainContext *g_main_context_get_thread_default (void);
/* GMainLoop: */
GMainLoop *g_main_loop_new (GMainContext *context,
- gboolean is_running);
+ gboolean is_running);
void g_main_loop_run (GMainLoop *loop);
void g_main_loop_quit (GMainLoop *loop);
GMainLoop *g_main_loop_ref (GMainLoop *loop);
@@ -178,28 +319,28 @@ GMainContext *g_main_loop_get_context (GMainLoop *loop);
/* GSource: */
GSource *g_source_new (GSourceFuncs *source_funcs,
- guint struct_size);
+ guint struct_size);
GSource *g_source_ref (GSource *source);
void g_source_unref (GSource *source);
guint g_source_attach (GSource *source,
- GMainContext *context);
+ GMainContext *context);
void g_source_destroy (GSource *source);
void g_source_set_priority (GSource *source,
- gint priority);
+ gint priority);
gint g_source_get_priority (GSource *source);
void g_source_set_can_recurse (GSource *source,
- gboolean can_recurse);
+ gboolean can_recurse);
gboolean g_source_get_can_recurse (GSource *source);
guint g_source_get_id (GSource *source);
GMainContext *g_source_get_context (GSource *source);
void g_source_set_callback (GSource *source,
- GSourceFunc func,
- gpointer data,
- GDestroyNotify notify);
+ GSourceFunc func,
+ gpointer data,
+ GDestroyNotify notify);
void g_source_set_funcs (GSource *source,
GSourceFuncs *funcs);
@@ -214,16 +355,16 @@ void g_source_set_name_by_id (guint tag,
/* Used to implement g_source_connect_closure and internally*/
void g_source_set_callback_indirect (GSource *source,
- gpointer callback_data,
- GSourceCallbackFuncs *callback_funcs);
+ gpointer callback_data,
+ GSourceCallbackFuncs *callback_funcs);
void g_source_add_poll (GSource *source,
- GPollFD *fd);
+ GPollFD *fd);
void g_source_remove_poll (GSource *source,
- GPollFD *fd);
+ GPollFD *fd);
void g_source_get_current_time (GSource *source,
- GTimeVal *timeval);
+ GTimeVal *timeval);
/* void g_source_connect_closure (GSource *source,
GClosure *closure);
@@ -238,27 +379,106 @@ GSource *g_timeout_source_new_seconds (guint interval);
/* Miscellaneous functions
*/
-void g_get_current_time (GTimeVal *result);
+void g_get_current_time (GTimeVal *result);
/* ============== Compat main loop stuff ================== */
#ifndef G_DISABLE_DEPRECATED
-/* Legacy names for GMainLoop functions
+/**
+ * g_main_new:
+ * @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.
+ *
+ * Creates a new #GMainLoop for th default main context.
+ *
+ * Returns: a new #GMainLoop
+ *
+ * Deprecated: 2.2: Use g_main_loop_new() instead
+ */
+#define g_main_new(is_running) g_main_loop_new (NULL, is_running)
+
+/**
+ * g_main_run:
+ * @loop: a #GMainLoop
+ *
+ * Runs a main loop until it stops running.
+ *
+ * Deprecated: 2.2: Use g_main_loop_run() instead
*/
-#define g_main_new(is_running) g_main_loop_new (NULL, is_running);
#define g_main_run(loop) g_main_loop_run(loop)
-#define g_main_quit(loop) g_main_loop_quit(loop)
-#define g_main_destroy(loop) g_main_loop_unref(loop)
-#define g_main_is_running(loop) g_main_loop_is_running(loop)
-/* Functions to manipulate the default main loop
+/**
+ * g_main_quit:
+ * @loop: a #GMainLoop
+ *
+ * Stops the #GMainLoop.
+ * If g_main_run() was called to run the #GMainLoop, it will now return.
+ *
+ * Deprecated: 2.2: Use g_main_loop_quit() instead
*/
+#define g_main_quit(loop) g_main_loop_quit(loop)
-#define g_main_iteration(may_block) g_main_context_iteration (NULL, may_block)
-#define g_main_pending() g_main_context_pending (NULL)
+/**
+ * g_main_destroy:
+ * @loop: a #GMainLoop
+ *
+ * Frees the memory allocated for the #GMainLoop.
+ *
+ * Deprecated: 2.2: Use g_main_loop_unref() instead
+ */
+#define g_main_destroy(loop) g_main_loop_unref(loop)
-#define g_main_set_poll_func(func) g_main_context_set_poll_func (NULL, func)
+/**
+ * g_main_is_running:
+ * @loop: a #GMainLoop
+ *
+ * Checks if the main loop is running.
+ *
+ * Returns: %TRUE if the main loop is running
+ *
+ * Deprecated: 2.2: Use g_main_loop_is_running() instead
+ */
+#define g_main_is_running(loop) g_main_loop_is_running(loop)
+
+/**
+ * g_main_iteration:
+ * @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.
+ *
+ * Runs a single iteration for the default #GMainContext.
+ *
+ * Returns: %TRUE if more events are pending.
+ *
+ * Deprecated: 2.2: Use g_main_context_iteration() instead.
+ */
+#define g_main_iteration(may_block) g_main_context_iteration (NULL, may_block)
+
+/**
+ * g_main_pending:
+ *
+ * Checks if any events are pending for the default #GMainContext
+ * (i.e. ready to be processed).
+ *
+ * Returns: %TRUE if any events are pending.
+ *
+ * Deprected: 2.2: Use g_main_context_pending() instead.
+ */
+#define g_main_pending() g_main_context_pending (NULL)
+
+/**
+ * g_main_set_poll_func:
+ * @func: the function to call to poll all file descriptors
+ *
+ * Sets the function to use for the handle polling of file descriptors
+ * for the default main context.
+ *
+ * Deprecated: 2.2: Use g_main_context_set_poll_func() again
+ */
+#define g_main_set_poll_func(func) g_main_context_set_poll_func (NULL, func)
#endif /* G_DISABLE_DEPRECATED */
@@ -266,39 +486,39 @@ void g_get_current_time (GTimeVal *result);
gboolean g_source_remove (guint tag);
gboolean g_source_remove_by_user_data (gpointer user_data);
gboolean g_source_remove_by_funcs_user_data (GSourceFuncs *funcs,
- gpointer user_data);
+ gpointer user_data);
/* Idles, child watchers and timeouts */
guint g_timeout_add_full (gint priority,
- guint interval,
- GSourceFunc function,
- gpointer data,
- GDestroyNotify notify);
+ guint interval,
+ GSourceFunc function,
+ gpointer data,
+ GDestroyNotify notify);
guint g_timeout_add (guint interval,
- GSourceFunc function,
- gpointer data);
+ GSourceFunc function,
+ gpointer data);
guint g_timeout_add_seconds_full (gint priority,
guint interval,
GSourceFunc function,
gpointer data,
GDestroyNotify notify);
guint g_timeout_add_seconds (guint interval,
- GSourceFunc function,
- gpointer data);
+ GSourceFunc function,
+ gpointer data);
guint g_child_watch_add_full (gint priority,
- GPid pid,
- GChildWatchFunc function,
- gpointer data,
- GDestroyNotify notify);
+ GPid pid,
+ GChildWatchFunc function,
+ gpointer data,
+ GDestroyNotify notify);
guint g_child_watch_add (GPid pid,
- GChildWatchFunc function,
- gpointer data);
+ GChildWatchFunc function,
+ gpointer data);
guint g_idle_add (GSourceFunc function,
- gpointer data);
+ gpointer data);
guint g_idle_add_full (gint priority,
- GSourceFunc function,
- gpointer data,
- GDestroyNotify notify);
+ GSourceFunc function,
+ gpointer data,
+ GDestroyNotify notify);
gboolean g_idle_remove_by_data (gpointer data);
/* Hook for GClosure / GSource integration. Don't touch */
diff --git a/glib/gpoll.h b/glib/gpoll.h
index eec4723..cc79381 100644
--- a/glib/gpoll.h
+++ b/glib/gpoll.h
@@ -59,10 +59,34 @@ G_BEGIN_DECLS
* Windows.
*/
typedef struct _GPollFD GPollFD;
-typedef gint (*GPollFunc) (GPollFD *ufds,
- guint nfsd,
- gint timeout_);
+/**
+ * GPollFunc:
+ * @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.
+ *
+ * Specifies the type of function passed to g_main_context_set_poll_func().
+ * The semantics of the function should match those of the poll() system call.
+ *
+ * Returns: the number of #GPollFD elements which have events or errors
+ * reported, or -1 if an error occurred.
+ */
+typedef gint (*GPollFunc) (GPollFD *ufds,
+ guint nfsd,
+ gint timeout_);
+
+/**
+ * GPollFD:
+ * @fd: the file descriptor to poll (or a <type>HANDLE</type> on Win32)
+ * @events: a bitwise combination 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.
+ * @revents: a bitwise combination of flags from #GIOCondition, returned
+ * from the poll() function to indicate which events occurred.
+ */
struct _GPollFD
{
#if defined (G_OS_WIN32) && GLIB_SIZEOF_VOID_P == 8
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
