minxlib::protocol_error Struct Reference

A base class to indicate X protocol errors. More...

#include <exception.hh>

Public Types
enum	failed_request_reason
	Names for different error codes. More...

Static Public Member Functions
static void	raise (const XErrorEvent *e)
	Report an X protocol error. More...
Static Public Member Functions inherited from minxlib::exception
static void	pythonize ()
	Expose exception interface to Python. More...

Public Attributes
const unsigned long	serial
	Serial number of failed request. More...
const unsigned long	error_code
	Error code of failed request. More...
const unsigned long	request_code
	Major opcode of failed request. More...
const unsigned long	minor_code
	Minor opcode of failed request. More...
const unsigned long	resource_id
	Resource ID associated with failed request. More...

Protected Types
typedef protocol_error *(*	cr_func )(const XErrorEvent *)
	Signature of factory function. More...
typedef factory_map< unsigned long, cr_func, py_func >	registry
	Registry of factory functions for instantiating subclasses. More...
Protected Types inherited from minxlib::exception
typedef void(*	py_func )()
	Signature for Pythonize functions. More...

Protected Member Functions
	protocol_error (const XErrorEvent *e)
	Construct a protocol_error object. More...
Protected Member Functions inherited from minxlib::exception
	exception (const std::string &msg)
	Construct base exception object. More...

Additional Inherited Members
Public Member Functions inherited from minxlib::exception
virtual	~exception () throw ()
	Virtual destructor. 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

A base class to indicate X protocol errors.

When an X protocol request fails, minxlib will notify its Python clients by raising an instance of this class or one of its subclasses 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.

Member Typedef Documentation

typedef protocol_error*(* minxlib::protocol_error::cr_func)(const XErrorEvent *)

protected

Signature of factory function.

Each protocol_error subclass will be instantiated by a factory function that takes an XErrorEvent and returns an instance of the subclass upcast to minxlib::protocol_error.

typedef factory_map<unsigned long, cr_func, py_func> minxlib::protocol_error::registry

protected

Registry of factory functions for instantiating subclasses.

This type defines the protocol_error object factory's registry, which maps the X protocol error codes to the corresponding protocol_error subclass's factory function. Additionally, we store the Pythonize functions in the registry as well, which obviates the need for another map to hold them.

For the factory pattern to work, protocol_error subclasses must define a static boolean data member and, in its initializer, call protocol_error::registry::add(), passing it the appropriate X protocol error code, the subclass's factory function, and its Pythonize function.

Member Enumeration Documentation

enum minxlib::protocol_error::failed_request_reason

Names for different error codes.

This enumeration specifies the reason for a failed protocol request. It is simply the Xlib names converted from CamelCase to a saner naming convention:

minxlib	Xlib
bad_access	BadAccess
bad_alloc	BadAlloc
bad_atom	BadAtom
bad_color	BadColor
bad_cursor	BadCursor
bad_drawable	BadDrawable
bad_font	BadFont
bad_gc	BadGC
bad_id_choice	BadIDChoice
bad_implementation	BadImplementation
bad_length	BadLength
bad_match	BadMatch
bad_name	BadName
bad_pixmap	BadPixmap
bad_request	BadRequest
bad_value	BadValue
bad_window	BadWindow

Constructor & Destructor Documentation

minxlib::protocol_error::protocol_error ( const XErrorEvent *  e)

protected

Construct a protocol_error object.

Parameters

e	The XErrorEvent structure detailing the error.

Returns

Properly constructed protocol_error object.

This class is meant to be used by the Xlib error handler, which is implemented in minxlib by display::report_protocol_errors(). That function will be passed an XErrorEvent by Xlib, which it will, in turn, pass to this constructor. The constructor converts the error to human-readable form and also records the various fields in the protocol_error object it creates.

Note

This is a protected constructor because protocol_error instances are meant to be created using the create() factory method and only subclasses may initialize the base.

Member Function Documentation

static void minxlib::protocol_error::raise ( const XErrorEvent *  e)

static

Report an X protocol error.

Parameters

e	XErrorEvent structure containing protocol error details.

Returns

Nothing.

This function raises a minxlib.protocol_error to inform the Python side of Minx of various X-related errors such as attempting to set the input focus on a non-existent or unmapped window.

Most X protocol errors will be reported using minxlib.protocol_error. However, certain protocol errors have specific types that are derived from this class. The Python side of Minx can use these subclass types to easily catch and handle specific errors.

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. This is because throwing a C++ exception from inside an Xlib callback makes the Minx process enter some sort of infinite loop and consume 100% CPU. Basically, interaction between C and C++ with regards to exceptions and stack unwinding is ill-defined (or, at least when it comes to Xlib and minxlib, it is).

Member Data Documentation

const unsigned long minxlib::protocol_error::error_code

Error code of failed request.

This value specifies the reason for the failed request and will be one of the values of the failed_request_reason enumeration.

const unsigned long minxlib::protocol_error::minor_code

Minor opcode of failed request.

No idea what the hell this is. Not used in Minx anyway.

const unsigned long minxlib::protocol_error::request_code

Major opcode of failed request.

This member is the opcode of the failed X protocol request as defined in X11/Xproto.h.

minxlib does not provide an enumeration for the different protocol request codes. However, some of the request codes are made available as specific exception types derived from protocol_error. Those that are not wrapped thusly can only be gleaned from the string representation of protocol_error, which will contain an appropriate name for the request code.

const unsigned long minxlib::protocol_error::resource_id

Resource ID associated with failed request.

This member specifies the particular X object (window, GC, atom, whatever) that was involved with the protocol request that failed.

For example, if we try to set the input focus to a window that has been unmapped or destroyed, the resulting protocol_error's resource_id will be the ID of that window. Since the X protocol is asynchronous, handling protocol_error exceptions and using this ID is about the only way to keep the window manager's internal state in-sync with the X server's internal state.

const unsigned long minxlib::protocol_error::serial

Serial number of failed request.

All requests to the X server have a serial number that starts at one. This field contains the request number corresponding to the protocol request that failed, thus, resulting in a protocol_error.

Note

This is a low-level detail of the X protocol and is not really used in Minx.