Customization Features

# 9 Customization Features

- Exception handling with %exception
  - Handling exceptions in C code
  - Exception handling with longjmp()
  - Handling C++ exceptions
  - Defining different exception handlers
  - Using The SWIG exception library
- Object ownership and %newobject
- Features and the %feature directive

In many cases, it is desirable to change the default wrapping of particular declarations in an interface. For example, you might want to provide hooks for catching C++ exceptions, add assertions, or provide hints to the underlying code generator. This chapter describes some of these customization techniques. First, a discussion of exception handling is presented. Then, a more general-purpose customization mechanism known as "features" is described.

## 9.1 Exception handling with %exception

The `%exception` directive allows you to define a general purpose exception handler. For example, you can specify the following:

>     %exception {
>         try {
>             $action
>         }
>         catch (RangeError) {
>             PyErr_SetString(PyExc_IndexError,"index out-of-bounds");
>             return NULL;
>         }
>     }

When defined, the code enclosed in braces is inserted directly into the low-level wrapper functions. The special symbol `$action` gets replaced with the actual operation to be performed (a function call, method invocation, attribute access, etc.). An exception handler remains in effect until it is explicitly deleted. This is done by using `%exception` with no code. For example:

>     %exception;   // Deletes any previously defined handler

Compatibility note: Previous versions of SWIG used a special directive `%except` for exception handling. That directive is still supported but is deprecated--`%exception` provides the same functionality, but is substantially more flexible.

### 9.1.1 Handling exceptions in C code

C has no formal exception handling mechanism so there are several approaches that might be used. A somewhat common technique is to simply set a special error code. For example:

>     /* File : except.c */

>     static char error_message[256];
>     static int error_status = 0;

>     void throw_exception(char *msg) {
>     	strncpy(error_message,msg,256);
>     	error_status = 1;
>     }

>     void clear_exception() {
>     	error_status = 0;
>     }
>     char *check_exception() {
>     	if (error_status) return error_message;
>     	else return NULL;
>     }

To use these functions, functions simply call `throw_exception()` to indicate an error occurred. For example :

>     double inv(double x) {
>     	if (x != 0) return 1.0/x;
>     	else {
>     		throw_exception("Division by zero");
>     		return 0;
>     	}
>     }

To catch the exception, you can write a simple exception handler such as the following (shown for Perl5) :

>     %exception {
>         char *err;
>         clear_exception();
>         $action
>         if ((err = check_exception())) {
>            croak(err);
>         }
>     }

In this case, when an error occurs, it is translated into a Perl error.

### 9.1.2 Exception handling with longjmp()

Exception handling can also be added to C code using the `<setjmp.h>` library. Here is a minimalistic implementation that relies on the C preprocessor :

>     /* File : except.c
>        Just the declaration of a few global variables we're going to use */

>     #include <setjmp.h>
>     jmp_buf exception_buffer;
>     int exception_status;

>     /* File : except.h */
>     #include <setjmp.h>
>     extern jmp_buf exception_buffer;
>     extern int exception_status;

>     #define try if ((exception_status = setjmp(exception_buffer)) == 0)
>     #define catch(val) else if (exception_status == val)
>     #define throw(val) longjmp(exception_buffer,val)
>     #define finally else

>     /* Exception codes */

>     #define RangeError     1
>     #define DivisionByZero 2
>     #define OutOfMemory    3

Now, within a C program, you can do the following :

>     double inv(double x) {
>     	if (x) return 1.0/x;
>     	else throw(DivisionByZero);
>     }

Finally, to create a SWIG exception handler, write the following :

>     %{
>     #include "except.h"
>     %}

>     %exception {
>     	try {
>     		$action
>     	} catch(RangeError) {
>     		croak("Range Error");
>     	} catch(DivisionByZero) {
>     		croak("Division by zero");
>     	} catch(OutOfMemory) {
>     		croak("Out of memory");
>     	} finally {
>     		croak("Unknown exception");
>     	}
>     }

Note: This implementation is only intended to illustrate the general idea. To make it work better, you'll need to modify it to handle nested `try` declarations.

### 9.1.3 Handling C++ exceptions

Handling C++ exceptions is also straightforward. For example:

