minxlib::fatal_error Struct Reference

An exception object to indicate a fatal X error. More...

#include <exception.hh>

Static Public Member Functions
static void	raise ()
	Report a fatal X error. More...
static void	throw_it ()
	Throw a fatal_error in C++ rather than raising it in Python. 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 a fatal X error.

When something fatal happens (such as losing the connection to the X server), minxlib will notify its Python clients by raising an instance of this class as an exception. Like all minxlib exceptions, on the Python side of Minx, this class is derived from minxlib.exception, which, in turn, is derived from the standard Python Exception class.

After a fatal_error is raised, clients should clean-up and terminate. Attempting further use of Xlib via minxlib will result in continued fatal_error exceptions.

Member Function Documentation

static void minxlib::fatal_error::raise ( )

static

Report a fatal X error.

Returns

Nothing.

This function raises a minxlib.fatal_error so the Python side of Minx is informed of catastrophic failures such as losing the connection to the X server.

Note

C++ clients cannot directly instantiate this class and throw it. Instead, they must call this function to have the error properly reported to the Python side.

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.

static void minxlib::fatal_error::throw_it ( )

static

Throw a fatal_error in C++ rather than raising it in Python.

Returns

Nothing.

When a fatal X error is encountered, minxlib::display::report_fatal_errors() will raise a minxlib.fatal_error on the Python side without throwing a minxlib::fatal_error C++ exception because we cannot throw C++ exceptions from Xlib callbacks.

After that, minxlib::display will set an internal flag to indicate that a fatal error has been encountered and that its connection to the X server can no longer be used. Clients that try to ignore the first fatal_error and keep using minxlib's X API will then keep receiving more fatal_error exceptions.

However, in this situation, it should be okay to throw a C++ fatal_error and let Boost.Python perform the necessary exception translation at the Python/C++ boundary because the exception is not generated from inside an Xlib callback.

This method allows the minxlib::display class and other minxlib clients to report a fatal error by throwing the exception rather than simply raising it in the Python interpreter.