Some updates to the chicken documenatation, a few more fixes
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@7080 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
John Lenz
parent
897e5ad40d
commit
a09045ab5c
6 changed files with 136 additions and 55 deletions
|
|
@ -1,6 +1,15 @@
|
|||
Version 1.3.25 (In progress)
|
||||
============================
|
||||
|
||||
03/17/2005: wuzzeb (John Lenz)
|
||||
[Chicken]
|
||||
+ Fix a whole bunch of bugs in the chicken module. The entire
|
||||
test suite now compiles, with the exception of the tests that require
|
||||
std_vector.i, std_deque.i, and so on, which chicken does not have yet.
|
||||
|
||||
+ Add support for %exception and %typemap(exceptions). Exceptions are
|
||||
thrown with a call to (abort) and can be handled by (handle-exceptions)
|
||||
|
||||
03/15/2005: wsfulton
|
||||
[Java] Patch from Scott Michel for directors. Modifications to the typemaps
|
||||
giving users fine control over memory ownership and lifetime of director classes.
|
||||
|
|
|
|||
|
|
@ -23,17 +23,21 @@
|
|||
<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_nn10">TinyCLOS</a>
|
||||
<li><a href="#Chicken_nn11">Compilation</a>
|
||||
<li><a href="#Chicken_nn12">Linkage</a>
|
||||
<li><a href="#Chicken_nn11">TinyCLOS</a>
|
||||
<li><a href="#Chicken_nn12">Compilation</a>
|
||||
<li><a href="#Chicken_nn13">Linkage</a>
|
||||
<ul>
|
||||
<li><a href="#Chicken_nn13">Shared library</a>
|
||||
<li><a href="#Chicken_nn14">Static binary</a>
|
||||
<li><a href="#Chicken_nn14">Shared library</a>
|
||||
<li><a href="#Chicken_nn15">Static binary</a>
|
||||
</ul>
|
||||
<li><a href="#Chicken_nn15">Typemaps</a>
|
||||
<li><a href="#Chicken_nn16">Pointers</a>
|
||||
<li><a href="#Chicken_nn17">Unsupported features and known problems</a>
|
||||
<li><a href="#Chicken_nn16">Typemaps</a>
|
||||
<li><a href="#Chicken_nn17">Pointers</a>
|
||||
<ul>
|
||||
<li><a href="#Chicken_nn18">Garbage collection</a>
|
||||
</ul>
|
||||
<li><a href="#Chicken_nn19">Unsupported features and known problems</a>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
|
@ -141,7 +145,6 @@
|
|||
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"></a>17.2 Code Generation</H2>
|
||||
|
|
@ -183,6 +186,7 @@
|
|||
<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"></a>17.2.3 Constants and Variables</H3>
|
||||
|
||||
|
|
@ -230,19 +234,55 @@
|
|||
parameters).
|
||||
</p>
|
||||
|
||||
<H2><a name="Chicken_nn10"></a>17.3 TinyCLOS</H2>
|
||||
<H3><a name="Chicken_nn10"></a>17.2.5 Exceptions</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#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 consiting 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
|
||||
<a href="http://www.call-with-current-continuation.org/manual/Exceptions.html#Exceptions">Chicken manual on Exceptions</a>
|
||||
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"></a>17.3 TinyCLOS</H2>
|
||||
|
||||
|
||||
<p>
|
||||
The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as:
|
||||
</p>
|
||||
<div class="code">
|
||||
Tiny CLOS is a Scheme implementation of a `kernelized' CLOS, with a
|
||||
"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.
|
||||
</div>
|
||||
comments and documentation."
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Almost all good Scheme books describe how to use metaobjects and
|
||||
|
|
@ -275,7 +315,7 @@
|
|||
|
||||
</p>
|
||||
|
||||
<H2><a name="Chicken_nn11"></a>17.4 Compilation</H2>
|
||||
<H2><a name="Chicken_nn12"></a>17.4 Compilation</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -289,7 +329,7 @@
|
|||
much simpler <tt>csc</tt> or <tt>csc.bat</tt>.
|
||||
</p>
|
||||
|
||||
<H2><a name="Chicken_nn12"></a>17.5 Linkage</H2>
|
||||
<H2><a name="Chicken_nn13"></a>17.5 Linkage</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -303,7 +343,7 @@
|
|||
loadable module.
|
||||
</p>
|
||||
|
||||
<H3><a name="Chicken_nn13"></a>17.5.1 Shared library</H3>
|
||||
<H3><a name="Chicken_nn14"></a>17.5.1 Shared library</H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -312,13 +352,13 @@
|
|||
in example.i and the C functions being wrapped are in example_impl.c.
|
||||
</p>
|
||||
|
||||
<div class="shell">
|
||||
<pre>
|
||||
$ swig -chicken example.i
|
||||
$ csc -svk example.scm example_impl.c example_wrap.c
|
||||
$ csi example.so test_script.scm
|
||||
</pre>
|
||||
</div>
|
||||
<div class="shell">
|
||||
<pre>
|
||||
$ swig -chicken example.i
|
||||
$ csc -svk example.scm example_impl.c example_wrap.c
|
||||
$ csi example.so test_script.scm
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
You must be careful not to name the example_impl.c file example.c because
|
||||
|
|
@ -331,20 +371,20 @@
|
|||
be accessable to the loader. You might need to set LD_LIBRARY_PATH.
|
||||
</p>
|
||||
|
||||
<H3><a name="Chicken_nn14"></a>17.5.2 Static binary</H3>
|
||||
<H3><a name="Chicken_nn15"></a>17.5.2 Static binary</H3>
|
||||
|
||||
|
||||
<p>Again, we can easily use csc to build a binary.</p>
|
||||
|
||||
<div class="shell">
|
||||
<pre>
|
||||
$ swig -chicken example.i
|
||||
$ csc -vk example.scm example_impl.c example_wrap.c test_script.scm -o example
|
||||
$ ./example
|
||||
</pre>
|
||||
</div>
|
||||
<div class="shell">
|
||||
<pre>
|
||||
$ swig -chicken example.i
|
||||
$ csc -vk example.scm example_impl.c example_wrap.c test_script.scm -o example
|
||||
$ ./example
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<H2><a name="Chicken_nn15"></a>17.6 Typemaps</H2>
|
||||
<H2><a name="Chicken_nn16"></a>17.6 Typemaps</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -353,7 +393,7 @@
|
|||
<code>Lib/chicken/chicken.swg</code>.
|
||||
</p>
|
||||
|
||||
<H2><a name="Chicken_nn16"></a>17.7 Pointers</H2>
|
||||
<H2><a name="Chicken_nn17"></a>17.7 Pointers</H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -383,17 +423,42 @@
|
|||
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.
|
||||
type. flags is either zero or SWIG_POINTER_DISOWN (see below).
|
||||
</p>
|
||||
|
||||
<H2><a name="Chicken_nn17"></a>17.8 Unsupported features and known problems</H2>
|
||||
<H3><a name="Chicken_nn18"></a>17.7.1 Garbage collection</H3>
|
||||
|
||||
|
||||
<p>If the owner flag in the SWIG_NewPointerObj is 1, NewPointerObj 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 completly manage pointers.
|
||||
</p>
|
||||
|
||||
<p>In situations where SWIG knows that a function is returning a type that should
|
||||
be garbage collected, SWIG will automaticly 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#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 this type, SWIG provides the DISOWN input typemap.
|
||||
After applying this typemap (see the Typemaps chapter 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 SWIG_POINTER_DISOWN flag to SWIG_ConvertPtr.
|
||||
<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>
|
||||
|
||||
<H2><a name="Chicken_nn19"></a>17.8 Unsupported features and known problems</H2>
|
||||
|
||||
|
||||
<ul>
|
||||
<li>No director support.</li>
|
||||
<li>No support for c++ standard types like std::vector.</li>
|
||||
<li>Importing multiple SWIG modules not working with TinyCLOS. (Planned on fixing for 1.3.25) </li>
|
||||
<li>Problems with complicated function overloading. (Planned on fixing for 1.3.25)</li>
|
||||
</ul>
|
||||
|
||||
</body>
|
||||
|
|
|
|||
|
|
@ -223,7 +223,7 @@
|
|||
<li><a href="SWIGPlus.html#SWIGPlus_nn29">Class extension</a>
|
||||
<li><a href="SWIGPlus.html#SWIGPlus_nn30">Templates</a>
|
||||
<li><a href="SWIGPlus.html#SWIGPlus_nn31">Namespaces</a>
|
||||
<li><a href="SWIGPlus.html#SWIGPlus_nn32">Exception specifiers</a>
|
||||
<li><a href="SWIGPlus.html#SWIGPlus_exception_specifications">Exception specifications</a>
|
||||
<li><a href="SWIGPlus.html#SWIGPlus_nn33">Pointers to Members</a>
|
||||
<li><a href="SWIGPlus.html#SWIGPlus_nn34">Smart pointers and operator->()</a>
|
||||
<li><a href="SWIGPlus.html#SWIGPlus_nn35">Using declarations and inheritance</a>
|
||||
|
|
@ -505,17 +505,21 @@
|
|||
<li><a href="Chicken.html#Chicken_nn7">Modules</a>
|
||||
<li><a href="Chicken.html#Chicken_nn8">Constants and Variables</a>
|
||||
<li><a href="Chicken.html#Chicken_nn9">Functions</a>
|
||||
<li><a href="Chicken.html#Chicken_nn10">Exceptions</a>
|
||||
</ul>
|
||||
<li><a href="Chicken.html#Chicken_nn10">TinyCLOS</a>
|
||||
<li><a href="Chicken.html#Chicken_nn11">Compilation</a>
|
||||
<li><a href="Chicken.html#Chicken_nn12">Linkage</a>
|
||||
<li><a href="Chicken.html#Chicken_nn11">TinyCLOS</a>
|
||||
<li><a href="Chicken.html#Chicken_nn12">Compilation</a>
|
||||
<li><a href="Chicken.html#Chicken_nn13">Linkage</a>
|
||||
<ul>
|
||||
<li><a href="Chicken.html#Chicken_nn13">Shared library</a>
|
||||
<li><a href="Chicken.html#Chicken_nn14">Static binary</a>
|
||||
<li><a href="Chicken.html#Chicken_nn14">Shared library</a>
|
||||
<li><a href="Chicken.html#Chicken_nn15">Static binary</a>
|
||||
</ul>
|
||||
<li><a href="Chicken.html#Chicken_nn15">Typemaps</a>
|
||||
<li><a href="Chicken.html#Chicken_nn16">Pointers</a>
|
||||
<li><a href="Chicken.html#Chicken_nn17">Unsupported features and known problems</a>
|
||||
<li><a href="Chicken.html#Chicken_nn16">Typemaps</a>
|
||||
<li><a href="Chicken.html#Chicken_nn17">Pointers</a>
|
||||
<ul>
|
||||
<li><a href="Chicken.html#Chicken_nn18">Garbage collection</a>
|
||||
</ul>
|
||||
<li><a href="Chicken.html#Chicken_nn19">Unsupported features and known problems</a>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
|
@ -938,6 +942,7 @@
|
|||
<li><a href="Python.html#Python_nn25">C++ namespaces</a>
|
||||
<li><a href="Python.html#Python_nn26">C++ templates</a>
|
||||
<li><a href="Python.html#Python_nn27">C++ Smart Pointers</a>
|
||||
<li><a href="Python.html#Python_nn27a">C++ Reference Counted Objects (ref/unref)</a>
|
||||
</ul>
|
||||
<li><a href="Python.html#Python_nn28">Further details on the Python class interface</a>
|
||||
<ul>
|
||||
|
|
|
|||
|
|
@ -959,6 +959,7 @@ generate code that prevents this. You will just have to be careful.
|
|||
|
||||
<H3><a name="Python_nn18"></a>26.3.5 Pointers</H3>
|
||||
|
||||
|
||||
<p>
|
||||
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no
|
||||
problem working with incomplete type information. Here is a rather
|
||||
|
|
@ -1910,6 +1911,7 @@ simply use the <tt>__deref__()</tt> method. For example:
|
|||
|
||||
<H3><a name="Python_nn27a"></a>26.3.15 C++ Reference Counted Objects (ref/unref)</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Another usual idiom in C++ is the use of reference counted
|
||||
objects. Consider for example:
|
||||
|
|
@ -2504,6 +2506,7 @@ class MyFoo(mymodule.Foo):
|
|||
|
||||
<H3><a name="Python_nn34"></a>26.5.2 Director classes</H3>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -27,6 +27,7 @@ extern "C" {
|
|||
#define SWIG_NewPointerObj(ptr, type, owner) \
|
||||
SWIG_Chicken_NewPointerObj((void*)ptr, type, owner, &known_space)
|
||||
#define swig_barf SWIG_Chicken_Barf
|
||||
#define SWIG_ThrowException(val) SWIG_Chicken_ThrowException(val)
|
||||
|
||||
#define SWIG_contract_assert(expr, message) if (!(expr)) { \
|
||||
SWIG_Chicken_Barf(SWIG_BARF1_CONTRACT_ASSERT, C_text(message)); } else
|
||||
|
|
@ -188,7 +189,7 @@ static void SWIG_Chicken_ThrowException(C_word value)
|
|||
|
||||
abort = C_block_item(abort, 0);
|
||||
if (C_immediatep(abort))
|
||||
SWIG_Chicken_Panic(C_text("`##sys#abort' is not defiend"));
|
||||
SWIG_Chicken_Panic(C_text("`##sys#abort' is not defined"));
|
||||
|
||||
C_save(value);
|
||||
C_do_apply(1, abort, C_SCHEME_UNDEFINED);
|
||||
|
|
|
|||
|
|
@ -252,17 +252,15 @@ SWIGINTERN void SWIG_exception_(int code, const char *msg) {
|
|||
|
||||
#ifdef SWIGCHICKEN
|
||||
%{
|
||||
#define CHICKEN_MSG_BUF_LEN 1024
|
||||
SWIGINTERN void SWIG_exception_(int code, const char *msg) {
|
||||
char msg_buf[CHICKEN_MSG_BUF_LEN];
|
||||
C_word *a;
|
||||
C_word scmmsg;
|
||||
C_word list;
|
||||
|
||||
sprintf (msg_buf, "Exception(%d): %.950s\n", code, msg);
|
||||
|
||||
a = C_alloc (C_SIZEOF_STRING (strlen (msg_buf)));
|
||||
scmmsg = C_string2 (&a, msg_buf);
|
||||
C_halt (scmmsg);
|
||||
a = C_alloc (C_SIZEOF_STRING (strlen (msg)) + C_SIZEOF_LIST(2));
|
||||
scmmsg = C_string2 (&a, (char *) msg);
|
||||
list = C_list(&a, 2, C_fix(code), scmmsg);
|
||||
SWIG_ThrowException(list);
|
||||
}
|
||||
#define SWIG_exception(a,b) SWIG_exception_((a),(b))
|
||||
%}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue