Difference between revisions of "DIP33"

From D Wiki
Jump to: navigation, search
(Created page with "'''<span style="color: red">This DIP is currently under construction. Please come back later.</span>''' {| class="wikitable" !Title: !'''A new exception hierarchy''' |- |DIP...")
 
Line 59: Line 59:
  
 
== Top-level classes ==
 
== Top-level classes ==
 +
 +
Strictly speaking, <code>Throwable</code> is of course the (only) top-level exception class.  Here, however, we discuss its direct descendants, from which all other exception classes derive.
  
 
=== Error ===
 
=== Error ===
Line 66: Line 68:
  
 
<code>Error</code> and its subclasses are used to signal ''programming errors''.  If an <code>Error</code> is thrown, it means that there is something wrong with how the program is constructed.  Examples include array index out of bounds, invalid function arguments, etc.  <code>Error</code>s can always be avoided by design.
 
<code>Error</code> and its subclasses are used to signal ''programming errors''.  If an <code>Error</code> is thrown, it means that there is something wrong with how the program is constructed.  Examples include array index out of bounds, invalid function arguments, etc.  <code>Error</code>s can always be avoided by design.
 +
 +
In general, <code>Error</code>s should not be caught, primarily because they indicate that the program logic is compromised, and that the program may therefore be in an invalid state from which there is no recovery.  Furthermore, one cannot rely on them being thrown at all.  For example, <code>assert</code> statements and array bounds checks, which both trigger <code>Error</code>s, may be disabled by compiler switches.
  
 
=== Exception ===
 
=== Exception ===
Line 81: Line 85:
 
This exception is thrown on an attempt to allocate more memory than what is currently available for the program.  Strictly speaking, this is ''not'' an <code>Error</code>, as the programmer cannot reasonably be expected to check memory availability before each allocation.  However, is not desirable to catch it along with normal <code>Exception</code>s either, as an OOM condition requires special treatment.  Therefore, this DIP places <code>OutOfMemory</code> at the top level of the hierarchy.
 
This exception is thrown on an attempt to allocate more memory than what is currently available for the program.  Strictly speaking, this is ''not'' an <code>Error</code>, as the programmer cannot reasonably be expected to check memory availability before each allocation.  However, is not desirable to catch it along with normal <code>Exception</code>s either, as an OOM condition requires special treatment.  Therefore, this DIP places <code>OutOfMemory</code> at the top level of the hierarchy.
  
 +
== Errors ==
 +
 +
Here follows a more detailed description of the various <code>Error</code> subclasses.
 +
 +
=== AssertError ===
 +
<syntaxhighlight lang="d">
 +
class AssertError : Error { }
 +
</syntaxhighlight>
 +
 +
This error is thrown when an <code>assert</code> statement fails.
 +
 +
=== InvalidArgumentError ===
 +
<syntaxhighlight lang="d">
 +
class InvalidArgumentError : Error { }
 +
</syntaxhighlight>
 +
 +
This error is thrown when one or more function arguments are invalid.  Since it is an <code>Error</code>, it should be used only to signal
  
 
== Copyright ==
 
== Copyright ==

Revision as of 06:51, 1 April 2013

This DIP is currently under construction. Please come back later.

Title: A new exception hierarchy
DIP: 33
Version: 1
Status: Draft
Created: 2013-04-01
Last Modified: 2013-04-01
Author: Lars T. Kyllingstad
Links:

Abstract

This is a proposal for a new exception hierarchy for Druntime and Phobos.

Rationale

Overview

The following is an outline of the exceptions in the hierarchy, and how they are related to each other. Deeper levels are subclasses of those above.

  • Throwable
    • Error
      • AssertError
      • InvalidArgumentError
      • RangeError
    • Exception
      • ConversionException
      • Exception
      • EncodingException
      • FilesystemException
      • IOException
        • NetworkException
      • ParseException
        • DocParseException
      • ProcessException
      • SystemException
        • ErrnoException
        • WinAPIException
      • ThreadException
    • OutOfMemory


Top-level classes

Strictly speaking, Throwable is of course the (only) top-level exception class. Here, however, we discuss its direct descendants, from which all other exception classes derive.

Error

class Error : Throwable { }

Error and its subclasses are used to signal programming errors. If an Error is thrown, it means that there is something wrong with how the program is constructed. Examples include array index out of bounds, invalid function arguments, etc. Errors can always be avoided by design.

In general, Errors should not be caught, primarily because they indicate that the program logic is compromised, and that the program may therefore be in an invalid state from which there is no recovery. Furthermore, one cannot rely on them being thrown at all. For example, assert statements and array bounds checks, which both trigger Errors, may be disabled by compiler switches.

Exception

class Exception : Throwable { }

Exception and its descendants are used to signal normal runtime errors. These are exceptional circumstances that the programmer cannot be expected to avoid by design. Examples include file not found, problems with parsing a document, system errors, etc.

OutOfMemory

class OutOfMemory : Throwable { }

This exception is thrown on an attempt to allocate more memory than what is currently available for the program. Strictly speaking, this is not an Error, as the programmer cannot reasonably be expected to check memory availability before each allocation. However, is not desirable to catch it along with normal Exceptions either, as an OOM condition requires special treatment. Therefore, this DIP places OutOfMemory at the top level of the hierarchy.

Errors

Here follows a more detailed description of the various Error subclasses.

AssertError

class AssertError : Error { }

This error is thrown when an assert statement fails.

InvalidArgumentError

class InvalidArgumentError : Error { }

This error is thrown when one or more function arguments are invalid. Since it is an Error, it should be used only to signal

Copyright

This document has been placed in the Public Domain.