21
23
<li><a href="#Chicken_nn7">Modules</a>
22
24
<li><a href="#Chicken_nn8">Constants and Variables</a>
23
25
<li><a href="#Chicken_nn9">Functions</a>
26
<li><a href="#Chicken_nn10">Exceptions</a>
25
<li><a href="#Chicken_nn10">TinyCLOS</a>
26
<li><a href="#Chicken_nn11">Compilation</a>
28
<li><a href="#Chicken_nn11">TinyCLOS</a>
27
29
<li><a href="#Chicken_nn12">Linkage</a>
29
<li><a href="#Chicken_nn13">Shared library</a>
30
<li><a href="#Chicken_nn14">Static binary</a>
32
<li><a href="#Chicken_nn15">Typemaps</a>
33
<li><a href="#Chicken_nn16">Pointers</a>
34
<li><a href="#Chicken_nn17">Unsupported features and known problems</a>
31
<li><a href="#Chicken_nn13">Static binary or shared library linked at compile time</a>
32
<li><a href="#Chicken_nn14">Building chicken extension libraries</a>
33
<li><a href="#Chicken_nn15">Linking multiple SWIG modules with TinyCLOS</a>
35
<li><a href="#Chicken_nn16">Typemaps</a>
36
<li><a href="#Chicken_nn17">Pointers</a>
38
<li><a href="#collection">Garbage collection</a>
40
<li><a href="#Chicken_nn18">Unsupported features and known problems</a>
219
231
A function may return more than one value by using the
220
232
<code>OUTPUT</code> specifier (see Lib/chicken/typemaps.i).
221
They will be returned as a Scheme list if there is more than one
233
They will be returned as multiple values using <code>(values)</code> if there is more than one
222
234
result (that is, a non-void return value and at least one argout
223
235
parameter, or a void return value and at least two argout
236
parameters). The return values can then be accessed with <code>(call-with-values)</code>.
227
<H2><a name="Chicken_nn10"></a>17.3 TinyCLOS</H2>
239
<H3><a name="Chicken_nn10"></a>17.2.5 Exceptions</H3>
242
<p>The SWIG chicken module has support for exceptions thrown from
243
C or C++ code to be caught in scheme.
244
See <a href="Customization.html#exception">Exception handling with %exception</a>
245
for more information about declaring exceptions in the interface file.
248
<p>Chicken supports both the <code>SWIG_exception(int code, const char *msg)</code> interface
249
as well as a <code>SWIG_ThrowException(C_word val)</code> function for throwing exceptions from
250
inside the %exception blocks. <code>SWIG_exception</code> will throw a list consisting of the code
251
(as an integer) and the message. Both of these will throw an exception using <code>(abort)</code>,
252
which can be handled by <code>(handle-exceptions)</code>. See
253
<a href="http://www.call-with-current-continuation.org/manual/Exceptions.html#Exceptions">Chicken manual on Exceptions</a>
254
and <a href="http://srfi.schemers.org/srfi-12/srfi-12.html">SFRI-12</a>. Since the exception values are thrown
255
directly, if <code>(condition-case)</code> is used to catch an exception the exception will come through in the <code>val ()</code> case.
258
<p>The following simple module</p>
260
<div class="code"><pre>
261
%module exception_test
264
void test_throw(int i) throws (int) {
265
if (i == 1) throw 15;
270
<p>could be run with</p>
272
<div class="targetlang"><pre>
273
(handle-exceptions exvar
276
(print "Threw something else " exvar))
281
<H2><a name="Chicken_nn11"></a>17.3 TinyCLOS</H2>
231
285
The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as:
234
Tiny CLOS is a Scheme implementation of a `kernelized' CLOS, with a
286
"Tiny CLOS is a Scheme implementation of a `kernelized' CLOS, with a
235
287
metaobject protocol. The implementation is even simpler than
236
288
the simple CLOS found in `The Art of the Metaobject Protocol,'
237
289
weighing in at around 850 lines of code, including (some)
238
comments and documentation.
290
comments and documentation."
242
294
Almost all good Scheme books describe how to use metaobjects and
294
332
-extra-libs -libs`</tt> or <tt>`chicken-config -shared
295
333
-extra-libs -libs`</tt>to your linker options. Use the
296
334
<tt>-shared</tt> option if you want to create a dynamically
300
<H3><a name="Chicken_nn13"></a>17.5.1 Shared library</H3>
304
The easiest way to use SWIG and CHICKEN is to use the csc compiler
305
wrapper provided by CHICKEN. Assume you have a SWIG interface file
306
in example.i and the C functions being wrapped are in example_impl.c.
311
$ swig -chicken example.i
312
$ csc -svk example.scm example_impl.c example_wrap.c
313
$ csi example.so test_script.scm
318
You must be careful not to name the example_impl.c file example.c because
319
when compiling example.scm, csc compiles that into example.c!
323
The test_script.scm should have <code>(load-library 'example "example.so")</code>
324
and <code>(declare (uses example))</code>. As well, the path to example.so should
325
be accessable to the loader. You might need to set LD_LIBRARY_PATH.
328
<H3><a name="Chicken_nn14"></a>17.5.2 Static binary</H3>
331
<p>Again, we can easily use csc to build a binary.</p>
335
$ swig -chicken example.i
336
$ csc -vk example.scm example_impl.c example_wrap.c test_script.scm -o example
341
<H2><a name="Chicken_nn15"></a>17.6 Typemaps</H2>
335
loadable module. You might also want to use the much simpler
336
<tt>csc</tt> or <tt>csc.bat</tt>.
339
<p>Each scheme file that is generated
340
by SWIG contains <code>(declare (uses <i>modname</i>))</code>. This means that to load the
341
module from scheme code, the code must include <code>(declare (uses <i>modname</i>))</code>.
345
<H3><a name="Chicken_nn13"></a>17.4.1 Static binary or shared library linked at compile time</H3>
348
<p>We can easily use csc to build a static binary.</p>
352
$ swig -chicken example.i
353
$ csc -v example.scm example_impl.c example_wrap.c test_script.scm -o example
358
<p>Similar to the above, any number of <tt>module.scm</tt> files could be compiled
359
into a shared library, and then that shared library linked when compiling the
360
main application.</p>
364
$ swig -chicken example.i
365
$ csc -sv example.scm example_wrap.c example_impl.c -o example.so
369
<p>The <tt>exmaple.so</tt> file can then linked with <tt>test_script.scm</tt> when it
370
is compiled, in which case <tt>test_script.scm</tt> must have <code>(declare (uses example))</code>.
371
Multiple SWIG modules could have been linked into <tt>example.so</tt> and each
372
one accessed with a <code>(declare (uses ... ))</code>.
377
$ csc -v test_script.scm -lexample
381
<p>An alternative is that the test_script.scm can have the code <code>(load-library 'example "example.so")</code>,
382
in which case the test script does not need to be linked with example.so. The test_script.scm file can then
383
be run with <tt>csi</tt>.
386
<H3><a name="Chicken_nn14"></a>17.4.2 Building chicken extension libraries</H3>
389
<p>Building a shared library like in the above section only works if the library
390
is linked at compile time with a script containing <code>(declare (uses ...))</code> or is
391
loaded explicitly with <code>(load-library 'example "example.so")</code>. It is
392
not the format that CHICKEN expects for extension libraries and eggs. The problem is the
393
<code>(declare (unit <i>modname</i>))</code> inside the <tt>modname.scm</tt> file. There are
394
two possible solutions to this.</p>
396
<p>First, SWIG accepts a <tt>-nounit</tt> argument, in which case the <code>(declare (unit <i>modname</i>))</code>
397
is not generated. Then, the <tt>modname.scm</tt> and <tt>modname_wrap.c</tt> files <b>must</b> be compiled into
398
their own shared library.</p>
402
$ csc -sv modname.scm modname_wrap.c modname_impl.c -o modname.so
406
<p>This library can then be loaded by scheme code with the <code>(require 'modname)</code> function.
407
See <a href="http://www.call-with-current-continuation.org/manual/Loading-extension-libraries.html">
408
Loading-extension-libraries</a> in the eval unit inside the CHICKEN manual for more information.</p>
410
<p>Another alternative is to run SWIG normally and create a scheme file that contains <code>(declare (uses <i>modname</i>))</code>
411
and then compile that file into the shared library as well. For example, inside the <tt>mod_load.scm</tt> file,</p>
413
<div class="targetlang">
415
(declare (uses mod1))
416
(declare (uses mod2))
420
<p>Which would then be compiled with</p>
424
$ swig -chicken mod1.i
425
$ swig -chicken mod2.i
426
$ csc -sv mod_load.scm mod1.scm mod2.scm mod1_wrap.c mod2_wrap.c mod1_impl.c mod2_impl.c -o mod.so
430
<p>Then the extension library can be loaded with <code>(require 'mod)</code>. As we can see here,
431
<tt>mod_load.scm</tt> contains the code that gets exectued when the module is loaded. All this code
432
does is load both mod1 and mod2. As we can see, this technique is more useful when you want to
433
combine a few SWIG modules into one chicken extension library, especially if modules are related by
434
<code>%import</code></p>
436
<p>In either method, the files that are compiled into the shared library could also be
437
packaged into an egg. The <tt>mod1_wrap.c</tt> and <tt>mod2_wrap.c</tt> files that are created by SWIG
438
are stand alone and do not need SWIG to be installed to be compiled. Thus the egg could be
439
distributed and used by anyone, even if SWIG is not installed.</p>
441
<p>See the <tt>Examples/chicken/egg</tt> directory in the SWIG source for an example that builds
442
two eggs, one using the first method and one using the second method.</p>
444
<H3><a name="Chicken_nn15"></a>17.4.3 Linking multiple SWIG modules with TinyCLOS</H3>
447
<p>Linking together multiple modules that share type information using the <code>%import</code>
448
directive while also using <tt>-proxy</tt> is more complicated. For example, if <tt>mod2.i</tt> imports <tt>mod1.i</tt>, then the
449
<tt>mod2.scm</tt> file contains references to symbols declared in <tt>mod1.scm</tt>,
450
and thus a <code>(declare (uses <i>mod1</i>))</code> or <code>(require '<i>mod1</i>)</code> must be exported
451
to the top of <tt>mod2.scm</tt>. By default, when SWIG encounters an <code>%import "modname.i"</code> directive,
452
it exports <code>(declare (uses <i>modname</i>))</code> into the scm file. This works fine unless mod1 was compiled with
453
the <tt>-nounit</tt> argument or was compiled into an extension library with other modules under a different name.</p>
455
<p>One option is to override the automatic generation of <code>(declare (uses mod1))</code>
456
by passing the <tt>-noclosuses</tt> option to SWIG when compiling <tt>mod2.i</tt>.
457
SWIG then provides the <code>%insert(closprefix) %{ %}</code> directive. Any scheme code inside that directive is inserted into the
458
generated .scm file, and if <tt>mod1</tt> was compiled with <tt>-nounit</tt>, the directive should contain <code>(require 'mod1)</code>.
459
This option allows for mixed loading as well, where some modules are imported with <code>(declare (uses <i>modname</i>))</code>
460
(which means they were compiled without -nounit) and some are imported with <code>(require 'modname)</code>.</p>
462
<p>The other option is to use the second idea in the above section. Compile all the modules normally, without any
463
<code>%insert(closprefix)</code>, <tt>-nounit</tt>, or <tt>-noclosuses</tt>. Then the modules will import each other correctly
464
with <code>(declare (uses ...))</code>.
465
To create an extension library or an egg, just create a <tt>module_load.scm</tt> file that <code>(declare (uses ...))</code>
468
<H2><a name="Chicken_nn16"></a>17.5 Typemaps</H2>
377
504
wrapper code calls the function
378
505
<code>SWIG_ConvertPtr(C_word s, void **result, swig_type_info *type, int flags)</code>,
379
506
passing a pointer to a struct representing the expected pointer
507
type. flags is either zero or SWIG_POINTER_DISOWN (see below).
383
<H2><a name="Chicken_nn17"></a>17.8 Unsupported features and known problems</H2>
510
<H3><a name="collection"></a>17.6.1 Garbage collection</H3>
513
<p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a
514
finalizer to the type which will call the destructor or delete method of
515
that type. The destructor and delete functions are no longer exported for
516
use in scheme code, instead SWIG and chicken manage pointers.
517
In situations where SWIG knows that a function is returning a type that should
518
be garbage collected, SWIG will automaticly set the owner flag to 1. For other functions,
519
the <code>%newobject</code> directive must be specified for functions whose return values
520
should be garbage collected. See
521
<a href="Customization.html#ownership">Object ownership and %newobject</a> for more information.
524
<p>In situations where a C or C++ function will assume ownership of a pointer, and thus
525
chicken should no longer garbage collect it, SWIG provides the <code>DISOWN</code> input typemap.
526
After applying this typemap (see the <a href="Typemaps.html">Typemaps chapter</a> for more information on how to apply typemaps),
527
any pointer that gets passed in will no longer be garbage collected.
528
An object is disowned by passing the <code>SWIG_POINTER_DISOWN</code> flag to <code>SWIG_ConvertPtr</code>.
529
<b>Warning:</b> Since the lifetime of the object is now controlled by the underlying code, the object might
530
get deleted while the scheme code still holds a pointer to it. Further use of this pointer
534
<p>Adding a finalizer function from C code was added to chicken in the 1.89 release, so garbage collection
535
does not work for chicken versions below 1.89. If you would like the SWIG generated code to work with
536
chicken 1.40 to 1.89, pass the <code>-nocollection</code> argument to SWIG. This will not export code
537
inside the _wrap.c file to register finalizers, and will then export destructor functions which
538
must be called manually.
541
<H2><a name="Chicken_nn18"></a>17.7 Unsupported features and known problems</H2>
387
<li>No exception handling.</li>
388
545
<li>No director support.</li>
389
546
<li>No support for c++ standard types like std::vector.</li>
390
<li>No support for automatic garbage collection of wrapped classes and structures. (Planned on adding in SWIG version 1.3.25) </li>
391
<li>Importing multiple SWIG modules not working with TinyCLOS. (Planned on fixing for 1.3.25) </li>
392
<li>Problems with complicated function overloading. (Planned on fixing for 1.3.25)</li>
547
<li>The TinyCLOS wrappers for overloaded functions will not work correctly when using
548
<a href="SWIGPlus.html#SWIGPlus_default_args">%feature(compactdefaultargs)</a>.</li>
551
<p>TinyCLOS has a limitation such that generic methods do not properly work on methods
552
with different number of specializers: TinyCLOS assumes that every method added to a generic function
553
will have the same number of specializers. SWIG generates functions with different lengths of specializers
554
when C/C++ functions are overloaded. For example, the code</p>
559
int foo(int a, Foo *b);
563
<p>will produce scheme code</p>
565
<div class="targetlang">
567
(define-method (foo (arg0 <top>) (arg1 <Foo>)) (<i>call primitive function</i>))
568
(define-method (foo (arg0 <top>)) (<i>call primitive function</i>))
571
<p>Using unpatched TinyCLOS, the second <code>(define-method)</code> will replace the first one,
572
so calling <code>(foo 3 f)</code> will produce an error.</p>
574
<p>There are two solutions to this: the
575
file <tt>Lib/chicken/tinyclos-multi-generic.patch</tt> in the SWIG source contains a patch against
576
tinyclos.scm inside the chicken source to add support into TinyCLOS for multi-argument generics.
577
This requires chicken to be rebuilt and custom install of chicken. An alternative is the <tt>Lib/chicken/multi-generic.scm</tt>
578
file in the SWIG source. This file can be loaded after TinyCLOS is loaded, and it will override some functions
579
inside TinyCLOS to correctly support multi-argument generics. This solution will work on any install of chicken.
580
Please see the comments at the top of both files for more information.</p>
added
removed
Doc/Manual/Chicken.html
