Help/Core/Exception.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="824.48">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #0000bf}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #007300}
  18 p.p9 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #606060}
  19 span.s1 {font: 18.0px Helvetica}
  20 span.s2 {color: #0000bf}
  21 span.s3 {color: #0000bf}
  22 span.s4 {color: #0000bf}
  23 span.s5 {color: #606060}
  24 span.s6 {color: #007300}
  25 span.s7 {color: #000000}
  26 span.Apple-tab-span {white-space:pre}
  27 </style>
  28 </head>
  29 <body>
  30 <p class="p1"><span class="s1"><b>Exception<span class="Apple-tab-span">        </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></b></span><b>root error class</b></p>
  31 <p class="p2"><br></p>
  32 <p class="p1"><b>Inherits from: </b><a href="Object.html"><span class="s2"><b>Object</b></span></a></p>
  33 <p class="p2"><br></p>
  34 <p class="p1">The root of SuperCollider's error handling mechanism.</p>
  35 <p class="p2"><br></p>
  36 <p class="p1">Exception is an abstract class, defining basic error behavior. This class is not directly used in SuperCollider. Users may create subclasses of Exception to identify specific types of failure conditions.</p>
  37 <p class="p2"><br></p>
  38 <p class="p1">The built-in exception types are actually subclasses of <a href="Error.html"><span class="s3">Error</span></a> -- see its help file for the hierarchy.</p>
  39 <p class="p2"><br></p>
  40 <p class="p3"><b>Background: General exception handling</b></p>
  41 <p class="p2"><br></p>
  42 <p class="p1">An exception is any event that disrupts the normal execution flow of a program. In practice there is not much distinction between an exception and an error; in SuperCollider, we tend to speak of errors where other object-oriented languages (Java, C++) would use exception consistently.</p>
  43 <p class="p2"><br></p>
  44 <p class="p1">If a piece of code runs into an unexpected condition, it creates an exception object that holds information about the faulty condition, and then "throws" that object. From there, the interpreter unwinds backward through all the preceding stack frames looking for an exception handler that will "catch" the exception. The exception handler can take an alternate route to resolve the failure and continue normally; if this is not possible, it can re-throw the exception back to the previous stack frame. An exception that never gets caught causes execution to abort. In SuperCollider, this results in the standard error dump (see the <a href="../Language/Understanding-Errors.html"><span class="s3">Understanding-Errors</span></a> help file for details); in C++ or Java, the effect is catastrophic, causing the whole program to crash.</p>
  45 <p class="p2"><br></p>
  46 <p class="p1">Common syntax in other languages for exception handling is:</p>
  47 <p class="p2"><br></p>
  48 <p class="p4">try { ...code... }</p>
  49 <p class="p4">catch { ...exception handler... }</p>
  50 <p class="p2"><br></p>
  51 <p class="p1">Specific languages may have other variants. The SuperCollider compiler doesn't have room for the "catch" keyword, so the syntax is simpler:</p>
  52 <p class="p2"><br></p>
  53 <p class="p4">try { ...code... } { ...exception handler... };</p>
  54 <p class="p2"><br></p>
  55 <p class="p1">With "try," if the error cannot be handled, you have to re-throw the error explicitly:</p>
  56 <p class="p2"><br></p>
  57 <p class="p4">try { ...code... } { <span class="s4">|error|</span></p>
  58 <p class="p4"><span class="Apple-tab-span">     </span>if( test: can <span class="s4">I</span> handle the error? ) {</p>
  59 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>handle gracefully</p>
  60 <p class="p4"><span class="Apple-tab-span">     </span>} { error.throw }</p>
  61 <p class="p4">};</p>
  62 <p class="p2"><br></p>
  63 <p class="p1">SuperCollider includes a variant, borrowed from Scheme, in which the exception is always fatal, but the preceding code might have allocated some resources that need to be released before reporting the error. For example, you might open a file and do some processing on it that might encounter an error. Good practice is to close the file before the error halt, which you can do this way:</p>
  64 <p class="p2"><br></p>
  65 <p class="p4">file = <span class="s4">File</span>(path, <span class="s5">"r"</span>);</p>
  66 <p class="p4">protect {</p>
  67 <p class="p4"><span class="Apple-tab-span">     </span>work with the file here, which might cause an error</p>
  68 <p class="p4">} {</p>
  69 <p class="p4"><span class="Apple-tab-span">     </span>file.close;</p>
  70 <p class="p4">};</p>
  71 <p class="p2"><br></p>
  72 <p class="p1">With "protect," the second function will execute even if there is no error, and any error will be passed up the chain.</p>
  73 <p class="p2"><br></p>
  74 <p class="p1">In Java, you can catch specific classes of exception. You can simulate this usage with the following construction:</p>
  75 <p class="p2"><br></p>
  76 <p class="p5">// Java-style</p>
  77 <p class="p6"><br></p>
  78 <p class="p4">try {<span class="Apple-converted-space">  </span>}</p>
  79 <p class="p4">catch { <span class="s4">FileNotFoundException</span> e } { console.printLine(<span class="s5">"File not found: "</span> + e.path) }</p>
  80 <p class="p4">catch { <span class="s4">EmptyFileException</span> e } { console.printLine(<span class="s5">"File is empty: "</span> + e.path) };</p>
  81 <p class="p6"><br></p>
  82 <p class="p5">// SuperCollider-style (hypothetical; these specific exceptions do not exist in the main library</p>
  83 <p class="p6"><br></p>
  84 <p class="p4">try {<span class="Apple-converted-space">  </span>} { <span class="s4">|error|</span></p>
  85 <p class="p4"><span class="Apple-tab-span">     </span>switch(error.species.name)</p>
  86 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>{ <span class="s6">'FileNotFoundException'</span> } { postln(<span class="s5">"File not found:"</span> + e.path) }</p>
  87 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>{ <span class="s6">'EmptyFileException'</span> } { postln(<span class="s5">"File is empty:"</span> + e.path) }</p>
  88 <p class="p5"><span class="s7"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span>// default condition: unhandled exception, rethrow</p>
  89 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>{ error.throw }</p>
  90 <p class="p4">}</p>
  91 <p class="p2"><br></p>
  92 <p class="p1">Following is an example that recovers from a failed attempt to write into an immutable array, by re-attempting the write on a copy of the array.</p>
  93 <p class="p2"><br></p>
  94 <p class="p4">(</p>
  95 <p class="p7"><span class="s7">~inPlaceSub = { </span>|array, find, replace|</p>
  96 <p class="p4"><span class="Apple-tab-span">     </span>array.do({ <span class="s4">|item, i|</span></p>
  97 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>if(item == find) { array[i] = replace };</p>
  98 <p class="p4"><span class="Apple-tab-span">     </span>});</p>
  99 <p class="p4">};</p>
 100 <p class="p6"><br></p>
 101 <p class="p7"><span class="s7">~trySub = { </span>|array, find, replace|</p>
 102 <p class="p4"><span class="Apple-tab-span">     </span>try {</p>
 103 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>~inPlaceSub.(array, find, replace)</p>
 104 <p class="p7"><span class="s7"><span class="Apple-tab-span">    </span>} { </span>|error|</p>
 105 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>switch(error.species.name)</p>
 106 <p class="p8"><span class="s7"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>{ </span>'PrimitiveFailedError'<span class="s7"> } {</span></p>
 107 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>if(error.what.find(<span class="s5">"immutable"</span>).notNil) {</p>
 108 <p class="p9"><span class="s7"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span>"caught ImmutableError"<span class="s7">.postln;</span></p>
 109 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>~inPlaceSub.(array.copy, find, replace)</p>
 110 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>} { <span class="s5">"unknown primitive exception"</span>.postln; error.throw; }</p>
 111 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>}</p>
 112 <p class="p5"><span class="s7"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span>// default case: unhandled exception, should die so re-throw error</p>
 113 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>{ <span class="s5">"unknown exception"</span>.postln; error.throw; }</p>
 114 <p class="p4"><span class="Apple-tab-span">     </span>};</p>
 115 <p class="p4">};</p>
 116 <p class="p4">)</p>
 117 <p class="p6"><br></p>
 118 <p class="p5">// pass in a mutable array, OK</p>
 119 <p class="p4">~trySub.((0..9), 9, 19);</p>
 120 <p class="p6"><br></p>
 121 <p class="p5">// pass in a literal array, Immutable exception is caught and handled</p>
 122 <p class="p4">~trySub.(#[0, 1, 2, 3, 4, 5], 5, 6);</p>
 123 <p class="p6"><br></p>
 124 <p class="p5">// pass in a nonsense value, other exception is re-thrown</p>
 125 <p class="p4">~trySub.(10, 5, 6);</p>
 126 <p class="p2"><br></p>
 127 </body>
 128 </html>