luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-12-10 18:43:42 +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

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