PDFlib Text Extraction Toolkit (TET) Manual

3.2 C Binding
Exception handling. The TET API provides a mechanism for acting upon exceptions
thrown by the library in order to compensate for the lack of native exception handling
in the C language. Using the TET_TRY( ) and TET_CATCH( ) macros client code can be set up
such that a dedicated piece of code is invoked for error handling and cleanup when an
exception occurs. These macros set up two code sections: the try clause with code which
may throw an exception, and the catch clause with code which acts upon an exception.
If any of the API functions called in the try block throws an exception, program execution
will continue at the first statement of the catch block immediately. The following
rules must be obeyed in TET client code:
> TET_TRY( ) and TET_CATCH( ) must always be paired.
> TET_new( ) will never throw an exception; since a try block can only be started with a
valid TET object handle, TET_new( ) must be called outside of any try block.
> TET_delete( ) will never throw an exception, and therefore can safely be called outside
of any try block. It can also be called in a catch clause.
> Special care must be taken about variables that are used in both the try and catch
blocks. Since the compiler doesn’t know about the transfer of control from one block
to the other, it might produce inappropriate code (e.g., register variable optimizations)
in this situation.
Fortunately, there is a simple rule to avoid this kind of problem: Variables used in
both the try and catch blocks must be declared volatile. Using the volatile keyword signals
to the compiler that it must not apply dangerous optimizations to the variable.
> If a try block is left (e.g., with a return statement, thus bypassing the invocation of
the corresponding TET_CATCH( )), the TET_EXIT_TRY( ) macro must be called before the
return statement to inform the exception machinery.
> As in all TET language bindings document processing must stop when an exception
was thrown.
The following code fragment demonstrates these rules with the typical idiom for dealing
with TET exceptions in client code (a full sample can be found in the TET package):
volatile int pageno;
...
if ((tet = TET_new()) == (TET *) 0)
{
printf("out of memory\n");
return(2);
}
TET_TRY(tet)
{
for (pageno = 1; pageno