>     %exception {
>     	try {
>     		$action
>     	} catch(RangeError) {
>     		croak("Range Error");
>     	} catch(DivisionByZero) {
>     		croak("Division by zero");
>     	} catch(OutOfMemory) {
>     		croak("Out of memory");
>     	} catch(...) {
>     		croak("Unknown exception");
>     	}
>     }

The exception types need to be declared as classes elsewhere, possibly in a header file :

>     class RangeError {};
>     class DivisionByZero {};
>     class OutOfMemory {};

### 9.1.4 Defining different exception handlers

By default, the `%exception` directive creates an exception handler that is used for all wrapper functions that follow it. Unless there is a well-defined (and simple) error handling mechanism in place, defining one universal exception handler may be unwieldy and result in excessive code bloat since the handler is inlined into each wrapper function.

To fix this, you can be more selective about how you use the `%exception` directive. One approach is to only place it around critical pieces of code. For example:

>     %exception {
>     	... your exception handler ...
>     }
>     /* Define critical operations that can throw exceptions here */

>     %exception;

>     /* Define non-critical operations that don't throw exceptions */

More precise control over exception handling can be obtained by attaching an exception handler to specific declaration name. For example:

>     %exception allocate {
>         try {
>             $action
>         }
>         catch (MemoryError) {
>             croak("Out of memory");
>         }
>     }

In this case, the exception handler is only attached to declarations named "allocate". This would include both global and member functions. The names supplied to `%exception` follow the same rules as for `%rename`. For example, if you wanted to define an exception handler for a specific class, you might write this:

>     %exception Object::allocate {
>         try {
>             $action
>         }
>         catch (MemoryError) {
>             croak("Out of memory");
>         }
>     }

When a class prefix is supplied, the exception handler is applied to the corresponding declaration in the specified class as well as for identically named functions appearing in derived classes.

`%exception` can even be used to pinpoint a precise declaration when overloading is used. For example:

>     %exception Object::allocate(int) {
>         try {
>             $action
>         }
>         catch (MemoryError) {
>             croak("Out of memory");
>         }
>     }

Attaching exceptions to specific declarations is a good way to reduce code bloat. It can also be a useful way to attach exceptions to specific parts of a header file. For example:

>     %module example
>     %{
>     #include "someheader.h"
>     %}

>     // Define a few exception handlers for specific declarations
>     %exception Object::allocate(int) {
>         try {
>             $action
>         }
>         catch (MemoryError) {
>             croak("Out of memory");
>         }
>     }

>     %exception Object::getitem {
>         try {
>            $action
>         }
>         catch (RangeError) {
>            croak("Index out of range");
>         }
>     }
>     ...
>     // Read a raw header file
>     %include "someheader.h"

Compatibility note: The `%exception` directive replaces the functionality provided by the deprecated "except" typemap. The typemap would allow exceptions to be thrown in the target language based on the return type of a function and was intended to be a mechanism for pinpointing specific declarations. However, it never really worked that well and the new %exception directive is much better.

### 9.1.5 Using The SWIG exception library

The `exception.i` library file provides support for creating language independent exceptions in your interfaces. To use it, simply put an "`%include exception.i`" in your interface file. This creates a function`SWIG_exception()` that can be used to raise common scripting language exceptions in a portable manner. For example :

>     // Language independent exception handler
>     %include exception.i

>     %exception {
>         try {
>             $action
>         } catch(RangeError) {
>             SWIG_exception(SWIG_ValueError, "Range Error");
>         } catch(DivisionByZero) {
>             SWIG_exception(SWIG_DivisionByZero, "Division by zero");
>         } catch(OutOfMemory) {
>             SWIG_exception(SWIG_MemoryError, "Out of memory");
>         } catch(...) {
>             SWIG_exception(SWIG_RuntimeError,"Unknown exception");
>         }
>     }

As arguments, `SWIG_exception()` takes an error type code (an integer) and an error message string. The currently supported error types are :

>     SWIG_MemoryError
>     SWIG_IOError
>     SWIG_RuntimeError
>     SWIG_IndexError
>     SWIG_TypeError
>     SWIG_DivisionByZero
>     SWIG_OverflowError
>     SWIG_SyntaxError
>     SWIG_ValueError
>     SWIG_SystemError
>     SWIG_UnknownError

Since the `SWIG_exception()` function is defined at the C-level it can be used elsewhere in SWIG. This includes typemaps and helper functions.

## 9.2 Object ownership and %newobject

