From: Matthias Clasen Date: Sun, 11 Jul 2010 03:53:36 +0000 (-0400) Subject: Move main loop docs inline X-Git-Tag: 2.25.11~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=358b9d6ac750c3d35b259df2b59353d004a32ace;p=platform%2Fupstream%2Fglib.git Move main loop docs inline --- 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 -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(). - - - 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 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. - - - 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(). - - - - Customizing the main loop iteration - - 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(). - - - The operation of these functions can best be seen in terms - of a state diagram, as shown in . - -
- States of a Main Context - -
- + + + @@ -109,8 +22,7 @@ manages all available sources of events -The GMainLoop struct is an opaque data type -representing the main event loop of a GLib or GTK+ application. + @@ -177,102 +89,82 @@ representing the main event loop of a GLib or GTK+ application. -Creates a new #GMainLoop for the default main loop. + -@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: -Frees the memory allocated for the #GMainLoop. + -@loop: a #GMainLoop. -@Deprecated: 2.2: Use g_main_loop_unref() instead. +@loop: -Runs a main loop until it stops running. + -@loop: a #GMainLoop. -@Deprecated: 2.2: Use g_main_loop_run() instead. +@loop: -Stops the #GMainLoop. If g_main_run() was called to run the #GMainLoop, -it will now return. + -@loop: a #GMainLoop. -@Deprecated: 2.2: Use g_main_loop_quit() instead. +@loop: -Checks if the main loop is running. + -@loop: a #GMainLoop. -@Returns: %TRUE if the main loop is running. -@Deprecated: 2.2: USe g_main_loop_is_running() instead. +@loop: -Use this for high priority event sources. -It is not used within GLib or GTK+. + -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. + -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.) + -Use this for default priority idle functions. -In GLib this priority is used when adding idle functions with g_idle_add(). + -Use this for very low priority background tasks. -It is not used within GLib or GTK+. + -The GMainContext struct is an opaque data type -representing a set of sources to be handled in a main loop. + @@ -323,15 +215,10 @@ representing a set of sources to be handled in a main loop. -Runs a single iteration for the default #GMainContext. + -@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: @@ -345,12 +232,9 @@ processed. -Checks if any events are pending for the default #GMainContext -(i.e. ready to be processed). + -@Returns: %TRUE if any events are pending. -@Deprecated: 2.2: Use g_main_context_pending() instead. @@ -492,17 +376,13 @@ Checks if any events are pending for the default #GMainContext -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. + -@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: @@ -544,12 +424,10 @@ or -1 if an error occurred. -Sets the function to use for the handle polling of file descriptors -for the default main context. + -@func: the function to call to poll all file descriptors. -@Deprecated: 2.2: Use g_main_context_set_poll_func() instead. +@func: @@ -680,22 +558,18 @@ for the default main context. -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). + -The type of functions to be called when a child exists. + -@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: @@ -734,32 +608,6 @@ The type of functions to be called when a child exists. - - - - - -#gint fd; -the file descriptor to poll (or a HANDLE on Win32 platforms). - - - -#gushort events; -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. - - - - -#gushort revents; -a bitwise combination of flags from #GIOCondition, returned from the -poll() function to indicate which events occurred. - - - - @fd: @@ -787,8 +635,7 @@ you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use -The GSource struct is an opaque data type representing -an event source. + @@ -803,63 +650,24 @@ for dependency reasons. -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. - - -@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: -The GSourceCallbackFuncs struct contains -functions for managing callback objects. + -@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: 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(). + * + * Creating new source types + * 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 deriving 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. + * 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(). + * + * Customizing the main loop iteration + * 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(). + * The operation of these functions can best be seen in terms + * of a state diagram, as shown in . + *
States of a Main Context + * + *
+ * + */ + /* 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 GMainContext struct is an opaque data + * type representing a set of sources to be handled in a main loop. + */ +typedef struct _GMainContext GMainContext; + +/** + * GMainLoop: + * + * The GMainLoop struct is an opaque data type + * representing the main event loop of a GLib or GTK+ application. + */ +typedef struct _GMainLoop GMainLoop; + +/** + * GSource: + * + * The GSource 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 GSourceCallbackFuncs 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 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. + */ +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 HANDLE 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