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().