From a409a0a098609c444e4c7076c76572cfafd67d0f Mon Sep 17 00:00:00 2001 From: Thomas Thurman Date: Sun, 6 Jan 2008 21:23:33 +0000 Subject: [PATCH] Function commenting marathon; more to come. 2008-01-06 Thomas Thurman * src/core/display.c: Function commenting marathon; more to come. svn path=/trunk/; revision=3506 --- ChangeLog | 4 ++ src/core/display.c | 114 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 117 insertions(+), 1 deletion(-) diff --git a/ChangeLog b/ChangeLog index 2c33ea040..e53b0fdc1 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2008-01-06 Thomas Thurman + + * src/core/display.c: Function commenting marathon; more to come. + 2008-01-02 Thomas Thurman * src/core/xprops.c (meta_prop_get_cardinal), src/core/compositor.c diff --git a/src/core/display.c b/src/core/display.c index 6cc546539..8e9c6c01f 100644 --- a/src/core/display.c +++ b/src/core/display.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)