/tags/rel-1.3.35/Doc/Manual/Modules.html
HTML | 259 lines | 211 code | 46 blank | 2 comment | 0 complexity | efee333b18121f34a5a8274cb8d8f738 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4<title>Working with Modules</title>
5<link rel="stylesheet" type="text/css" href="style.css">
6</head>
7
8<body bgcolor="#ffffff">
9<H1><a name="Modules"></a>15 Working with Modules</H1>
10<!-- INDEX -->
11<div class="sectiontoc">
12<ul>
13<li><a href="#Modules_nn1">Basics</a>
14<li><a href="#Modules_nn2">The SWIG runtime code</a>
15<li><a href="#external_run_time">External access to the runtime</a>
16<li><a href="#Modules_nn4">A word of caution about static libraries</a>
17<li><a href="#Modules_nn5">References</a>
18<li><a href="#Modules_nn6">Reducing the wrapper file size</a>
19</ul>
20</div>
21<!-- INDEX -->
22
23
24
25<p>
26When first working with SWIG, users commonly start by creating a
27single module. That is, you might define a single SWIG interface that
28wraps some set of C/C++ code. You then compile all of the generated
29wrapper code into a module and use it. For large applications, however,
30this approach is problematic---the size of the generated wrapper code
31can be rather large. Moreover, it is probably easier to manage the
32target language interface when it is broken up into smaller pieces.
33</p>
34
35<p>
36This chapter describes the problem of using SWIG in programs
37where you want to create a collection of modules.
38</p>
39
40<H2><a name="Modules_nn1"></a>15.1 Basics</H2>
41
42
43<p>
44The basic usage case with multiple modules is when modules do not have
45cross-references (ie. when wrapping multiple independent C APIs). In that case,
46swig input files should just work out of the box - you simply create multiple
47wrapper .cxx files, link them into your application, and insert/load each in the
48scripting language runtime as you would do for the single module case.
49</p>
50
51<p>
52A bit more complex is the case in which modules need to share information.
53For example, when one module extends the class of the another by deriving from
54it:
55</p>
56
57<div class="code"><pre>
58%module base
59
60%inline %{
61class base {
62public:
63 int foo(void);
64};
65%}
66</pre></div>
67
68<div class="code"><pre>
69%module derived
70
71%import "base.i"
72
73%inline %{
74class derived : public base {
75public:
76 int bar(void);
77};
78%}
79</pre></div>
80
81<p>To create the wrapper properly, module <tt>derived</tt> needs to know the
82<tt>base</tt> class and that it's interface is covered in another module. The
83line <tt>%import "base.i"</tt> lets SWIG know exactly that. The common mistake here is
84to <tt>%import</tt> the <tt>.h</tt> file instead of the <tt>.i</tt>, which sadly won't do the trick. Another issue
85to take care of is that multiple dependent wrappers should not be linked/loaded
86in parallel from multiple threads as SWIG provides no locking - for more on that
87issue, read on.</p>
88
89<H2><a name="Modules_nn2"></a>15.2 The SWIG runtime code</H2>
90
91
92<p>
93Many of SWIG's target languages generate a set of functions commonly known as
94the "SWIG runtime." These functions are primarily related to the runtime type
95system which checks pointer types and performs other tasks such as proper
96casting of pointer values in C++. As a general rule, the statically typed target
97languages, such as Java, use the language's built in static type checking and
98have no need for a SWIG runtime. All the dynamically typed / interpreted
99languages rely on the SWIG runtime.
100</p>
101
102<p>
103The runtime functions are private to each SWIG-generated module. That is, the
104runtime functions are declared with "static" linkage and are visible only to the
105wrapper functions defined in that module. The only problem with this approach is
106that when more than one SWIG module is used in the same application, those
107modules often need to share type information. This is especially true for C++
108programs where SWIG must collect and share information about inheritance
109relationships that cross module boundaries.
110</p>
111
112<p>
113To solve the problem of sharing information across modules, a pointer to the
114type information is stored in a global variable in the target language
115namespace. During module initialization, type information is loaded into the
116global data structure of type information from all modules.
117</p>
118
119<p>
120There are a few trade offs with this approach. This type information is global
121across all SWIG modules loaded, and can cause type conflicts between modules
122that were not designed to work together. To solve this approach, the SWIG
123runtime code uses a define SWIG_TYPE_TABLE to provide a unique type table. This
124behavior can be enabled when compiling the generated _wrap.cxx or _wrap.c file
125by adding -DSWIG_TYPE_TABLE=myprojectname to the command line argument.
126</p>
127
128<p>
129Then, only modules compiled with SWIG_TYPE_TABLE set to myprojectname will share
130type information. So if your project has three modules, all three should be
131compiled with -DSWIG_TYPE_TABLE=myprojectname, and then these three modules will
132share type information. But any other project's types will not interfere or
133clash with the types in your module.
134</p>
135
136<p>
137Another issue relating to the global type table is thread safety. If two modules
138try and load at the same time, the type information can become corrupt. SWIG
139currently does not provide any locking, and if you use threads, you must make
140sure that modules are loaded serially. Be careful if you use threads and the
141automatic module loading that some scripting languages provide. One solution is
142to load all modules before spawning any threads, or use SWIG_TYPE_TABLE to
143separate type tables so they do not clash with each other.
144</p>
145
146<p>
147Lastly, SWIG uses a #define SWIG_RUNTIME_VERSION, located in Lib/swigrun.swg and
148near the top of every generated module. This number gets incremented when the
149data structures change, so that SWIG modules generated with different versions
150can peacefully coexist. So the type structures are separated by the
151(SWIG_TYPE_TABLE, SWIG_RUNTIME_VERSION) pair, where by default SWIG_TYPE_TABLE
152is empty. Only modules compiled with the same pair will share type information.
153</p>
154
155<H2><a name="external_run_time"></a>15.3 External access to the runtime</H2>
156
157
158<p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
159the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others sometimes need
160to be called. Calling these functions from a typemap is supported, since the typemap code
161is embedded into the <tt>_wrap.c</tt> file, which has those declarations available. If you need
162to call the SWIG run-time functions from another C file, there is one header you need
163to include. To generate the header that needs to be included, run the following command:
164
165<div class="shell"><pre>
166$ swig -python -external-runtime <filename>
167</pre></div>
168
169<p>The filename argument is optional and if it is not passed, then the default filename will
170be something like <tt>swigpyrun.h</tt>, depending on the language. This header file should
171be treated like any of the other _wrap.c output files, and should be regenerated when the
172_wrap files are. After including this header, your code will be able to call <tt>SWIG_TypeQuery</tt>,
173<tt>SWIG_NewPointerObj</tt>, <tt>SWIG_ConvertPtr</tt> and others. The exact argument parameters
174for these functions might differ between language modules; please check the language module chapters
175for more information.</p>
176
177<p>Inside this header the functions are declared static and are included inline into the file,
178and thus the file does not need to be linked against any SWIG libraries or code (you might still
179need to link against the language libraries like libpython-2.3). Data is shared between this
180file and the _wrap.c files through a global variable in the scripting language. It is also
181possible to copy this header file along with the generated wrapper files into your own package,
182so that you can distribute a package that can be compiled without SWIG installed (this works
183because the header file is self-contained, and does not need to link with anything).</p>
184
185<p>
186This header will also use the -DSWIG_TYPE_TABLE described above, so when
187compiling any code which includes the generated header file should define the
188SWIG_TYPE_TABLE to be the same as the module whose types you are trying to
189access.
190</p>
191
192<H2><a name="Modules_nn4"></a>15.4 A word of caution about static libraries</H2>
193
194
195<p>
196When working with multiple SWIG modules, you should take care not to use static
197libraries. For example, if you have a static library <tt>libfoo.a</tt> and you link a collection
198of SWIG modules with that library, each module will get its own private copy of the library code inserted
199into it. This is very often <b>NOT</b> what you want and it can lead to unexpected or bizarre program
200behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries.
201</p>
202
203<H2><a name="Modules_nn5"></a>15.5 References</H2>
204
205
206<p>
207Due to the complexity of working with shared libraries and multiple modules, it might be a good idea to consult
208an outside reference. John Levine's "Linkers and Loaders" is highly recommended.
209</p>
210
211<H2><a name="Modules_nn6"></a>15.6 Reducing the wrapper file size</H2>
212
213
214<p>
215Using multiple modules with the <tt>%import</tt> directive is the most common approach to modularising large projects.
216In this way a number of different wrapper files can be generated, thereby avoiding the generation of a single large wrapper file.
217There are a couple of alternative solutions for reducing the size of a wrapper file through the use of command line options and features.
218</p>
219
220<p>
221<b>-fcompact</b><br>
222This command line option will compact the size of the wrapper file without changing the code generated into the wrapper file.
223It simply removes blank lines and joins lines of code together.
224This is useful for compilers that have a maximum file size that can be handled.
225</p>
226
227<p>
228<b>-fvirtual</b><br>
229This command line option will remove the generation of superfluous virtual method wrappers.
230Consider the following inheritance hierarchy:
231</p>
232
233<div class="code">
234<pre>
235struct Base {
236 virtual void method();
237 ...
238};
239
240struct Derived : Base {
241 virtual void method();
242 ...
243};
244</pre>
245</div>
246
247<p>
248Normally wrappers are generated for both methods, whereas this command line option will suppress the generation of a wrapper for <tt>Derived::method</tt>.
249Normal polymorphic behaviour remains as <tt>Derived::method</tt> will still be called should you have
250a <tt>Derived</tt> instance and call the wrapper for <tt>Base::method</tt>.
251</p>
252
253<p>
254<b>%feature("compactdefaultargs")</b><br>
255This feature can reduce the number of wrapper methods when wrapping methods with default arguments. The section on <a href="SWIGPlus.html#SWIGPlus_default_args">default arguments</a> discusses the feature and its limitations.
256</p>
257
258</body>
259</html>