A common problem in some applications is managing proper ownership of objects. For example, consider a function like this:

>     Foo *blah() {
>        Foo *f = new Foo();
>        return f;
>     }

If you wrap the function `blah()`, SWIG has no idea that the return value is a newly allocated object. As a result, the resulting extension module may produce a memory leak (SWIG is conservative and will never delete objects unless it knows for certain that the returned object was newly created).

To fix this, you can provide an extra hint to the code generator using the `%newobject` directive. For example:

>     %newobject blah;
>     Foo *blah();

`%newobject` works exactly like `%rename` and `%exception`. In other words, you can attach it to class members and parameterized declarations as before. For example:

>     %newobject ::blah();                   // Only applies to global blah
>     %newobject Object::blah(int,double);   // Only blah(int,double) in Object
>     %newobject *::copy;                    // Copy method in all classes
>     ...

When `%newobject` is supplied, many language modules will arrange to take ownership of the return value. This allows the value to be automatically garbage-collected when it is no longer in use. However, this depends entirely on the target language (a language module may choose to ignore the `%newobject` directive).

Closely related to `%newobject` is a special typemap. The "newfree" typemap can be used to deallocate a newly allocated return value. It is only available on methods for which `%newobject` has been applied and is commonly used to clean-up string results. For example:

>     %typemap(newfree) char * "free($1);";
>     ...
>     %newobject strdup;
>     ...
>     char *strdup(const char *s);

In this case, the result of the function is a string in the target language. Since this string is a copy of the original result, the data returned by `strdup()` is no longer needed. The "newfree" typemap in the example simply releases this memory.

Compatibility note: Previous versions of SWIG had a special `%new` directive. However, unlike `%newobject`, it only applied to the next declaration. For example:

>     %new char *strdup(const char *s);

For now this is still supported but is deprecated.

How to shoot yourself in the foot: The `%newobject` directive is not a declaration modifier like the old `%new` directive. Don't write code like this:

>     %newobject
>     char *strdup(const char *s);

The results might not be what you expect.

## 9.3 Features and the %feature directive

Both `%exception` and `%newobject` are examples of a more general purpose customization mechanism known as "features." A feature is simply a user-definable property that is attached to specific declarations in an interface file. Features are attached using the `%feature` directive. For example:

>     %feature("except") Object::allocate {
>         try {
>             $action
>         }
>         catch (MemoryError) {
>             croak("Out of memory");
>         }
>     }

>     %feature("new","1") *::copy;

In fact, the `%exception` and `%newobject` directives are really nothing more than macros involving `%feature`:

>     #define %exception %feature("except")
>     #define %newobject %feature("new","1")

The `%feature` directive follows the same name matching rules as the `%rename` directive (which is in fact just a special form of `%feature`). This means that features can be applied with pinpoint accuracy to specific declarations if needed.

When a feature is defined, it is given a name and a value. Most commonly, the value is supplied after the declaration name as shown for the `"except"` example above. However, if the feature is simple, a value might be supplied as an extra argument as shown for the `"new"` feature.

A feature stays in effect until it is explicitly disabled. A feature is disabled by supplying a `%feature` directive with no value. For example:

>     %feature("except") Object::allocate;    // Removes any previously defined feature

If no declaration name is given, a global feature is defined. This feature is then attached to every declaration that follows. This is how global exception handlers are defined. For example:

>     /* Define a global exception handler */
>     %feature("except") {
>        try {
>          $action
>        }
>        ...
>     }

>     ... bunch of declarations ...

>     /* Disable the exception handler */
>     %feature("except");

`%feature` is a relatively new addition to SWIG that was not added until version 1.3.10. Its intended use is as a highly flexible customization mechanism that can be used to annotate declarations with additional information for use by specific target language modules. For example, in the Python module, you might use `%feature` to rewrite shadow class code as follows:

>     %module example
>     %rename(bar_id) bar(int,double);

>     // Rewrite bar() to allow some nice overloading

>     %feature("shadow") Foo::bar(int) %{
>     def bar(*args):
>         if len(args) == 3:
>              return apply(examplec.Foo_bar_id,args)
>         return apply(examplec.Foo_bar,args)
>     %}

>     class Foo {
>     public:
>         int bar(int x);
>         int bar(int x, double y);
>     }

As of this writing, `%feature` is still experimental. Further details of its use will be described in the documentation for specific language modules.