Public Types | Static Public Member Functions | Public Attributes | Protected Types | Protected Member Functions | List of all members
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 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 *)

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

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

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_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)

Construct a protocol_error object.

eThe XErrorEvent structure detailing the error.
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.

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)

Report an X protocol error.

eXErrorEvent structure containing protocol error details.

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.

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.

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