|
|
|
|
The error handling approach in C for Cairo has multiple elements:
When a method on an object fails, the object is put into
an error state. Subsequent operations on the object do
nothing. The status of the object can be queried with
a function like status().
Constructors, rather than
returning NULL on out-of-memory failure,
return a special singleton object on which all
operations do nothing. Retrieving the status of the
singleton object returns CAIRO_STATUS_NO_MEMORY
Is this going to apply to cairo_surface_t as well?
What about cairo_copy_path_data()? It's probably going to
have to return NULL.
Errors propagate from object to object. Setting a pattern in an out-of-memory state as the source of a cairo_t puts the type into an error state.
Much of the above is not yet implemented at the time of this writing
A language binding could copy the C approach, and for a language without exceptions, this is likely the right thing to do. However, for a language with exceptions, exposing a completely different style of error handling for cairo would be strange. So, instead, status should be checked after every call to cairo, and exceptions thrown as necessary.
One problem that can arise with this, in languages where handling exceptions is mandatory (like Java), is that almost every cairo function can result in a status being set, usually because of an out-of-memory condition. This could make cairo hard to use. To resolve this problem, let's classify then cairo status codes:
/* Memory */ CAIRO_STATUS_NO_MEMORY, /* Programmer error */ CAIRO_STATUS_INVALID_RESTORE CAIRO_STATUS_INVALID_POP_GROUP CAIRO_STATUS_NO_CURRENT_POINT CAIRO_STATUS_INVALID_MATRIX CAIRO_STATUS_NO_TARGET_SURFACE CAIRO_STATUS_INVALID_STRING CAIRO_STATUS_SURFACE_FINISHED CAIRO_STATUS_BAD_NESTING /* Language binding implementation */ CAIRO_STATUS_NULL_POINTER CAIRO_STATUS_INVALID_PATH_DATA CAIRO_STATUS_SURFACE_TYPE_MISMATCH /* Other */ CAIRO_STATUS_READ_ERROR CAIRO_STATUS_WRITE_ERROR
If we look at these, the
CAIRO_STATUS_NO_MEMORY
should map to the native out-of-memory exception, which could
happen at any point in any case. Most of the others indicate
programmer error, and handling them in user code would be
silly. These should be mapped into whatever the language uses
for assertion failures, rather than errors that are normally
handled. (In Java, a subclass of Error rather than Exception,
perhaps.) And CAIRO_STATUS_READ_ERROR,
and CAIRO_STATUS_WRITE_ERROR can occur
only in very specific places. (In fact, as described
in the section called “Streams and File I/O”, these errors may be
mapped into the language's native I/O error types.)
So, there really aren't exceptions that the programmer must
handle at most points in the Cairo API.