From 78642fd6b143f7a133489bdf21106e4203afd789 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Mon, 3 Apr 2000 21:59:31 +0000 Subject: [PATCH] (Guile Support Internals): Expand Smobs section w/ explanation contributed by Matthias Koeppe. git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@373 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- SWIG/Doc/engineering.html | 76 ++++++++++++++++++++++++++++++--------- 1 file changed, 59 insertions(+), 17 deletions(-) diff --git a/SWIG/Doc/engineering.html b/SWIG/Doc/engineering.html index 411bf1f8e..5f784e2ee 100644 --- a/SWIG/Doc/engineering.html +++ b/SWIG/Doc/engineering.html @@ -420,8 +420,8 @@ prefix the context, e.g., "guile-module". Guile support is complicated by a lack of user community cohesiveness, which manifests in multiple shared-library usage conventions. A set of policies implementing a usage convention is called a linkage. The default -linkage is the simplest; nothing special is done. In this case `SWIG_init()' -is provided and users must do something like this: +linkage is the simplest; nothing special is done. In this case +SWIG_init() is provided and users must do something like this: 
@@ -430,8 +430,11 @@ is provided and users must do something like this:
-At this time, the name `SWIG_init' is hardcoded; this approach does not work -with multiple swig-modules. +At this time, the name SWIG_init is hardcoded; this approach does +not work with multiple swig-modules. NOTE: The "simple" and "matrix" examples +under Examples/guile include guilemain.i; the resulting standalone interpreter +does not require calls to dynamic-link and +dynamic-call, as shown here.

A second linkage creates "libtool dl module" wrappers, and currently is @@ -440,9 +443,9 @@ convention, since that is not finalized.

The only other linkage supported at this time creates shared object libraries -suitable for use by hobbit's `(hobbit4d link)' guile module. This is called -the "hobbit" linkage, and requires also using the "-package" command line -option to set the part of the module name before the last symbol. For +suitable for use by hobbit's (hobbit4d link) guile module. This +is called the "hobbit" linkage, and requires also using the "-package" command +line option to set the part of the module name before the last symbol. For example, both command lines: [checkme:ttn]

@@ -452,15 +455,15 @@ swig -guile -package my/lib -module foo foo.i
-would create module `(my lib foo)' (assuming in the first case foo.i declares -the module to be "foo"). The installed files are my/lib/libfoo.so.X.Y.Z and -friends. This scheme is still very experimental; the (hobbit4d link) -conventions are not well understood. +would create module (my lib foo) (assuming in the first case +foo.i declares the module to be "foo"). The installed files are +my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very experimental; +the (hobbit4d link) conventions are not well understood.

There are no other linkage types planned, but that could change... To add a new type, add the name to the enum in guile.h and add the case to -`GUILE::emit_linkage()'. +GUILE::emit_linkage().

Underscore Folding

@@ -488,13 +491,52 @@ in foo.i. This may change in the future.

Smobs

-For pointer types, SWIG can use Guile smobs if given the command-line option -"-with-smobs". Ultimately this will be the default (and only) behavior and -the command-line option will no longer be supported. Ideally, "-with-smobs" -will not even make it to beta. +For pointer types, SWIG can use Guile smobs if given the command-line +option "-with-smobs". Ultimately this will be the default (and only) +behavior and the command-line option will no longer be supported. +Ideally, "-with-smobs" will not even make it to beta.

-[insert smob implementation overview here (Matthias Koeppe?)] +Currently, one wrapper module must be generated without +-c and compiled with -DSWIG_GLOBAL, all the +other wrapper modules must be generated with -c. Maybe +one should move all the global helper functions that come from +guile.swg into a library, which is built by make +runtime. + +

+In earlier versions of SWIG, C pointers were represented as Scheme +strings containing a hexadecimal rendering of the pointer value and a +mangled type name. As Guile allows registering user types, so-called +"smobs" (small objects), a much cleaner representation has been +implemented now. The details will be discussed in the following. + +

+A smob is a cons cell where the lower half of the CAR contains the +smob type tag, while the upper half of the CAR and the whole CDR are +available. SWIG_Guile_Init() registers a smob type named +"swig" with Guile; its type tag is stored in the variable +swig_tag. The upper half of the CAR store an index into +a table of all C pointer types seen so far, to which new types seen +are appended. The CDR stores the pointer value. SWIG smobs print +like this: #<swig struct xyzzy * 0x1234affe> Two of +them are equal? if and only if they have the same type +and value. + +

+To construct a Scheme object from a C pointer, the wrapper code calls +the function SWIG_Guile_MakePtr_Str(), passing both a +mangled type string and a pretty type string. The former is looked up +in the type table to get the type index to store in the upper half of +the CAR. If the type is new, it is appended to type table. + +

+To get the pointer represented by a smob, the wrapper code calls the +function SWIG_Guile_GetPtr_Str, passing the mangled name +of the expected pointer type, which is used for looking up the type in +the type table and accessing the list of compatible types. If the +Scheme object passed was not a SWIG smob representing a compatible +pointer, a wrong-type-arg exception is raised.

11. Miscellaneous