Software: Apache/2.0.54 (Fedora). PHP/5.0.4 

uname -a: Linux mina-info.me 2.6.17-1.2142_FC4smp #1 SMP Tue Jul 11 22:57:02 EDT 2006 i686 

uid=48(apache) gid=48(apache) groups=48(apache)
context=system_u:system_r:httpd_sys_script_t 

Safe-mode: OFF (not secure)

/usr/share/doc/swig-1.3.24/Manual/   drwxr-xr-x
Free 5.15 GB of 27.03 GB (19.05%)
                            Encoder    Tools    Proc.    FTP brute    Sec.    SQL    PHP-code    Update    Feedback    Self remove    Logout    

Viewing file:     Customization.html (20 KB)      -rw-r--r--

11 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
  • Features and default arguments
  • Feature example

11.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 either %exception or %noexception 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.

11.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.

11.1.2 Exception handling with longjmp()

/* 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");
	}
}

11.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 {};

11.1.4 Defining different exception handlers

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 */

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

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

%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");
    }
}

%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"

11.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.

11.2 Object ownership and %newobject

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

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

%newobject blah;
Foo *blah();

%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
...

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);

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);

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);

11.3 Features and the %feature directive

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

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

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

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("except") Object::method { $action };
%feature("except") Object::method %{ $action %};
%feature("except") Object::method " $action ";
%feature("except","$action") Object::method;

%feature("name","value", attribute1="AttibuteValue1") symbol;
%feature("name", attribute1="AttibuteValue1") symbol {value};
%feature("name", attribute1="AttibuteValue1") symbol %{value%};
%feature("name", attribute1="AttibuteValue1") symbol "value";

%feature("except", throws="MyExceptionClass") Object::method { 
   try {
     $action
   } catch (...) {
     ... code to throw a MyExceptionClass Java exception ...
   }
};

Further details can be obtained from the Java exception handling section.

11.3.1 Features and default arguments

SWIG treats methods with default arguments as separate overloaded methods as detailed in the default arguments section. Any %feature targeting a method with default arguments will apply to all the extra overloaded methods that SWIG generates if the default arguments are specified in the feature. If the default arguments are not specified in the feature, then the feature will match that exact wrapper method only and not the extra overloaded methods that SWIG generates. For example:

%feature("except") void hello(int i=0, double d=0.0);
void hello(int i=0, double d=0.0);

will apply the feature to all three wrapper methods, that is:

void hello(int i, double d);
void hello(int i);
void hello();

If the default arguments are not specified in the feature:

%feature("except") void hello(int i, double d);
void hello(int i=0, double d=0.0);

then the feature will only apply to this wrapper method:

void hello(int i, double d);

and not these wrapper methods:

void hello(int i);
void hello();

If compactdefaultargs are being used, then the difference between specifying or not specifying default arguments in a feature is not applicable as just one wrapper is generated.

Compatibility note: The different behaviour of features specified with or without default arguments was introduced in SWIG-1.3.23 when the approach to wrapping methods with default arguments was changed.

11.3.2 Feature example

As has been shown earlier, the intended use for the %feature directive is as a highly flexible customization mechanism that can be used to annotate declarations with additional information for use by specific target language modules. Another example is in the Python module. You might use %feature to rewrite proxy/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);
}