📄 bindings-errors.html
字号:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"><title>Error handling</title><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"><link rel="start" href="index.html" title="Cairo: A Vector Graphics Library"><link rel="up" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo"><link rel="prev" href="bindings-streams.html" title="Streams and File I/O"><link rel="next" href="bindings-patterns.html" title="Patterns"><meta name="generator" content="GTK-Doc V1.6 (XML mode)"><link rel="stylesheet" href="style.css" type="text/css"><link rel="part" href="pt01.html" title="Part I. Tutorial"><link rel="part" href="pt02.html" title="Part II. Reference"><link rel="chapter" href="Drawing.html" title="Drawing"><link rel="chapter" href="Fonts.html" title="Fonts"><link rel="chapter" href="Surfaces.html" title="Surfaces"><link rel="chapter" href="Support.html" title="Utilities"><link rel="index" href="ix01.html" title="Index"><link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="bindings-streams.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">Cairo: A Vector Graphics Library</th><td><a accesskey="n" href="bindings-patterns.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bindings-errors"></a>Error handling</h2></div></div></div><p> The error handling approach in C for Cairo has multiple elements: </p><div class="itemizedlist"><ul type="disc"><li><p> 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 <a href="cairo-cairo-t.html#cairo-status"><code class="function">status()</code></a>. </p></li><li><p> Constructors, rather than returning <code class="constant">NULL</code> on out-of-memory failure, return a special singleton object on which all operations do nothing. Retrieving the status of the singleton object returns <code class="constant">CAIRO_STATUS_NO_MEMORY</code> </p><p class="remark"><i><span class="remark"> Is this going to apply to <span class="type">cairo_surface_t</span> as well? </span></i></p><p class="remark"><i><span class="remark"> What about cairo_copy_path_data()? It's probably going to have to return <code class="constant">NULL</code>. </span></i></p></li><li><p> Errors propagate from object to object. Setting a pattern in an out-of-memory state as the source of a <span class="type">cairo_t</span> puts the type into an error state. </p></li></ul></div><p class="remark"><i><span class="remark">Much of the above is not yet implemented at the time of this writing</span></i></p><p> 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. </p><p> 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: </p><pre class="programlisting">/* Memory */ CAIRO_STATUS_NO_MEMORY,/* Programmer error */ CAIRO_STATUS_INVALID_RESTORECAIRO_STATUS_INVALID_POP_GROUPCAIRO_STATUS_NO_CURRENT_POINTCAIRO_STATUS_INVALID_MATRIXCAIRO_STATUS_NO_TARGET_SURFACECAIRO_STATUS_INVALID_STRINGCAIRO_STATUS_SURFACE_FINISHEDCAIRO_STATUS_BAD_NESTING/* Language binding implementation */CAIRO_STATUS_NULL_POINTERCAIRO_STATUS_INVALID_PATH_DATACAIRO_STATUS_SURFACE_TYPE_MISMATCH/* Other */ CAIRO_STATUS_READ_ERRORCAIRO_STATUS_WRITE_ERROR</pre><p> If we look at these, the <code class="constant">CAIRO_STATUS_NO_MEMORY</code> 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 <code class="constant">CAIRO_STATUS_READ_ERROR</code>, and <code class="constant">CAIRO_STATUS_WRITE_ERROR</code> can occur only in very specific places. (In fact, as described in <a href="bindings-streams.html" title="Streams and File I/O">the section called “Streams and File I/O”</a>, 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. </p></div></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -