luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-10-31 00:12:19 +01:00
Code Issues Packages Projects Releases Wiki Activity

Move main loop docs inline

Browse Source
This commit is contained in:
Matthias Clasen
2010-07-10 23:53:36 -04:00
parent ab8cb652c8
commit 358b9d6ac7
4 changed files with 446 additions and 318 deletions
Download Patch File Download Diff File Expand all files Collapse all files

284
docs/reference/glib/tmpl/main.sgml
View File

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

76
glib/gmain.c
View File

@@ -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;

374
glib/gmain.h
View File

@@ -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 */

30
glib/gpoll.h
View File

@@ -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