mirror of https://github.com/swig/swig
598 lines
24 KiB
HTML
598 lines
24 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>SWIG and Chicken</title>
|
|
<link rel="stylesheet" type="text/css" href="style.css">
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
|
|
<H1><a name="Chicken">23 SWIG and Chicken</a></H1>
|
|
<!-- INDEX -->
|
|
<div class="sectiontoc">
|
|
<ul>
|
|
<li><a href="#Chicken_nn2">Preliminaries</a>
|
|
<ul>
|
|
<li><a href="#Chicken_nn3">Running SWIG in C mode</a>
|
|
<li><a href="#Chicken_nn4">Running SWIG in C++ mode</a>
|
|
</ul>
|
|
<li><a href="#Chicken_nn5">Code Generation</a>
|
|
<ul>
|
|
<li><a href="#Chicken_nn6">Naming Conventions</a>
|
|
<li><a href="#Chicken_nn7">Modules</a>
|
|
<li><a href="#Chicken_nn8">Constants and Variables</a>
|
|
<li><a href="#Chicken_nn9">Functions</a>
|
|
<li><a href="#Chicken_nn10">Exceptions</a>
|
|
</ul>
|
|
<li><a href="#Chicken_nn11">TinyCLOS</a>
|
|
<li><a href="#Chicken_nn12">Linkage</a>
|
|
<ul>
|
|
<li><a href="#Chicken_nn13">Static binary or shared library linked at compile time</a>
|
|
<li><a href="#Chicken_nn14">Building chicken extension libraries</a>
|
|
<li><a href="#Chicken_nn15">Linking multiple SWIG modules with TinyCLOS</a>
|
|
</ul>
|
|
<li><a href="#Chicken_nn16">Typemaps</a>
|
|
<li><a href="#Chicken_nn17">Pointers</a>
|
|
<ul>
|
|
<li><a href="#Chicken_collection">Garbage collection</a>
|
|
</ul>
|
|
<li><a href="#Chicken_nn18">Unsupported features and known problems</a>
|
|
<ul>
|
|
<li><a href="#Chicken_nn19">TinyCLOS problems with Chicken version <= 1.92</a>
|
|
</ul>
|
|
</ul>
|
|
</div>
|
|
<!-- INDEX -->
|
|
|
|
|
|
|
|
<p>
|
|
This chapter describes SWIG's support of CHICKEN. CHICKEN is a
|
|
Scheme-to-C compiler supporting most of the language features as
|
|
defined in the <i>Revised^5 Report on Scheme</i>. Its main
|
|
attributes are that it
|
|
</p>
|
|
|
|
<ol>
|
|
<li>generates portable C code</li>
|
|
<li>includes a customizable interpreter</li>
|
|
<li>links to C libraries with a simple Foreign Function Interface</li>
|
|
<li>supports full tail-recursion and first-class continuations</li>
|
|
</ol>
|
|
|
|
<p>
|
|
When confronted with a large C library, CHICKEN users can use
|
|
SWIG to generate CHICKEN wrappers for the C library. However,
|
|
the real advantages of using SWIG with CHICKEN are its
|
|
<strong>support for C++</strong> -- object-oriented code is
|
|
difficult to wrap by hand in CHICKEN -- and its <strong>typed
|
|
pointer representation</strong>, essential for C and C++
|
|
libraries involving structures or classes.
|
|
|
|
</p>
|
|
|
|
<H2><a name="Chicken_nn2">23.1 Preliminaries</a></H2>
|
|
|
|
|
|
<p>
|
|
CHICKEN support was introduced to SWIG in version 1.3.18. SWIG
|
|
relies on some recent additions to CHICKEN, which are only
|
|
present in releases of CHICKEN with version number
|
|
<strong>greater than or equal to 1.89</strong>.
|
|
To use a chicken version between 1.40 and 1.89, see the <a href="#Chicken_collection">Garbage collection</a>
|
|
section below.
|
|
</p>
|
|
|
|
<p>
|
|
You may want to look at any of the examples in Examples/chicken/
|
|
directory for the basic steps to run SWIG CHICKEN.
|
|
</p>
|
|
|
|
<H3><a name="Chicken_nn3">23.1.1 Running SWIG in C mode</a></H3>
|
|
|
|
|
|
<p>
|
|
To run SWIG CHICKEN in C mode, use
|
|
the -chicken option.
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>% swig -chicken example.i</pre>
|
|
</div>
|
|
|
|
<p>
|
|
To allow the wrapper to take advantage of future CHICKEN code
|
|
generation improvements, part of the wrapper is direct CHICKEN
|
|
function calls (<tt>example_wrap.c</tt>) and part is CHICKEN
|
|
Scheme (<tt>example.scm</tt>). The basic Scheme code must
|
|
be compiled to C using your system's CHICKEN compiler or
|
|
both files can be compiled directly using the much simpler <tt>csc</tt>.
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
% chicken example.scm -output-file oexample.c
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
So for the C mode of SWIG CHICKEN, <tt>example_wrap.c</tt> and
|
|
<tt>oexample.c</tt> are the files that must be compiled to
|
|
object files and linked into your project.
|
|
</p>
|
|
|
|
<H3><a name="Chicken_nn4">23.1.2 Running SWIG in C++ mode</a></H3>
|
|
|
|
|
|
<p>
|
|
To run SWIG CHICKEN in C++ mode, use
|
|
the -chicken -c++ option.
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>% swig -chicken -c++ example.i</pre>
|
|
</div>
|
|
|
|
<p>
|
|
This will generate <tt>example_wrap.cxx</tt> and
|
|
<tt>example.scm</tt>. The basic Scheme code must be
|
|
compiled to C using your system's CHICKEN compiler or
|
|
both files can be compiled directly using the much simpler <tt>csc</tt>.
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>% chicken example.scm -output-file oexample.c</pre>
|
|
</div>
|
|
|
|
<p>
|
|
So for the C++ mode of SWIG CHICKEN, <tt>example_wrap.cxx</tt>
|
|
and <tt>oexample.c</tt> are the files that must be compiled to
|
|
object files and linked into your project.
|
|
</p>
|
|
|
|
<H2><a name="Chicken_nn5">23.2 Code Generation</a></H2>
|
|
|
|
|
|
<H3><a name="Chicken_nn6">23.2.1 Naming Conventions</a></H3>
|
|
|
|
|
|
<p>
|
|
Given a C variable, function or constant declaration named
|
|
<tt>Foo_Bar</tt>, the declaration will be available
|
|
in CHICKEN as an identifier ending with
|
|
<tt>Foo-Bar</tt>. That is, an underscore is converted
|
|
to a dash.
|
|
</p>
|
|
|
|
<p>
|
|
You may control what the CHICKEN identifier will be by using the
|
|
<tt>%rename</tt> SWIG directive in the SWIG interface file.
|
|
</p>
|
|
|
|
<H3><a name="Chicken_nn7">23.2.2 Modules</a></H3>
|
|
|
|
|
|
<p>
|
|
The name of the module must be declared one of two ways:
|
|
<ul>
|
|
<li>Placing <tt>%module example</tt> in the SWIG interface
|
|
file.</li>
|
|
<li>Using <tt>-module example</tt> on the SWIG command
|
|
line.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
The generated example.scm file then exports <code>(declare (unit modulename))</code>.
|
|
If you do not want SWIG to export the <code>(declare (unit modulename))</code>, pass
|
|
the -nounit option to SWIG.
|
|
|
|
<p>
|
|
CHICKEN will be able to access the module using the <code>(declare
|
|
(uses <i>modulename</i>))</code> CHICKEN Scheme form.
|
|
</p>
|
|
|
|
<H3><a name="Chicken_nn8">23.2.3 Constants and Variables</a></H3>
|
|
|
|
|
|
<p>
|
|
Constants may be created using any of the four constructs in
|
|
the interface file:
|
|
</p>
|
|
<ol>
|
|
<li><code>#define MYCONSTANT1 ...</code></li>
|
|
<li><code>%constant int MYCONSTANT2 = ...</code></li>
|
|
<li><code>const int MYCONSTANT3 = ...</code></li>
|
|
<li><code>enum { MYCONSTANT4 = ... };</code></li>
|
|
</ol>
|
|
|
|
<p>
|
|
In all cases, the constants may be accessed from within CHICKEN
|
|
using the form <tt>(MYCONSTANT1)</tt>; that is, the constants
|
|
may be accessed using the read-only parameter form.
|
|
</p>
|
|
|
|
<p>
|
|
Variables are accessed using the full parameter form.
|
|
For example, to set the C variable "int my_variable;", use the
|
|
Scheme form <tt>(my-variable 2345)</tt>. To get the C variable,
|
|
use <tt>(my-variable)</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
The <tt>%feature("constasvar")</tt> can be applied to any constant
|
|
or immutable variable. Instead of exporting the constant as
|
|
a function that must be called, the constant will appear as a
|
|
scheme variable. This causes the generated .scm file to just contain the code
|
|
<tt>(set! MYCONSTANT1 (MYCONSTANT1))</tt>. See
|
|
<a href="Customization.html#Customization_features">Features and the %feature directive</a>
|
|
for info on how to apply the %feature.
|
|
</p>
|
|
|
|
<H3><a name="Chicken_nn9">23.2.4 Functions</a></H3>
|
|
|
|
|
|
<p>
|
|
C functions declared in the SWIG interface file will have
|
|
corresponding CHICKEN Scheme procedures. For example, the C
|
|
function "int sqrt(double x);" will be available using the
|
|
Scheme form <tt>(sqrt 2345.0)</tt>. A <code>void</code> return
|
|
value will give C_SCHEME_UNDEFINED as a result.
|
|
</p>
|
|
<p>
|
|
A function may return more than one value by using the
|
|
<code>OUTPUT</code> specifier (see Lib/chicken/typemaps.i).
|
|
They will be returned as multiple values using <code>(values)</code> if there is more than one
|
|
result (that is, a non-void return value and at least one argout
|
|
parameter, or a void return value and at least two argout
|
|
parameters). The return values can then be accessed with <code>(call-with-values)</code>.
|
|
</p>
|
|
|
|
<H3><a name="Chicken_nn10">23.2.5 Exceptions</a></H3>
|
|
|
|
|
|
<p>The SWIG chicken module has support for exceptions thrown from
|
|
C or C++ code to be caught in scheme.
|
|
See <a href="Customization.html#Customization_exception">Exception handling with %exception</a>
|
|
for more information about declaring exceptions in the interface file.
|
|
</p>
|
|
|
|
<p>Chicken supports both the <code>SWIG_exception(int code, const char *msg)</code> interface
|
|
as well as a <code>SWIG_ThrowException(C_word val)</code> function for throwing exceptions from
|
|
inside the %exception blocks. <code>SWIG_exception</code> will throw a list consisting of the code
|
|
(as an integer) and the message. Both of these will throw an exception using <code>(abort)</code>,
|
|
which can be handled by <code>(handle-exceptions)</code>. See
|
|
the Chicken manual on Exceptions
|
|
and <a href="http://srfi.schemers.org/srfi-12/srfi-12.html">SFRI-12</a>. Since the exception values are thrown
|
|
directly, if <code>(condition-case)</code> is used to catch an exception the exception will come through in the <code>val ()</code> case.
|
|
</p>
|
|
|
|
<p>The following simple module</p>
|
|
|
|
<div class="code"><pre>
|
|
%module exception_test
|
|
|
|
%inline %{
|
|
void test_throw(int i) throws (int) {
|
|
if (i == 1) throw 15;
|
|
}
|
|
%}
|
|
</pre></div>
|
|
|
|
<p>could be run with</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
(handle-exceptions exvar
|
|
(if (= exvar 15)
|
|
(print "Correct!")
|
|
(print "Threw something else " exvar))
|
|
(test-throw 1))
|
|
</pre></div>
|
|
|
|
|
|
<H2><a name="Chicken_nn11">23.3 TinyCLOS</a></H2>
|
|
|
|
|
|
<p>
|
|
The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as:
|
|
"Tiny CLOS is a Scheme implementation of a 'kernelized' CLOS, with a
|
|
metaobject protocol. The implementation is even simpler than
|
|
the simple CLOS found in 'The Art of the Metaobject Protocol',
|
|
weighing in at around 850 lines of code, including (some)
|
|
comments and documentation."
|
|
</p>
|
|
|
|
<p>
|
|
Almost all good Scheme books describe how to use metaobjects and
|
|
generic procedures to implement an object-oriented Scheme
|
|
system. Please consult a Scheme book if you are unfamiliar
|
|
with the concept.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
CHICKEN has a modified version of TinyCLOS, which SWIG CHICKEN
|
|
uses if the -proxy argument is given. If -proxy is passed, then
|
|
the generated example.scm file will contain TinyCLOS class definitions.
|
|
A class named Foo is declared as <Foo>, and each member variable
|
|
is allocated a slot. Member functions are exported as generic functions.
|
|
|
|
<p>
|
|
|
|
Primitive symbols and functions (the interface that would be presented if
|
|
-proxy was not passed) are hidden and no longer accessible. If the -unhideprimitive
|
|
command line argument is passed to SWIG, then the primitive symbols will be
|
|
available, but each will be prefixed by the string "primitive:"
|
|
|
|
<p>
|
|
|
|
The exported symbol names can be controlled with the -closprefix and -useclassprefix arguments.
|
|
If -useclassprefix is passed to SWIG, every member function will be generated with the class name
|
|
as a prefix. If the -closprefix mymod: argument is passed to SWIG, then the exported functions will
|
|
be prefixed by the string "mymod:". If -useclassprefix is passed, -closprefix is ignored.
|
|
|
|
</p>
|
|
|
|
<H2><a name="Chicken_nn12">23.4 Linkage</a></H2>
|
|
|
|
|
|
<p>
|
|
Please refer to <em>CHICKEN - A practical and portable Scheme
|
|
system - User's manual</em> for detailed help on how to link
|
|
object files to create a CHICKEN Scheme program. Briefly, to
|
|
link object files, be sure to add <tt>`chicken-config
|
|
-extra-libs -libs`</tt> or <tt>`chicken-config -shared
|
|
-extra-libs -libs`</tt>to your linker options. Use the
|
|
<tt>-shared</tt> option if you want to create a dynamically
|
|
loadable module. You might also want to use the much simpler
|
|
<tt>csc</tt> or <tt>csc.bat</tt>.
|
|
</p>
|
|
|
|
<p>Each scheme file that is generated
|
|
by SWIG contains <code>(declare (uses <i>modname</i>))</code>. This means that to load the
|
|
module from scheme code, the code must include <code>(declare (uses <i>modname</i>))</code>.
|
|
</p>
|
|
|
|
|
|
<H3><a name="Chicken_nn13">23.4.1 Static binary or shared library linked at compile time</a></H3>
|
|
|
|
|
|
<p>We can easily use csc to build a static binary.</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
$ swig -chicken example.i
|
|
$ csc -v example.scm example_impl.c example_wrap.c test_script.scm -o example
|
|
$ ./example
|
|
</pre>
|
|
</div>
|
|
|
|
<p>Similar to the above, any number of <tt>module.scm</tt> files could be compiled
|
|
into a shared library, and then that shared library linked when compiling the
|
|
main application.</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
$ swig -chicken example.i
|
|
$ csc -sv example.scm example_wrap.c example_impl.c -o example.so
|
|
</pre>
|
|
</div>
|
|
|
|
<p>The <tt>example.so</tt> file can then linked with <tt>test_script.scm</tt> when it
|
|
is compiled, in which case <tt>test_script.scm</tt> must have <code>(declare (uses example))</code>.
|
|
Multiple SWIG modules could have been linked into <tt>example.so</tt> and each
|
|
one accessed with a <code>(declare (uses ... ))</code>.
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
$ csc -v test_script.scm -lexample
|
|
</pre>
|
|
</div>
|
|
|
|
<p>An alternative is that the test_script.scm can have the code <code>(load-library 'example "example.so")</code>,
|
|
in which case the test script does not need to be linked with example.so. The test_script.scm file can then
|
|
be run with <tt>csi</tt>.
|
|
</p>
|
|
|
|
<H3><a name="Chicken_nn14">23.4.2 Building chicken extension libraries</a></H3>
|
|
|
|
|
|
<p>Building a shared library like in the above section only works if the library
|
|
is linked at compile time with a script containing <code>(declare (uses ...))</code> or is
|
|
loaded explicitly with <code>(load-library 'example "example.so")</code>. It is
|
|
not the format that CHICKEN expects for extension libraries and eggs. The problem is the
|
|
<code>(declare (unit <i>modname</i>))</code> inside the <tt>modname.scm</tt> file. There are
|
|
two possible solutions to this.</p>
|
|
|
|
<p>First, SWIG accepts a <tt>-nounit</tt> argument, in which case the <code>(declare (unit <i>modname</i>))</code>
|
|
is not generated. Then, the <tt>modname.scm</tt> and <tt>modname_wrap.c</tt> files <b>must</b> be compiled into
|
|
their own shared library.</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
$ csc -sv modname.scm modname_wrap.c modname_impl.c -o modname.so
|
|
</pre>
|
|
</div>
|
|
|
|
<p>This library can then be loaded by scheme code with the <code>(require 'modname)</code> function.
|
|
See the
|
|
Loading-extension-libraries in the eval unit inside the CHICKEN manual for more information.</p>
|
|
|
|
<p>Another alternative is to run SWIG normally and create a scheme file that contains <code>(declare (uses <i>modname</i>))</code>
|
|
and then compile that file into the shared library as well. For example, inside the <tt>mod_load.scm</tt> file,</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
(declare (uses mod1))
|
|
(declare (uses mod2))
|
|
</pre>
|
|
</div>
|
|
|
|
<p>Which would then be compiled with</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
$ swig -chicken mod1.i
|
|
$ swig -chicken mod2.i
|
|
$ csc -sv mod_load.scm mod1.scm mod2.scm mod1_wrap.c mod2_wrap.c mod1_impl.c mod2_impl.c -o mod.so
|
|
</pre>
|
|
</div>
|
|
|
|
<p>Then the extension library can be loaded with <code>(require 'mod)</code>. As we can see here,
|
|
<tt>mod_load.scm</tt> contains the code that gets executed when the module is loaded. All this code
|
|
does is load both mod1 and mod2. As we can see, this technique is more useful when you want to
|
|
combine a few SWIG modules into one chicken extension library, especially if modules are related by
|
|
<code>%import</code></p>
|
|
|
|
<p>In either method, the files that are compiled into the shared library could also be
|
|
packaged into an egg. The <tt>mod1_wrap.c</tt> and <tt>mod2_wrap.c</tt> files that are created by SWIG
|
|
are stand alone and do not need SWIG to be installed to be compiled. Thus the egg could be
|
|
distributed and used by anyone, even if SWIG is not installed.</p>
|
|
|
|
<p>See the <tt>Examples/chicken/egg</tt> directory in the SWIG source for an example that builds
|
|
two eggs, one using the first method and one using the second method.</p>
|
|
|
|
<H3><a name="Chicken_nn15">23.4.3 Linking multiple SWIG modules with TinyCLOS</a></H3>
|
|
|
|
|
|
<p>Linking together multiple modules that share type information using the <code>%import</code>
|
|
directive while also using <tt>-proxy</tt> is more complicated. For example, if <tt>mod2.i</tt> imports <tt>mod1.i</tt>, then the
|
|
<tt>mod2.scm</tt> file contains references to symbols declared in <tt>mod1.scm</tt>,
|
|
and thus a <code>(declare (uses <i>mod1</i>))</code> or <code>(require '<i>mod1</i>)</code> must be exported
|
|
to the top of <tt>mod2.scm</tt>. By default, when SWIG encounters an <code>%import "modname.i"</code> directive,
|
|
it exports <code>(declare (uses <i>modname</i>))</code> into the scm file. This works fine unless mod1 was compiled with
|
|
the <tt>-nounit</tt> argument or was compiled into an extension library with other modules under a different name.</p>
|
|
|
|
<p>One option is to override the automatic generation of <code>(declare (uses mod1))</code>
|
|
by passing the <tt>-noclosuses</tt> option to SWIG when compiling <tt>mod2.i</tt>.
|
|
SWIG then provides the <code>%insert(closprefix) %{ %}</code> directive. Any scheme code inside that directive is inserted into the
|
|
generated .scm file, and if <tt>mod1</tt> was compiled with <tt>-nounit</tt>, the directive should contain <code>(require 'mod1)</code>.
|
|
This option allows for mixed loading as well, where some modules are imported with <code>(declare (uses <i>modname</i>))</code>
|
|
(which means they were compiled without -nounit) and some are imported with <code>(require 'modname)</code>.</p>
|
|
|
|
<p>The other option is to use the second idea in the above section. Compile all the modules normally, without any
|
|
<code>%insert(closprefix)</code>, <tt>-nounit</tt>, or <tt>-noclosuses</tt>. Then the modules will import each other correctly
|
|
with <code>(declare (uses ...))</code>.
|
|
To create an extension library or an egg, just create a <tt>module_load.scm</tt> file that <code>(declare (uses ...))</code>
|
|
all the modules.</p>
|
|
|
|
<H2><a name="Chicken_nn16">23.5 Typemaps</a></H2>
|
|
|
|
|
|
<p>
|
|
The Chicken module handles all types via typemaps. This information is
|
|
read from <code>Lib/chicken/typemaps.i</code> and
|
|
<code>Lib/chicken/chicken.swg</code>.
|
|
</p>
|
|
|
|
<H2><a name="Chicken_nn17">23.6 Pointers</a></H2>
|
|
|
|
|
|
<p>
|
|
For pointer types, SWIG uses CHICKEN tagged pointers.
|
|
|
|
A tagged pointer is an ordinary CHICKEN pointer with an
|
|
extra slot for a void *. With SWIG
|
|
CHICKEN, this void * is a pointer to a type-info
|
|
structure. So each pointer used as input or output from
|
|
the SWIG-generated CHICKEN wrappers will have type
|
|
information attached to it. This will let the wrappers
|
|
correctly determine which method should be called
|
|
according to the object type hierarchy exposed in the SWIG
|
|
interface files.
|
|
</p>
|
|
<p>
|
|
To construct a Scheme object from a C pointer, the wrapper code
|
|
calls the function
|
|
<code>SWIG_NewPointerObj(void *ptr, swig_type_info *type, int owner)</code>,
|
|
The function that calls <code>SWIG_NewPointerObj</code> must have a variable declared
|
|
<code>C_word *known_space = C_alloc(C_SIZEOF_SWIG_POINTER);</code>
|
|
It is ok to call <code>SWIG_NewPointerObj</code> more than once,
|
|
just make sure known_space has enough space for all the created pointers.
|
|
</p>
|
|
<p>
|
|
To get the pointer represented by a CHICKEN tagged pointer, the
|
|
wrapper code calls the function
|
|
<code>SWIG_ConvertPtr(C_word s, void **result, swig_type_info *type, int flags)</code>,
|
|
passing a pointer to a struct representing the expected pointer
|
|
type. flags is either zero or SWIG_POINTER_DISOWN (see below).
|
|
</p>
|
|
|
|
<H3><a name="Chicken_collection">23.6.1 Garbage collection</a></H3>
|
|
|
|
|
|
<p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a
|
|
finalizer to the type which will call the destructor or delete method of
|
|
that type. The destructor and delete functions are no longer exported for
|
|
use in scheme code, instead SWIG and chicken manage pointers.
|
|
In situations where SWIG knows that a function is returning a type that should
|
|
be garbage collected, SWIG will automatically set the owner flag to 1. For other functions,
|
|
the <code>%newobject</code> directive must be specified for functions whose return values
|
|
should be garbage collected. See
|
|
<a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more information.
|
|
</p>
|
|
|
|
<p>In situations where a C or C++ function will assume ownership of a pointer, and thus
|
|
chicken should no longer garbage collect it, SWIG provides the <code>DISOWN</code> input typemap.
|
|
After applying this typemap (see the <a href="Typemaps.html#Typemaps">Typemaps chapter</a> for more information on how to apply typemaps),
|
|
any pointer that gets passed in will no longer be garbage collected.
|
|
An object is disowned by passing the <code>SWIG_POINTER_DISOWN</code> flag to <code>SWIG_ConvertPtr</code>.
|
|
<b>Warning:</b> Since the lifetime of the object is now controlled by the underlying code, the object might
|
|
get deleted while the scheme code still holds a pointer to it. Further use of this pointer
|
|
can lead to a crash.
|
|
</p>
|
|
|
|
<p>Adding a finalizer function from C code was added to chicken in the 1.89 release, so garbage collection
|
|
does not work for chicken versions below 1.89. If you would like the SWIG generated code to work with
|
|
chicken 1.40 to 1.89, pass the <code>-nocollection</code> argument to SWIG. This will not export code
|
|
inside the _wrap.c file to register finalizers, and will then export destructor functions which
|
|
must be called manually.
|
|
</p>
|
|
|
|
<H2><a name="Chicken_nn18">23.7 Unsupported features and known problems</a></H2>
|
|
|
|
|
|
<ul>
|
|
<li>No director support.</li>
|
|
<li>No support for c++ standard types like std::vector.</li>
|
|
<li>The TinyCLOS wrappers for overloaded functions will not work correctly when using
|
|
<a href="SWIGPlus.html#SWIGPlus_default_args">%feature(compactdefaultargs)</a>.</li>
|
|
</ul>
|
|
|
|
<H3><a name="Chicken_nn19">23.7.1 TinyCLOS problems with Chicken version <= 1.92</a></H3>
|
|
|
|
|
|
<p>In Chicken versions equal to or below 1.92, TinyCLOS has a limitation such that generic methods do not properly work on methods
|
|
with different number of specializers: TinyCLOS assumes that every method added to a generic function
|
|
will have the same number of specializers. SWIG generates functions with different lengths of specializers
|
|
when C/C++ functions are overloaded. For example, the code</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
class Foo {};
|
|
int foo(int a, Foo *b);
|
|
int foo(int a);
|
|
</pre></div>
|
|
|
|
<p>will produce scheme code</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
(define-method (foo (arg0 <top>) (arg1 <Foo>)) (<i>call primitive function</i>))
|
|
(define-method (foo (arg0 <top>)) (<i>call primitive function</i>))
|
|
</pre></div>
|
|
|
|
<p>Using unpatched TinyCLOS, the second <code>(define-method)</code> will replace the first one,
|
|
so calling <code>(foo 3 f)</code> will produce an error.</p>
|
|
|
|
<p>There are three solutions to this. The easist is to upgrade to the latest Chicken version. Otherwise, the
|
|
file <tt>Lib/chicken/tinyclos-multi-generic.patch</tt> in the SWIG source contains a patch against
|
|
tinyclos.scm inside the 1.92 chicken source to add support into TinyCLOS for multi-argument generics. (This patch was accepted into Chicken)
|
|
This requires chicken to be rebuilt and custom install of chicken. An alternative is the <tt>Lib/chicken/multi-generic.scm</tt>
|
|
file in the SWIG source. This file can be loaded after TinyCLOS is loaded, and it will override some functions
|
|
inside TinyCLOS to correctly support multi-argument generics. Please see the comments at the top of both files for more information.</p>
|
|
|
|
</body>
|
|
</html>
|