<html>
<head>
<title>TSE3 error handling</title>
</head>
<!--TSE3-BODY-->
<h1>TSE3 error handling</h1>
<h3>C++ exceptions</h3>
<p>
The TSE3 library uses exceptions to indicate unrecoverable errors.
The member functions which raise errors are clearly indicatated in the
documentation.
<p>
For this reason it is important that you write your application with
exception handlers (at the very least, enclose your <code>main</code>
function in a <code>try</code>/<code>catch</code> block, otherwise
any errors will lead to a segfault.
<p>
Every different TSE3 error is derived from a common base class,
<code>Error</code>. This class in turn derives from the standard library
exception class <code>exception</code>. It is up to you at what level
you catch any exception (i.e. specific subclass like
<code>PhraseListError</code>, all TSE3 errors with <code>Error</code> or
all library exceptions with <code>exception</code>).
<p>
The suggested format for catching errors is as shown below:
<p>
<pre>
try
{
// perform TSE3 activity that might throw an exception
phraseList.insert(newPhrase);
}
catch (const Error &e)
{
// do some error handling
cerr << "An error occured of type " << e.reason << endl;
exit(1);
}
</pre>
<p>
That is, catch by const reference. Of course, you will probably want
to catch a more specific exception type; in the above example a
<code>PhraseListError</code>.
<h3>Error reason codes</h3>
<p>
The base <code>Error</code> class includes a reason code parameter. You
may therefore distinguish the cause of the error in two ways, by
type of exception caught or by inspecting the reason code. Reason codes
are defined by the <code>ErrorCode</code> enum type.
<p>
The reason for this (seemingly redundant) reason code is simple: when
writing an application it is easier to work out which internationalised
error string to show to the user on reciept of an exception by indexing
into a table by reason code, rather that trying to convert an exception
type into a string.
<p>
The TSE3 library provides a set of standard English string representations
of each <code>ErrorCode</code> value.
<h3>General information</h3>
<p>
The error class definitions are located in the file
<code>tse3/Error.h</code>. The other TSE3 header files do not include
this directly, so if you need to handle TSE3 exceptions you will need to
<code>#include</code> this in your own code.
<p>
Note that some erroneous operations, like attempting to remove a
<code>Phrase</code> from the <code>PhraseList</code> which was never
inserted, result in no error being raised and the method returning silently.
Such occurences are clearly marked in the documentation.
<h3>Memory allocation errors</h3>
<p>
Since TSE3 error handling is based on the C++ exception mechanism, memory
allocation failure is also expected to raise an exception
(<code>std::bad_alloc</code>). For this reason, you will not see code that
checks the return value of <code>new</code> against the value zero in the
TSE3 source.
<p>
In fact, TSE3 does not even attempt to catch a <code>bad_alloc</code> since
if there is a memory leak, there really is no useful work that the
library can perform - it is probably too late to gracefully degrade. It
is up to the library user to catch any occurance of <code>bad_alloc</code>
and warn the application user, if possible.
<!--TSE3-FOOTER-->
</body>
</html>
distrib
>
Mandriva
>
9.2
>
i586
>
media
>
contrib
>
by-pkgid
>
6a008f60192f948b748b09d760d81244
>
files
>
39
