jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Some updates to the chicken documenatation, a few more fixes

Browse source 
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 2005-03-17 22:19:46 +00:00
commit a09045ab5c
6 changed files with 136 additions and 55 deletions
Download patch file Download diff file Expand all files Collapse all files

9
CHANGES.current
View file

@ -1,6 +1,15 @@
Version 1.3.25 (In progress) 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 03/15/2005: wsfulton
[Java] Patch from Scott Michel for directors. Modifications to the typemaps [Java] Patch from Scott Michel for directors. Modifications to the typemaps
giving users fine control over memory ownership and lifetime of director classes. giving users fine control over memory ownership and lifetime of director classes.

141
Doc/Manual/Chicken.html
View file

@ -23,17 +23,21 @@
<li><a href="#Chicken_nn7">Modules</a> <li><a href="#Chicken_nn7">Modules</a>
<li><a href="#Chicken_nn8">Constants and Variables</a> <li><a href="#Chicken_nn8">Constants and Variables</a>
<li><a href="#Chicken_nn9">Functions</a> <li><a href="#Chicken_nn9">Functions</a>
<li><a href="#Chicken_nn10">Exceptions</a>
</ul> </ul>
<li><a href="#Chicken_nn10">TinyCLOS</a> <li><a href="#Chicken_nn11">TinyCLOS</a>
<li><a href="#Chicken_nn11">Compilation</a> <li><a href="#Chicken_nn12">Compilation</a>
<li><a href="#Chicken_nn12">Linkage</a> <li><a href="#Chicken_nn13">Linkage</a>
<ul> <ul>
<li><a href="#Chicken_nn13">Shared library</a> <li><a href="#Chicken_nn14">Shared library</a>
<li><a href="#Chicken_nn14">Static binary</a> <li><a href="#Chicken_nn15">Static binary</a>
</ul> </ul>
<li><a href="#Chicken_nn15">Typemaps</a> <li><a href="#Chicken_nn16">Typemaps</a>
<li><a href="#Chicken_nn16">Pointers</a> <li><a href="#Chicken_nn17">Pointers</a>
<li><a href="#Chicken_nn17">Unsupported features and known problems</a> <ul>
<li><a href="#Chicken_nn18">Garbage collection</a>
</ul>
<li><a href="#Chicken_nn19">Unsupported features and known problems</a>
</ul> </ul>
</div> </div>
<!-- INDEX --> <!-- INDEX -->
@ -141,7 +145,6 @@
So for the C++ mode of SWIG CHICKEN, <tt>example_wrap.cxx</tt> 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 and <tt>oexample.c</tt> are the files that must be compiled to
object files and linked into your project. object files and linked into your project.
</p> </p>
<H2><a name="Chicken_nn5"></a>17.2 Code Generation</H2> <H2><a name="Chicken_nn5"></a>17.2 Code Generation</H2>
@ -183,6 +186,7 @@
<p> <p>
CHICKEN will be able to access the module using the <code>(declare CHICKEN will be able to access the module using the <code>(declare
(uses <i>modulename</i>))</code> CHICKEN Scheme form. (uses <i>modulename</i>))</code> CHICKEN Scheme form.
</p>
<H3><a name="Chicken_nn8"></a>17.2.3 Constants and Variables</H3> <H3><a name="Chicken_nn8"></a>17.2.3 Constants and Variables</H3>
@ -230,19 +234,55 @@
parameters). parameters).
</p> </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> <p>
The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as: The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as:
</p> "Tiny CLOS is a Scheme implementation of a `kernelized' CLOS, with a
<div class="code">
Tiny CLOS is a Scheme implementation of a `kernelized' CLOS, with a
metaobject protocol. The implementation is even simpler than metaobject protocol. The implementation is even simpler than
the simple CLOS found in `The Art of the Metaobject Protocol,' the simple CLOS found in `The Art of the Metaobject Protocol,'
weighing in at around 850 lines of code, including (some) weighing in at around 850 lines of code, including (some)
comments and documentation. comments and documentation."
</div> </p>
<p> <p>
Almost all good Scheme books describe how to use metaobjects and Almost all good Scheme books describe how to use metaobjects and
@ -275,7 +315,7 @@
</p> </p>
<H2><a name="Chicken_nn11"></a>17.4 Compilation</H2> <H2><a name="Chicken_nn12"></a>17.4 Compilation</H2>
<p> <p>
@ -289,7 +329,7 @@
much simpler <tt>csc</tt> or <tt>csc.bat</tt>. much simpler <tt>csc</tt> or <tt>csc.bat</tt>.
</p> </p>
<H2><a name="Chicken_nn12"></a>17.5 Linkage</H2> <H2><a name="Chicken_nn13"></a>17.5 Linkage</H2>
<p> <p>
@ -303,7 +343,7 @@
loadable module. loadable module.
</p> </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> <p>
@ -312,13 +352,13 @@
in example.i and the C functions being wrapped are in example_impl.c. in example.i and the C functions being wrapped are in example_impl.c.
</p> </p>
<div class="shell"> <div class="shell">
<pre> <pre>
$ swig -chicken example.i $ swig -chicken example.i
$ csc -svk example.scm example_impl.c example_wrap.c $ csc -svk example.scm example_impl.c example_wrap.c
$ csi example.so test_script.scm $ csi example.so test_script.scm
</pre> </pre>
</div> </div>
<p> <p>
You must be careful not to name the example_impl.c file example.c because 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. be accessable to the loader. You might need to set LD_LIBRARY_PATH.
</p> </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> <p>Again, we can easily use csc to build a binary.</p>
<div class="shell"> <div class="shell">
<pre> <pre>
$ swig -chicken example.i $ swig -chicken example.i
$ csc -vk example.scm example_impl.c example_wrap.c test_script.scm -o example $ csc -vk example.scm example_impl.c example_wrap.c test_script.scm -o example
$ ./example $ ./example
</pre> </pre>
</div> </div>
<H2><a name="Chicken_nn15"></a>17.6 Typemaps</H2> <H2><a name="Chicken_nn16"></a>17.6 Typemaps</H2>
<p> <p>
@ -353,7 +393,7 @@
<code>Lib/chicken/chicken.swg</code>. <code>Lib/chicken/chicken.swg</code>.
</p> </p>
<H2><a name="Chicken_nn16"></a>17.7 Pointers</H2> <H2><a name="Chicken_nn17"></a>17.7 Pointers</H2>
<p> <p>
@ -383,17 +423,42 @@
wrapper code calls the function wrapper code calls the function
<code>SWIG_ConvertPtr(C_word s, void **result, swig_type_info *type, int flags)</code>, <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 passing a pointer to a struct representing the expected pointer
type. type. flags is either zero or SWIG_POINTER_DISOWN (see below).
</p> </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> <ul>
<li>No director support.</li> <li>No director support.</li>
<li>No support for c++ standard types like std::vector.</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>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> </ul>
</body> </body>

