Doc/Manual/Chicken.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <!-- Hand-written HTML -->
   3 <html>
   4 <head>
   5 <title>SWIG and Chicken</title>
   6 <link rel="stylesheet" type="text/css" href="style.css">
   7 </head>
   8
   9 <body bgcolor="#ffffff">
  10
  11 <H1><a name="Chicken"></a>19 SWIG and Chicken</H1>
  12 <!-- INDEX -->
  13 <div class="sectiontoc">
  14 <ul>
  15 <li><a href="#Chicken_nn2">Preliminaries</a>
  16 <ul>
  17 <li><a href="#Chicken_nn3">Running SWIG in C mode</a>
  18 <li><a href="#Chicken_nn4">Running SWIG in C++ mode</a>
  19 </ul>
  20 <li><a href="#Chicken_nn5">Code Generation</a>
  21 <ul>
  22 <li><a href="#Chicken_nn6">Naming Conventions</a>
  23 <li><a href="#Chicken_nn7">Modules</a>
  24 <li><a href="#Chicken_nn8">Constants and Variables</a>
  25 <li><a href="#Chicken_nn9">Functions</a>
  26 <li><a href="#Chicken_nn10">Exceptions</a>
  27 </ul>
  28 <li><a href="#Chicken_nn11">TinyCLOS</a>
  29 <li><a href="#Chicken_nn12">Linkage</a>
  30 <ul>
  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>
  34 </ul>
  35 <li><a href="#Chicken_nn16">Typemaps</a>
  36 <li><a href="#Chicken_nn17">Pointers</a>
  37 <ul>
  38 <li><a href="#collection">Garbage collection</a>
  39 </ul>
  40 <li><a href="#Chicken_nn18">Unsupported features and known problems</a>
  41 <ul>
  42 <li><a href="#Chicken_nn19">TinyCLOS problems with Chicken version &lt;= 1.92</a>
  43 </ul>
  44 </ul>
  45 </div>
  46 <!-- INDEX -->
  47
  48
  49
  50     <p>
  51       This chapter describes SWIG's support of CHICKEN.  CHICKEN is a
  52       Scheme-to-C compiler supporting most of the language features as
  53       defined in the <i>Revised^5 Report on Scheme</i>.  Its main
  54       attributes are that it
  55     </p>
  56
  57       <ol>
  58         <li>generates portable C code</li>
  59         <li>includes a customizable interpreter</li>
  60         <li>links to C libraries with a simple Foreign Function Interface</li>
  61         <li>supports full tail-recursion and first-class continuations</li>
  62       </ol>
  63
  64     <p>
  65       When confronted with a large C library, CHICKEN users can use
  66       SWIG to generate CHICKEN wrappers for the C library.  However,
  67       the real advantages of using SWIG with CHICKEN are its
  68       <strong>support for C++</strong> -- object-oriented code is
  69       difficult to wrap by hand in CHICKEN -- and its <strong>typed
  70       pointer representation</strong>, essential for C and C++
  71       libraries involving structures or classes.
  72
  73     </p>
  74
  75 <H2><a name="Chicken_nn2"></a>19.1 Preliminaries</H2>
  76
  77
  78     <p>
  79       CHICKEN support was introduced to SWIG in version 1.3.18.  SWIG
  80       relies on some recent additions to CHICKEN, which are only
  81       present in releases of CHICKEN with version number
  82       <strong>greater than or equal to 1.89</strong>.
  83       To use a chicken version between 1.40 and 1.89, see the <a href="#collection">Garbage collection</a>
  84       section below.
  85     </p>
  86
  87       <p>
  88       You may want to look at any of the examples in Examples/chicken/
  89       or Examples/GIFPlot/Chicken for the basic steps to run SWIG
  90       CHICKEN.
  91       </p>
  92
  93 <H3><a name="Chicken_nn3"></a>19.1.1 Running SWIG in C mode</H3>
  94
  95
  96       <p>
  97       To run SWIG CHICKEN in C mode, use
  98       the -chicken option.
  99       </p>
 100
 101       <div class="shell">
 102         <pre>% swig -chicken example.i</pre>
 103       </div>
 104
 105       <p>
 106       To allow the wrapper to take advantage of future CHICKEN code
 107       generation improvements, part of the wrapper is direct CHICKEN
 108       function calls (<tt>example_wrap.c</tt>) and part is CHICKEN
 109       Scheme (<tt>example.scm</tt>).  The basic Scheme code must
 110       be compiled to C using your system's CHICKEN compiler or
 111       both files can be compiled directly using the much simpler <tt>csc</tt>.
 112       </p>
 113
 114       <div class="shell">
 115 <pre>
 116 % chicken example.scm -output-file oexample.c
 117 </pre>
 118       </div>
 119
 120       <p>
 121       So for the C mode of SWIG CHICKEN, <tt>example_wrap.c</tt> and
 122       <tt>oexample.c</tt> are the files that must be compiled to
 123       object files and linked into your project.
 124       </p>
 125
 126 <H3><a name="Chicken_nn4"></a>19.1.2 Running SWIG in C++ mode</H3>
 127
 128
 129       <p>
 130       To run SWIG CHICKEN in C++ mode, use
 131       the -chicken -c++ option.
 132       </p>
 133
 134       <div class="shell">
 135         <pre>% swig -chicken -c++ example.i</pre>
 136       </div>
 137
 138       <p>
 139       This will generate <tt>example_wrap.cxx</tt> and
 140       <tt>example.scm</tt>.  The basic Scheme code must be
 141       compiled to C using your system's CHICKEN compiler or
 142       both files can be compiled directly using the much simpler <tt>csc</tt>.
 143       </p>
 144
 145       <div class="shell">
 146         <pre>% chicken example.scm -output-file oexample.c</pre>
 147       </div>
 148
 149       <p>
 150       So for the C++ mode of SWIG CHICKEN, <tt>example_wrap.cxx</tt>
 151       and <tt>oexample.c</tt> are the files that must be compiled to
 152       object files and linked into your project.
 153       </p>
 154
 155 <H2><a name="Chicken_nn5"></a>19.2 Code Generation</H2>
 156
 157
 158 <H3><a name="Chicken_nn6"></a>19.2.1 Naming Conventions</H3>
 159
 160
 161     <p>
 162       Given a C variable, function or constant declaration named
 163       <tt>Foo_Bar</tt>, the declaration will be available
 164       in CHICKEN as an identifier ending with
 165       <tt>Foo-Bar</tt>.  That is, an underscore is converted
 166       to a dash.
 167     </p>
 168
 169     <p>
 170       You may control what the CHICKEN identifier will be by using the
 171       <tt>%rename</tt> SWIG directive in the SWIG interface file.
 172     </p>
 173
 174 <H3><a name="Chicken_nn7"></a>19.2.2 Modules</H3>
 175
 176
 177       <p>
 178       The name of the module must be declared one of two ways:
 179       <ul>
 180         <li>Placing <tt>%module example</tt> in the SWIG interface
 181           file.</li>
 182         <li>Using <tt>-module example</tt> on the SWIG command
 183           line.</li>
 184       </ul>
 185
 186       <p>
 187       The generated example.scm file then exports <code>(declare (unit modulename))</code>.
 188       If you do not want SWIG to export the <code>(declare (unit modulename))</code>, pass
 189       the -nounit option to SWIG.
 190
 191     <p>
 192       CHICKEN will be able to access the module using the <code>(declare
 193         (uses <i>modulename</i>))</code> CHICKEN Scheme form.
 194     </p>
 195
 196 <H3><a name="Chicken_nn8"></a>19.2.3 Constants and Variables</H3>
 197
 198
 199     <p>
 200       Constants may be created using any of the four constructs in
 201       the interface file:
 202     </p>
 203       <ol>
 204         <li><code>#define MYCONSTANT1 ...</code></li>
 205         <li><code>%constant int MYCONSTANT2 = ...</code></li>
 206         <li><code>const int MYCONSTANT3 = ...</code></li>
 207         <li><code>enum { MYCONSTANT4  = ... };</code></li>
 208       </ol>
 209
 210     <p>
 211       In all cases, the constants may be accessed from within CHICKEN
 212       using the form <tt>(MYCONSTANT1)</tt>; that is, the constants
 213       may be accessed using the read-only parameter form.
 214     </p>
 215
 216     <p>
 217       Variables are accessed using the full parameter form.
 218       For example, to set the C variable "int my_variable;", use the
 219       Scheme form <tt>(my-variable 2345)</tt>.  To get the C variable,
 220       use <tt>(my-variable)</tt>.
 221     </p>
 222
 223     <p>
 224       The <tt>%feature("constasvar")</tt> can be applied to any constant
 225       or immutable variable.  Instead of exporting the constant as
 226       a function that must be called, the constant will appear as a
 227       scheme variable.  This causes the generated .scm file to just contain the code
 228       <tt>(set! MYCONSTANT1 (MYCONSTANT1))</tt>. See
 229       <a href="Customization.html#features">Features and the %feature directive</a>
 230       for info on how to apply the %feature.
 231     </p>
 232
 233 <H3><a name="Chicken_nn9"></a>19.2.4 Functions</H3>
 234
 235
 236     <p>
 237       C functions declared in the SWIG interface file will have
 238       corresponding CHICKEN Scheme procedures.  For example, the C
 239       function "int sqrt(double x);" will be available using the
 240       Scheme form <tt>(sqrt 2345.0)</tt>.  A <code>void</code> return
 241       value will give C_SCHEME_UNDEFINED as a result.
 242     </p>
 243     <p>
 244       A function may return more than one value by using the
 245       <code>OUTPUT</code> specifier (see Lib/chicken/typemaps.i).
 246       They will be returned as multiple values using <code>(values)</code> if there is more than one
 247       result (that is, a non-void return value and at least one argout
 248       parameter, or a void return value and at least two argout
 249       parameters).  The return values can then be accessed with <code>(call-with-values)</code>.
 250     </p>
 251
 252 <H3><a name="Chicken_nn10"></a>19.2.5 Exceptions</H3>
 253
 254
 255      <p>The SWIG chicken module has support for exceptions thrown from
 256      C or C++ code to be caught in scheme.
 257      See <a href="Customization.html#exception">Exception handling with %exception</a>
 258      for more information about declaring exceptions in the interface file.
 259      </p>
 260
 261      <p>Chicken supports both the <code>SWIG_exception(int code, const char *msg)</code> interface
 262      as well as a <code>SWIG_ThrowException(C_word val)</code> function for throwing exceptions from
 263      inside the %exception blocks.  <code>SWIG_exception</code> will throw a list consisting of the code
 264      (as an integer) and the message.  Both of these will throw an exception using <code>(abort)</code>,
 265      which can be handled by <code>(handle-exceptions)</code>.  See
 266      <a href="http://www.call-with-current-continuation.org/manual/Exceptions.html#Exceptions">Chicken manual on Exceptions</a>
 267      and <a href="http://srfi.schemers.org/srfi-12/srfi-12.html">SFRI-12</a>.  Since the exception values are thrown
 268      directly, if <code>(condition-case)</code> is used to catch an exception the exception will come through in the <code>val ()</code> case.
 269      </p>
 270
 271      <p>The following simple module</p>
 272
 273 <div class="code"><pre>
 274 %module exception_test
 275
 276 %inline %{
 277   void test_throw(int i) throws (int) {
 278     if (i == 1) throw 15;
 279   }
 280 %}
 281 </pre></div>
 282
 283      <p>could be run with</p>
 284
 285 <div class="targetlang"><pre>
 286 (handle-exceptions exvar
 287   (if (= exvar 15)
 288     (print "Correct!")
 289     (print "Threw something else " exvar))
 290   (test-throw 1))
 291 </pre></div>
 292
 293
 294 <H2><a name="Chicken_nn11"></a>19.3 TinyCLOS</H2>
 295
 296
 297       <p>
 298       The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as:
 299         "Tiny CLOS is a Scheme implementation of a `kernelized' CLOS, with a
 300         metaobject protocol. The implementation is even simpler than
 301         the simple CLOS found in `The Art of the Metaobject Protocol,'
 302         weighing in at around 850 lines of code, including (some)
 303         comments and documentation."
 304       </p>
 305
 306       <p>
 307       Almost all good Scheme books describe how to use metaobjects and
 308       generic procedures to implement an object-oriented Scheme
 309       system.  Please consult a Scheme book if you are unfamiliar
 310       with the concept.
 311       </p>
 312
 313       <p>
 314
 315       CHICKEN has a modified version of TinyCLOS, which SWIG CHICKEN
 316       uses if the -proxy argument is given.  If -proxy is passed, then
 317       the generated example.scm file will contain TinyCLOS class definitions.
 318       A class named Foo is declared as &lt;Foo&gt;, and each member variable
 319       is allocated a slot.  Member functions are exported as generic functions.
 320
 321       <p>
 322
 323       Primitive symbols and functions (the interface that would be presented if
 324       -proxy was not passed) are hidden and no longer accessible.  If the -unhideprimitive
 325       command line argument is passed to SWIG, then the primitive symbols will be
 326       available, but each will be prefixed by the string "primitive:"
 327
 328       <p>
 329
 330       The exported symbol names can be controlled with the -closprefix and -useclassprefix arguments.
 331       If -useclassprefix is passed to SWIG, every member function will be generated with the class name
 332       as a prefix.  If the -closprefix mymod: argument is passed to SWIG, then the exported functions will
 333       be prefixed by the string "mymod:".  If -useclassprefix is passed, -closprefix is ignored.
 334
 335       </p>
 336
 337 <H2><a name="Chicken_nn12"></a>19.4 Linkage</H2>
 338
 339
 340     <p>
 341       Please refer to <em>CHICKEN - A practical and portable Scheme
 342       system - User's manual</em> for detailed help on how to link
 343       object files to create a CHICKEN Scheme program.  Briefly, to
 344       link object files, be sure to add <tt>`chicken-config
 345       -extra-libs -libs`</tt> or <tt>`chicken-config -shared
 346       -extra-libs -libs`</tt>to your linker options.  Use the
 347       <tt>-shared</tt> option if you want to create a dynamically
 348       loadable module.  You might also want to use the much simpler
 349       <tt>csc</tt> or <tt>csc.bat</tt>.
 350     </p>
 351
 352     <p>Each scheme file that is generated
 353    by SWIG contains <code>(declare (uses <i>modname</i>))</code>.  This means that to load the
 354    module from scheme code, the code must include <code>(declare (uses <i>modname</i>))</code>.
 355    </p>
 356
 357
 358 <H3><a name="Chicken_nn13"></a>19.4.1 Static binary or shared library linked at compile time</H3>
 359
 360
 361    <p>We can easily use csc to build a static binary.</p>
 362
 363 <div class="shell">
 364 <pre>
 365 $ swig -chicken example.i
 366 $ csc -v example.scm example_impl.c example_wrap.c test_script.scm -o example
 367 $ ./example
 368 </pre>
 369 </div>
 370
 371 <p>Similar to the above, any number of <tt>module.scm</tt> files could be compiled
 372 into a shared library, and then that shared library linked when compiling the
 373 main application.</p>
 374
 375 <div class="shell">
 376 <pre>
 377 $ swig -chicken example.i
 378 $ csc -sv example.scm example_wrap.c example_impl.c -o example.so
 379 </pre>
 380 </div>
 381
 382 <p>The <tt>example.so</tt> file can then linked with <tt>test_script.scm</tt> when it
 383 is compiled, in which case <tt>test_script.scm</tt> must have <code>(declare (uses example))</code>.
 384 Multiple SWIG modules could have been linked into <tt>example.so</tt> and each
 385 one accessed with a <code>(declare (uses ... ))</code>.
 386 </p>
 387
 388 <div class="shell">
 389 <pre>
 390 $ csc -v test_script.scm -lexample
 391 </pre>
 392 </div>
 393
 394 <p>An alternative is that the test_script.scm can have the code <code>(load-library 'example "example.so")</code>,
 395 in which case the test script does not need to be linked with example.so.  The test_script.scm file can then
 396 be run with <tt>csi</tt>.
 397 </p>
 398
 399 <H3><a name="Chicken_nn14"></a>19.4.2 Building chicken extension libraries</H3>
 400
 401
 402 <p>Building a shared library like in the above section only works if the library
 403 is linked at compile time with a script containing <code>(declare (uses ...))</code> or is
 404 loaded explicitly with <code>(load-library 'example "example.so")</code>. It is
 405 not the format that CHICKEN expects for extension libraries and eggs.  The problem is the
 406 <code>(declare (unit <i>modname</i>))</code> inside the <tt>modname.scm</tt> file.  There are
 407 two possible solutions to this.</p>
 408
 409 <p>First, SWIG accepts a <tt>-nounit</tt> argument, in which case the <code>(declare (unit <i>modname</i>))</code>
 410 is not generated.  Then, the <tt>modname.scm</tt> and <tt>modname_wrap.c</tt> files <b>must</b> be compiled into
 411 their own shared library.</p>
 412
 413 <div class="shell">
 414 <pre>
 415 $ csc -sv modname.scm modname_wrap.c modname_impl.c -o modname.so
 416 </pre>
 417 </div>
 418
 419 <p>This library can then be loaded by scheme code with the <code>(require 'modname)</code> function.
 420 See <a href="http://www.call-with-current-continuation.org/manual/Loading-extension-libraries.html">
 421 Loading-extension-libraries</a> in the eval unit inside the CHICKEN manual for more information.</p>
 422
 423 <p>Another alternative is to run SWIG normally and create a scheme file that contains <code>(declare (uses <i>modname</i>))</code>
 424 and then compile that file into the shared library as well.  For example, inside the <tt>mod_load.scm</tt> file,</p>
 425
 426 <div class="targetlang">
 427 <pre>
 428 (declare (uses mod1))
 429 (declare (uses mod2))
 430 </pre>
 431 </div>
 432
 433 <p>Which would then be compiled with</p>
 434
 435 <div class="shell">
 436 <pre>
 437 $ swig -chicken mod1.i
 438 $ swig -chicken mod2.i
 439 $ csc -sv mod_load.scm mod1.scm mod2.scm mod1_wrap.c mod2_wrap.c mod1_impl.c mod2_impl.c -o mod.so
 440 </pre>
 441 </div>
 442
 443 <p>Then the extension library can be loaded with <code>(require 'mod)</code>.  As we can see here,
 444 <tt>mod_load.scm</tt> contains the code that gets executed when the module is loaded.  All this code
 445 does is load both mod1 and mod2.  As we can see, this technique is more useful when you want to
 446 combine a few SWIG modules into one chicken extension library, especially if modules are related by
 447 <code>%import</code></p>
 448
 449 <p>In either method, the files that are compiled into the shared library could also be
 450 packaged into an egg.  The <tt>mod1_wrap.c</tt> and <tt>mod2_wrap.c</tt> files that are created by SWIG
 451 are stand alone and do not need SWIG to be installed to be compiled.  Thus the egg could be
 452 distributed and used by anyone, even if SWIG is not installed.</p>
 453
 454 <p>See the <tt>Examples/chicken/egg</tt> directory in the SWIG source for an example that builds
 455 two eggs, one using the first method and one using the second method.</p>
 456
 457 <H3><a name="Chicken_nn15"></a>19.4.3 Linking multiple SWIG modules with TinyCLOS</H3>
 458
 459
 460 <p>Linking together multiple modules that share type information using the <code>%import</code>
 461 directive while also using <tt>-proxy</tt> is more complicated.  For example, if <tt>mod2.i</tt> imports <tt>mod1.i</tt>, then the
 462 <tt>mod2.scm</tt> file contains references to symbols declared in <tt>mod1.scm</tt>,
 463 and thus a <code>(declare (uses <i>mod1</i>))</code> or <code>(require '<i>mod1</i>)</code> must be exported
 464 to the top of <tt>mod2.scm</tt>.  By default, when SWIG encounters an <code>%import "modname.i"</code> directive,
 465 it exports <code>(declare (uses <i>modname</i>))</code> into the scm file.  This works fine unless mod1 was compiled with
 466 the <tt>-nounit</tt> argument or was compiled into an extension library with other modules under a different name.</p>
 467
 468 <p>One option is to override the automatic generation of <code>(declare (uses mod1))</code>
 469 by passing the <tt>-noclosuses</tt> option to SWIG when compiling <tt>mod2.i</tt>.
 470 SWIG then provides the <code>%insert(closprefix) %{ %}</code> directive.  Any scheme code inside that directive is inserted into the
 471 generated .scm file, and if <tt>mod1</tt> was compiled with <tt>-nounit</tt>, the directive should contain <code>(require 'mod1)</code>.
 472 This option allows for mixed loading as well, where some modules are imported with <code>(declare (uses <i>modname</i>))</code>
 473 (which means they were compiled without -nounit) and some are imported with <code>(require 'modname)</code>.</p>
 474
 475 <p>The other option is to use the second idea in the above section.  Compile all the modules normally, without any
 476 <code>%insert(closprefix)</code>, <tt>-nounit</tt>, or <tt>-noclosuses</tt>.  Then the modules will import each other correctly
 477 with <code>(declare (uses ...))</code>.
 478 To create an extension library or an egg, just create a <tt>module_load.scm</tt> file that <code>(declare (uses ...))</code>
 479 all the modules.</p>
 480
 481 <H2><a name="Chicken_nn16"></a>19.5 Typemaps</H2>
 482
 483
 484     <p>
 485       The Chicken module handles all types via typemaps. This information is
 486       read from <code>Lib/chicken/typemaps.i</code> and
 487       <code>Lib/chicken/chicken.swg</code>.
 488     </p>
 489
 490 <H2><a name="Chicken_nn17"></a>19.6 Pointers</H2>
 491
 492
 493     <p>
 494       For pointer types, SWIG uses CHICKEN tagged pointers.
 495
 496       A tagged pointer is an ordinary CHICKEN pointer with an
 497       extra slot for a void *.  With SWIG
 498       CHICKEN, this void * is a pointer to a type-info
 499       structure.  So each pointer used as input or output from
 500       the SWIG-generated CHICKEN wrappers will have type
 501       information attached to it.  This will let the wrappers
 502       correctly determine which method should be called
 503       according to the object type hierarchy exposed in the SWIG
 504       interface files.
 505     </p>
 506     <p>
 507       To construct a Scheme object from a C pointer, the wrapper code
 508       calls the function
 509       <code>SWIG_NewPointerObj(void *ptr, swig_type_info *type, int owner)</code>,
 510       The function that calls <code>SWIG_NewPointerObj</code> must have a variable declared
 511       <code>C_word *known_space = C_alloc(C_SIZEOF_SWIG_POINTER);</code>
 512       It is ok to call <code>SWIG_NewPointerObj</code> more than once,
 513       just make sure known_space has enough space for all the created pointers.
 514     </p>
 515     <p>
 516       To get the pointer represented by a CHICKEN tagged pointer, the
 517       wrapper code calls the function
 518       <code>SWIG_ConvertPtr(C_word s, void **result, swig_type_info *type, int flags)</code>,
 519       passing a pointer to a struct representing the expected pointer
 520       type. flags is either zero or SWIG_POINTER_DISOWN (see below).
 521     </p>
 522
 523 <H3><a name="collection"></a>19.6.1 Garbage collection</H3>
 524
 525
 526   <p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a
 527      finalizer to the type which will call the destructor or delete method of
 528      that type.  The destructor and delete functions are no longer exported for
 529      use in scheme code, instead SWIG and chicken manage pointers.
 530   In situations where SWIG knows that a function is returning a type that should
 531   be garbage collected, SWIG will automatically set the owner flag to 1.  For other functions,
 532   the <code>%newobject</code> directive must be specified for functions whose return values
 533   should be garbage collected.  See
 534   <a href="Customization.html#ownership">Object ownership and %newobject</a> for more information.
 535   </p>
 536
 537   <p>In situations where a C or C++ function will assume ownership of a pointer, and thus
 538   chicken should no longer garbage collect it, SWIG provides the <code>DISOWN</code> input typemap.
 539   After applying this typemap (see the <a href="Typemaps.html">Typemaps chapter</a> for more information on how to apply typemaps),
 540   any pointer that gets passed in will no longer be garbage collected.
 541   An object is disowned by passing the <code>SWIG_POINTER_DISOWN</code> flag to <code>SWIG_ConvertPtr</code>.
 542   <b>Warning:</b> Since the lifetime of the object is now controlled by the underlying code, the object might
 543   get deleted while the scheme code still holds a pointer to it.  Further use of this pointer
 544   can lead to a crash.
 545   </p>
 546
 547   <p>Adding a finalizer function from C code was added to chicken in the 1.89 release, so garbage collection
 548   does not work for chicken versions below 1.89.  If you would like the SWIG generated code to work with
 549   chicken 1.40 to 1.89, pass the <code>-nocollection</code> argument to SWIG.  This will not export code
 550   inside the _wrap.c file to register finalizers, and will then export destructor functions which
 551   must be called manually.
 552   </p>
 553
 554 <H2><a name="Chicken_nn18"></a>19.7 Unsupported features and known problems</H2>
 555
 556
 557     <ul>
 558       <li>No director support.</li>
 559       <li>No support for c++ standard types like std::vector.</li>
 560       <li>The TinyCLOS wrappers for overloaded functions will not work correctly when using
 561           <a href="SWIGPlus.html#SWIGPlus_default_args">%feature(compactdefaultargs)</a>.</li>
 562     </ul>
 563
 564 <H3><a name="Chicken_nn19"></a>19.7.1 TinyCLOS problems with Chicken version &lt;= 1.92</H3>
 565
 566
 567     <p>In Chicken versions equal to or below 1.92, TinyCLOS has a limitation such that generic methods do not properly work on methods
 568     with different number of specializers: TinyCLOS assumes that every method added to a generic function
 569     will have the same number of specializers. SWIG generates functions with different lengths of specializers
 570     when C/C++ functions are overloaded.  For example, the code</p>
 571
 572 <div class="code">
 573 <pre>
 574 class Foo {};
 575 int foo(int a, Foo *b);
 576 int foo(int a);
 577 </pre></div>
 578
 579 <p>will produce scheme code</p>
 580
 581 <div class="targetlang">
 582 <pre>
 583 (define-method (foo (arg0 &lt;top&gt;) (arg1 &lt;Foo&gt;)) (<i>call primitive function</i>))
 584 (define-method (foo (arg0 &lt;top&gt;)) (<i>call primitive function</i>))
 585 </pre></div>
 586
 587 <p>Using unpatched TinyCLOS, the second <code>(define-method)</code> will replace the first one,
 588 so calling <code>(foo 3 f)</code> will produce an error.</p>
 589
 590 <p>There are three solutions to this.  The easist is to upgrade to the latest Chicken version.  Otherwise, the
 591 file <tt>Lib/chicken/tinyclos-multi-generic.patch</tt> in the SWIG source contains a patch against
 592 tinyclos.scm inside the 1.92 chicken source to add support into TinyCLOS for multi-argument generics.  (This patch was accepted into Chicken)
 593 This requires chicken to be rebuilt and custom install of chicken.  An alternative is the <tt>Lib/chicken/multi-generic.scm</tt>
 594 file in the SWIG source.  This file can be loaded after TinyCLOS is loaded, and it will override some functions
 595 inside TinyCLOS to correctly support multi-argument generics.  Please see the comments at the top of both files for more information.</p>
 596
 597   </body>
 598 </html>