Error handling: Cairo: A Vector Graphics Library

+Error handling

+ 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. +