23
Doc/Manual/Contents.html
View file

@ -223,7 +223,7 @@
<li><a href="SWIGPlus.html#SWIGPlus_nn29">Class extension</a> <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_nn30">Templates</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn31">Namespaces</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_nn33">Pointers to Members</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn34">Smart pointers and operator-&gt;()</a> <li><a href="SWIGPlus.html#SWIGPlus_nn34">Smart pointers and operator-&gt;()</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn35">Using declarations and inheritance</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_nn7">Modules</a>
<li><a href="Chicken.html#Chicken_nn8">Constants and Variables</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_nn9">Functions</a>
<li><a href="Chicken.html#Chicken_nn10">Exceptions</a>
</ul> </ul>
<li><a href="Chicken.html#Chicken_nn10">TinyCLOS</a> <li><a href="Chicken.html#Chicken_nn11">TinyCLOS</a>
<li><a href="Chicken.html#Chicken_nn11">Compilation</a> <li><a href="Chicken.html#Chicken_nn12">Compilation</a>
<li><a href="Chicken.html#Chicken_nn12">Linkage</a> <li><a href="Chicken.html#Chicken_nn13">Linkage</a>
<ul> <ul>
<li><a href="Chicken.html#Chicken_nn13">Shared library</a> <li><a href="Chicken.html#Chicken_nn14">Shared library</a>
<li><a href="Chicken.html#Chicken_nn14">Static binary</a> <li><a href="Chicken.html#Chicken_nn15">Static binary</a>
</ul> </ul>
<li><a href="Chicken.html#Chicken_nn15">Typemaps</a> <li><a href="Chicken.html#Chicken_nn16">Typemaps</a>
<li><a href="Chicken.html#Chicken_nn16">Pointers</a> <li><a href="Chicken.html#Chicken_nn17">Pointers</a>
<li><a href="Chicken.html#Chicken_nn17">Unsupported features and known problems</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> </ul>
</div> </div>
<!-- INDEX --> <!-- INDEX -->
@ -938,6 +942,7 @@
<li><a href="Python.html#Python_nn25">C++ namespaces</a> <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_nn26">C++ templates</a>
<li><a href="Python.html#Python_nn27">C++ Smart Pointers</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> </ul>
<li><a href="Python.html#Python_nn28">Further details on the Python class interface</a> <li><a href="Python.html#Python_nn28">Further details on the Python class interface</a>
<ul> <ul>

