New error handling in 3.2.0, and note to language binding writers

[Adam Goode]

In this message, I just wanted to point out a new feature that I
implemented in OpenSlide that I have wanted to do from the very
beginning: error detection and handling.

Previous versions of OpenSlide would assume that nothing would go wrong
during a call to openslide_read_region, but there are many things that
can go wrong. These include IO errors, corrupted images on disk,
incomplete or incorrect assumptions of the vendor formats, or internal
bugs in OpenSlide.

To fix this problem, I incorporated a similar error handling mechanism
to the cairo graphics library, described here:
http://www.cairographics.org/manual/cairo-error-status.html

The result of this change is that if something goes wrong in OpenSlide,
you can detect it now, rather than blindly carrying on and potentially
consuming or returning corrupted image data.

From C, you'll need to manually call openslide_get_error to check for
errors. The Java bindings to OpenSlide have been adjusted to
automatically check for errors after each operation, and throw an
exception if anything has gone wrong. Other language bindings should be
updated to do something similar.


Adam


P.S.

Here is how I described the new error handling in the OpenSlide
documentation:

Sometimes an unrecoverable error can occur that will invalidate the
OpenSlide object. (This is typically something like an I/O error or data
corruption.) When such an error happens in an OpenSlide object, the
object will move terminally into an error state.

While an object is in an error state, no OpenSlide functions will have
any effect on it except for openslide_close(). Functions that are
expected to return values will instead return an error value, typically
something like NULL or -1. openslide_read_region() will clear its
destination buffer instead of painting into it. openslide_get_error()
will return a non-NULL string containing an error message. See the
documentation for each function for details on what is returned in case
of error.

This style of error handling allows programs written in C to check for
errors only when convenient, because the error state is terminal and the
OpenSlide functions return harmlessly when there has been an error.

If writing wrappers for OpenSlide in languages that support exceptions,
it is recommended that the error state be checked after each call and
converted into an exception for that language.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 261 bytes
Desc: OpenPGP digital signature
Url : http://lists.andrew.cmu.edu/pipermail/openslide-users/attachments/20100604/0e4c40a4/attachment.bin