OpenGLEAN
OpenGLEAN User Support
Home page | Introduction | Documentation | Files | Examples | Proposals | Authors | Links


OpenGLEAN Development
Summary | CVS | (discussion via home page) | (contact via home page) | (suggestion box) | License | Todo | Bugs

API Function Failure Proposal

Summary

Provide OpenGLEAN clients with an option to gracefully handle errors.

Motivation

One of the mixed blessings of the GLUT family is that functions never fail (exception: glutCreateSubWindow() will return 0 if the parent is GLUT_OFFSCREEN); if they cannot succeed, the function simply exit(3)s safely. This is good for beginners who are trying to learn how to handle the API when it works. It's also good if you are writing a quick demonstration. But for serious work, one wants to find out about failure and handle it gracefully.

Graceful error handling is much desired, then. But, too, we don't want to force beginners and quick demos to deal with errors.

Solutions

At first glance, there appear to be two solution, with differing merits.

  1. Allow one to register an error-handler callback. OpenGLEAN would provide a default handler that prints an error message and exit(3)s. (There would presumably be a single handler for the entire library, since some API calls can be (or even must be) made without a current window. E.g., the first window that you open...)
  2. Allow one to inform OpenGLEAN that errors are to be handled by the client and to simply return select status values (e.g., 0 for window identifiers). Besides glutCreateSubWindow(), a handful of status-fetching functions can return special values (usually -1) already, to indicate "that request made no sense".

The former is more in keeping with the GLUT paradigm of callbacks, and would be easier to implement. The latter is more trouble to implement as every function that can fail must be modified to have a way out that cleans up any partial work properly before returning to the client. Much of the codebase, inherited indirectly from freeglut, is very sloppy about this and just does an unceremonious exit(3) when problems loom.

In reality, these two atlernatives seem to be just one. After all, if you don't exit(3), then you must return. But unless the error handler can cause the function to (successfully) restart, what else is there but to clean up and return an error status?

The Proposal.

So, the proposal is thus:

Allow the client to define an error handler.

A default handler is provided which will print error messages, and exit when appropriate.

When OpenGLEAN encounters an error (or perhaps even a warning of "inform" condition), it will invoke the handler with several pieces of information:

The message string must be text. The suggested behavior should probably be an enumerated integer; but if using a severity level, perhaps a floating point value between 0 and 1 would be more appropriate.

Because OpenGLEAN may have been in the midst of creating an object such as a window, it may not be safe to attempt to create a new OpenGLEAN resource (such as another window); and depending on why the current error handler is being invoked, it may not even be possible (perhaps the window system is refusing to open windows, for example). To the extent possible, OpenGLEAN should be cleaned up to permit clients to make attempts such as this, and things like the current window should probably be kept coherent---nor should post-handler code be too picky about OpenGLEAN state changes.

If the error handler returns, then the function that invoked the handler becomes responsible for cleaning up and trying to return a value. (Possibly allow the error handler to return a value to indicate whether OpenGLEAN should exit, print a warning, print an inform, or exit? This would let OpenGLEAN do library clean-up; calling exit(3) directly from the handler would make it harder for OpenGLEAN to intervene---though there already is that issue with normal client invocation of exit()...)

Some functions have a benign way to return "failure" already, such as glutGet(). Perhaps some of those do not need to be modified. By specifying a custom handler that simply returns to let the library return to the client, one can then do all of one's error handling by checking return codes. (At least in theory, pending work to make all failable library functions return something sensible for failure.)

Some function classes and their failure return codes include:





SourceForge.net Logo Supported in part by SourceForge.net.

Generated on Fri Sep 16 20:15:32 2005 for OpenGLEAN by doxygen 1.4.3
The OpenGLEAN project is hosted by olib.org and SourceForge.