Function commenting marathon; more to come.
2008-01-06 Thomas Thurman <tthurman@gnome.org>
* src/core/display.c: Function commenting marathon; more to come.
svn path=/trunk/; revision=3506
This commit is contained in:
Thomas Thurman
Thomas James Alexander Thurman
parent
ee7cfc8824
commit
a409a0a098
@ -1,3 +1,7 @@
|
||||
2008-01-06 Thomas Thurman <tthurman@gnome.org>
|
||||
|
||||
* src/core/display.c: Function commenting marathon; more to come.
|
||||
|
||||
2008-01-02 Thomas Thurman <tthurman@gnome.org>
|
||||
|
||||
* src/core/xprops.c (meta_prop_get_cardinal), src/core/compositor.c
|
||||
|
||||
@ -80,6 +80,27 @@
|
||||
g == META_GRAB_OP_KEYBOARD_ESCAPING_DOCK || \
|
||||
g == META_GRAB_OP_KEYBOARD_ESCAPING_GROUP)
|
||||
|
||||
/*! \defgroup pings
|
||||
* Sometimes we want to see whether a window is responding,
|
||||
* so we send it a "ping" message and see whether it sends us back a "pong"
|
||||
* message within a reasonable time. Here we have a system which lets us
|
||||
* nominate one function to be called if we get the pong in time and another
|
||||
* function if we don't. The system is rather more complicated than it needs
|
||||
* to be, since we only ever use it to destroy windows which are asked to
|
||||
* close themselves and don't do so within a reasonable amount of time, and
|
||||
* therefore we always use the same callbacks. It's possible that we might
|
||||
* use it for other things in future, or on the other hand we might decide
|
||||
* that we're never going to do so and simplify it a bit.
|
||||
*/
|
||||
|
||||
/*! Describes a ping on a window. When we send a ping to a window, we build
|
||||
* one of these structs, and it eventually gets passed to the timeout function
|
||||
* or to the function which handles the response from the window. If the window
|
||||
* does or doesn't respond to the ping, we use this information to deal with
|
||||
* these facts; we have a handler function for each.
|
||||
*
|
||||
* \ingroup pings
|
||||
*/
|
||||
typedef struct
|
||||
{
|
||||
MetaDisplay *display;
|
||||
@ -127,6 +148,11 @@ static void sanity_check_timestamps (MetaDisplay *display,
|
||||
|
||||
MetaGroup* get_focussed_group (MetaDisplay *display);
|
||||
|
||||
/*! Destructor for MetaPingData structs. Will destroy the
|
||||
* event source for the struct as well.
|
||||
*
|
||||
* \ingroup pings
|
||||
*/
|
||||
static void
|
||||
ping_data_free (MetaPingData *ping_data)
|
||||
{
|
||||
@ -137,6 +163,15 @@ ping_data_free (MetaPingData *ping_data)
|
||||
g_free (ping_data);
|
||||
}
|
||||
|
||||
/*! Frees every pending ping structure for the given X window on the
|
||||
* given display. This means that we also destroy the timeouts.
|
||||
*
|
||||
* \param display The display the window appears on
|
||||
* \param xwindow The X ID of the window whose pings we should remove
|
||||
*
|
||||
* \ingroup pings
|
||||
*
|
||||
*/
|
||||
static void
|
||||
remove_pending_pings_for_window (MetaDisplay *display, Window xwindow)
|
||||
{
|
||||
@ -4049,14 +4084,31 @@ meta_display_set_cursor_theme (const char *theme,
|
||||
#endif
|
||||
}
|
||||
|
||||
/*! Stores whether syncing is currently enabled.
|
||||
*/
|
||||
static gboolean is_syncing = FALSE;
|
||||
|
||||
/*! Returns whether X synchronisation is currently enabled.
|
||||
*
|
||||
* \return true if we must wait for events whenever we send X requests;
|
||||
* false otherwise.
|
||||
*
|
||||
* \bug This is *only* called by meta_display_open, but by that time
|
||||
* we have already turned syncing on or off on startup, and we don't
|
||||
* have any way to do so while Metacity is running, so it's rather
|
||||
* pointless.
|
||||
*/
|
||||
gboolean
|
||||
meta_is_syncing (void)
|
||||
{
|
||||
return is_syncing;
|
||||
}
|
||||
|
||||
/*! A handy way to turn on synchronisation on or off for every display.
|
||||
*
|
||||
* \bug Of course there is only one display ever anyway, so this can
|
||||
* be rather hugely simplified.
|
||||
*/
|
||||
void
|
||||
meta_set_syncing (gboolean setting)
|
||||
{
|
||||
@ -4076,8 +4128,25 @@ meta_set_syncing (gboolean setting)
|
||||
}
|
||||
}
|
||||
|
||||
/*! How long, in milliseconds, we should wait after pinging a window
|
||||
* before deciding it's not going to get back to us.
|
||||
*/
|
||||
#define PING_TIMEOUT_DELAY 2250
|
||||
|
||||
/*! Does whatever it is we decided to do when a window didn't respond
|
||||
* to a ping. We also remove the ping from the display's list of
|
||||
* pending pings. This function is called by the event loop when the timeout
|
||||
* times out which we created at the start of the ping.
|
||||
*
|
||||
* \param data All the information about this ping. It is a MetaPingData
|
||||
* cast to a void* in order to be passable to a timeout function.
|
||||
* This function will also free this parameter.
|
||||
*
|
||||
* \return Always returns false, because this function is called as a
|
||||
* timeout and we don't want to run the timer again.
|
||||
*
|
||||
* \ingroup pings
|
||||
*/
|
||||
static gboolean
|
||||
meta_display_ping_timeout (gpointer data)
|
||||
{
|
||||
@ -4102,6 +4171,28 @@ meta_display_ping_timeout (gpointer data)
|
||||
return FALSE;
|
||||
}
|
||||
|
||||
/*! Sends a ping request to a window. The window must respond to
|
||||
* the request within a certain amount of time. If it does, we
|
||||
* will call one callback; if the time passes and we haven't had
|
||||
* a response, we call a different callback. The window must have
|
||||
* the hint showing that it can respond to a ping; if it doesn't,
|
||||
* we call the "got a response" callback immediately and return.
|
||||
*
|
||||
* \param display The MetaDisplay that the window is on
|
||||
* \param window The MetaWindow to send the ping to
|
||||
* \param timestamp The timestamp of the ping. Used for uniqueness.
|
||||
* Cannot be CurrentTime; use a real timestamp!
|
||||
* \param ping_reply_func The callback to call if we get a response.
|
||||
* \param ping_timeout_func The callback to call if we don't get a response.
|
||||
* \param user_data Arbitrary data that will be passed to the callback
|
||||
* function. (In practice it's often a pointer to
|
||||
* the window.)
|
||||
*
|
||||
* \bug This should probably be a method on windows, rather than displays
|
||||
* for one of their windows.
|
||||
*
|
||||
* \ingroup pings
|
||||
*/
|
||||
void
|
||||
meta_display_ping_window (MetaDisplay *display,
|
||||
MetaWindow *window,
|
||||
@ -4215,7 +4306,17 @@ process_request_frame_extents (MetaDisplay *display,
|
||||
meta_XFree (hints);
|
||||
}
|
||||
|
||||
/* process the pong from our ping */
|
||||
/*! Process the pong (the response message) from the ping we sent
|
||||
* to the window. This involves removing the timeout, calling the
|
||||
* reply handler function, and freeing memory.
|
||||
*
|
||||
* \param display the display we got the pong from
|
||||
* \param event the XEvent which is a pong; we can tell which
|
||||
* ping it corresponds to because it bears the
|
||||
* same timestamp.
|
||||
*
|
||||
* \ingroup pings
|
||||
*/
|
||||
static void
|
||||
process_pong_message (MetaDisplay *display,
|
||||
XEvent *event)
|
||||
@ -4260,6 +4361,17 @@ process_pong_message (MetaDisplay *display,
|
||||
}
|
||||
}
|
||||
|
||||
/*! Finds whether a window has any pings waiting on it.
|
||||
*
|
||||
* \param display The MetaDisplay of the window.
|
||||
* \param window The MetaWindow whose pings we want to know about.
|
||||
*
|
||||
* \return True if there is at least one ping which has been sent
|
||||
* to the window without getting a response; false otherwise.
|
||||
*
|
||||
* \bug This should probably be a method on windows, rather than displays
|
||||
* for one of their windows.
|
||||
*/
|
||||
gboolean
|
||||
meta_display_window_has_pending_pings (MetaDisplay *display,
|
||||
MetaWindow *window)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user