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

Data Structures

struct  MetaPingData
 Describes a ping on a window. More...

Functions

static void ping_data_free (MetaPingData *ping_data)
 Destructor for MetaPingData structs.
static void remove_pending_pings_for_window (MetaDisplay *display, Window xwindow)
 Frees every pending ping structure for the given X window on the given display.
static gboolean meta_display_ping_timeout (gpointer data)
 Does whatever it is we decided to do when a window didn't respond to a ping.
void meta_display_ping_window (MetaDisplay *display, MetaWindow *window, guint32 timestamp, MetaWindowPingFunc ping_reply_func, MetaWindowPingFunc ping_timeout_func, gpointer user_data)
 Sends a ping request to a window.
static void process_pong_message (MetaDisplay *display, XEvent *event)
 Process the pong (the response message) from the ping we sent to the window.
gboolean meta_display_window_has_pending_pings (MetaDisplay *display, MetaWindow *window)
 Finds whether a window has any pings waiting on it.

Detailed Description

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.


Function Documentation

static gboolean meta_display_ping_timeout ( gpointer  data  )  [static]

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.

Parameters:
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.
Returns:
Always returns false, because this function is called as a timeout and we don't want to run the timer again.

Definition at line 4029 of file display.c.

References MetaPingData::display, FALSE, META_DEBUG_PING, _MetaDisplay::pending_pings, ping_data_free(), MetaPingData::ping_timeout_func, MetaPingData::ping_timeout_id, MetaPingData::timestamp, MetaPingData::user_data, and MetaPingData::xwindow.

Referenced by meta_display_ping_window().

void meta_display_ping_window ( MetaDisplay display,
MetaWindow window,
guint32  timestamp,
MetaWindowPingFunc  ping_reply_func,
MetaWindowPingFunc  ping_timeout_func,
gpointer  user_data 
)

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. This function returns straight away after setting things up; the callbacks will be called from the event loop.

Parameters:
display The MetaDisplay that the window is on
window The MetaWindow to send the ping to
timestamp The timestamp of the ping. Used for uniqueness. Cannot be CurrentTime; use a real timestamp!
ping_reply_func The callback to call if we get a response.
ping_timeout_func The callback to call if we don't get a response.
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.

Definition at line 4078 of file display.c.

References _MetaWindow::desc, MetaPingData::display, META_DEBUG_PING, meta_display_ping_timeout(), meta_warning(), meta_window_send_icccm_message(), _MetaWindow::net_wm_ping, _MetaDisplay::pending_pings, MetaPingData::ping_reply_func, PING_TIMEOUT_DELAY, MetaPingData::ping_timeout_func, MetaPingData::ping_timeout_id, MetaPingData::timestamp, MetaPingData::user_data, MetaPingData::xwindow, and _MetaWindow::xwindow.

gboolean meta_display_window_has_pending_pings ( MetaDisplay display,
MetaWindow window 
)

Finds whether a window has any pings waiting on it.

Parameters:
display The MetaDisplay of the window.
window The MetaWindow whose pings we want to know about.
Returns:
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.

Definition at line 4261 of file display.c.

References FALSE, _MetaDisplay::pending_pings, TRUE, _MetaWindow::xwindow, and MetaPingData::xwindow.

static void ping_data_free ( MetaPingData ping_data  )  [static]

Destructor for MetaPingData structs.

Will destroy the event source for the struct as well.

Definition at line 173 of file display.c.

References MetaPingData::ping_timeout_id.

Referenced by meta_display_ping_timeout(), process_pong_message(), and remove_pending_pings_for_window().

static void process_pong_message ( MetaDisplay display,
XEvent *  event 
) [static]

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.

Parameters:
display the display we got the pong from
event the XEvent which is a pong; we can tell which ping it corresponds to because it bears the same timestamp.

Definition at line 4203 of file display.c.

References META_DEBUG_PING, _MetaDisplay::pending_pings, ping_data_free(), MetaPingData::ping_reply_func, MetaPingData::ping_timeout_id, MetaPingData::timestamp, MetaPingData::user_data, and MetaPingData::xwindow.

Referenced by event_callback().

static void remove_pending_pings_for_window ( MetaDisplay display,
Window  xwindow 
) [static]

Frees every pending ping structure for the given X window on the given display.

This means that we also destroy the timeouts.

Parameters:
display The display the window appears on
xwindow The X ID of the window whose pings we should remove

Definition at line 193 of file display.c.

References NULL, _MetaDisplay::pending_pings, ping_data_free(), and MetaPingData::xwindow.

Referenced by meta_display_unregister_x_window().


Generated on Sat Aug 23 22:04:23 2008 for metacity by  doxygen 1.5.5