minxlib::connection_error Struct Reference

An exception object to indicate failure to connect to X server. More...

#include <exception.hh>

Static Public Member Functions
static void	raise (const std::string &display_name)
	Throw a connection error. More...
Static Public Member Functions inherited from minxlib::exception
static void	pythonize ()
	Expose exception interface to Python. More...

Additional Inherited Members
Public Member Functions inherited from minxlib::exception
virtual	~exception () throw ()
	Virtual destructor. More...
Protected Types inherited from minxlib::exception
typedef void(*	py_func )()
	Signature for Pythonize functions. More...
Protected Member Functions inherited from minxlib::exception
	exception (const std::string &msg)
	Construct base exception object. More...
Static Protected Member Functions inherited from minxlib::exception
static bool	register_pythonize (type_info t, py_func f)
	Register subclass's pythonize function. More...
static void	set_py_exception (type_info t, PyObject *e)
	Register Python exception class object for a subclass. More...
static PyObject *	get_py_exception (type_info t)
	Retrieve Python exception class for specified C++ type. More...
template<typename T >
static void	translate (const T &e)
	Generic Boost.Python exception translator. More...
template<typename T >
static void	register_translator ()
	Register Boost.Python exception translator for type T. More...

Detailed Description

An exception object to indicate failure to connect to X server.

When a minxlib::display object is created, if it fails to connect to the X server, the display class's constructor will throw an instance of this class to indicate the failure. On the Python side of Minx, this class is derived from minxlib.exception, which, in turn, is derived from the standard Python Exception class.

Member Function Documentation

static void minxlib::connection_error::raise ( const std::string &  display_name)

static

Throw a connection error.

Parameters

display_name

Name of display to which connection failed.

Returns

Nothing.

This function throws a connection_error. Clients cannot directly instantiate this class and throw it. Instead, they must call this function to have the object created and thrown.

When raising a connection_error, the client must specify the name of X display to which the connection attempt failed. XDisplayName(), for example, will return something usable; refer to the Xlib documentation for further details.

Note

All the minxlib exception classes hide their constructors and require clients to call a raise() function instead. This is because, in some cases (errors to be reported from Xlib callbacks), throwing a C++ exception has very undesirable effects (e.g., the Minx process consuming 100% CPU). For those cases, we want to simply raise a Python exception without generating the corresponding C++ exception. Hiding the exception class constructors ensures that clients can only generate exceptions in the appropriate way.

For connection errors, since they occur from a normal C++/Python context rather than from inside an Xlib callback, it is alright to throw a C++ exception and have Boost.Python perform the necessary translations. However, to keep minxlib's exception interface uniform, we hide this class's constructor as well and require clients to use raise(), which, internally, instantiates and throws a connection_error.