3
Doc/Manual/Python.html
View file

@ -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> <H3><a name="Python_nn18"></a>26.3.5 Pointers</H3>
<p> <p>
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no
problem working with incomplete type information. Here is a rather 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> <H3><a name="Python_nn27a"></a>26.3.15 C++ Reference Counted Objects (ref/unref)</H3>
<p> <p>
Another usual idiom in C++ is the use of reference counted Another usual idiom in C++ is the use of reference counted
objects. Consider for example: objects. Consider for example:
@ -2504,6 +2506,7 @@ class MyFoo(mymodule.Foo):
<H3><a name="Python_nn34"></a>26.5.2 Director classes</H3> <H3><a name="Python_nn34"></a>26.5.2 Director classes</H3>

3
Lib/chicken/chickenrun.swg
View file

@ -27,6 +27,7 @@ extern "C" {
#define SWIG_NewPointerObj(ptr, type, owner) \ #define SWIG_NewPointerObj(ptr, type, owner) \
SWIG_Chicken_NewPointerObj((void*)ptr, type, owner, &known_space) SWIG_Chicken_NewPointerObj((void*)ptr, type, owner, &known_space)
#define swig_barf SWIG_Chicken_Barf #define swig_barf SWIG_Chicken_Barf
#define SWIG_ThrowException(val) SWIG_Chicken_ThrowException(val)
#define SWIG_contract_assert(expr, message) if (!(expr)) { \ #define SWIG_contract_assert(expr, message) if (!(expr)) { \
SWIG_Chicken_Barf(SWIG_BARF1_CONTRACT_ASSERT, C_text(message)); } else 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); abort = C_block_item(abort, 0);
if (C_immediatep(abort)) 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_save(value);
C_do_apply(1, abort, C_SCHEME_UNDEFINED); C_do_apply(1, abort, C_SCHEME_UNDEFINED);

12
Lib/exception.i
View file

@ -252,17 +252,15 @@ SWIGINTERN void SWIG_exception_(int code, const char *msg) {
#ifdef SWIGCHICKEN #ifdef SWIGCHICKEN
%{ %{
#define CHICKEN_MSG_BUF_LEN 1024
SWIGINTERN void SWIG_exception_(int code, const char *msg) { SWIGINTERN void SWIG_exception_(int code, const char *msg) {
char msg_buf[CHICKEN_MSG_BUF_LEN];
C_word *a; C_word *a;
C_word scmmsg; C_word scmmsg;
C_word list;
sprintf (msg_buf, "Exception(%d): %.950s\n", code, msg); a = C_alloc (C_SIZEOF_STRING (strlen (msg)) + C_SIZEOF_LIST(2));
scmmsg = C_string2 (&a, (char *) msg);
a = C_alloc (C_SIZEOF_STRING (strlen (msg_buf))); list = C_list(&a, 2, C_fix(code), scmmsg);
scmmsg = C_string2 (&a, msg_buf); SWIG_ThrowException(list);
C_halt (scmmsg);
} }
#define SWIG_exception(a,b) SWIG_exception_((a),(b)) #define SWIG_exception(a,b) SWIG_exception_((a),(b))
%} %}