36
37
where you want to create a collection of modules.
39
<H2><a name="Modules_nn2"></a>15.1 The SWIG runtime code</H2>
43
Many of SWIG's target languages generate a set of functions
44
commonly known as the "SWIG runtime." These functions are
45
primarily related to the runtime type system which checks pointer
46
types and performs other tasks such as proper casting of pointer
47
values in C++. As a general rule, the statically typed target languages,
48
such as Java, use the language's built in static type checking and
40
<H2><a name="Modules_nn1"></a>15.1 Basics</H2>
44
The basic usage case with multiple modules is when modules do not have
45
cross-references (ie. when wrapping multiple independent C APIs). In that case,
46
swig input files should just work out of the box - you simply create multiple
47
wrapper .cxx files, link them into your application, and insert/load each in the
48
scripting language runtime as you would do for the single module case.
52
A bit more complex is the case in which modules need to share information.
53
For example, when one module extends the class of the another by deriving from
57
<div class="code"><pre>
68
<div class="code"><pre>
74
class derived : public base {
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
83
line <tt>%import "base.i"</tt> lets SWIG know exactly that. The common mistake here is
84
to <tt>%import</tt> the <tt>.h</tt> file instead of the <tt>.i</tt>, which sadly won't do the trick. Another issue
85
to take care of is that multiple dependent wrappers should not be linked/loaded
86
in parallel from multiple threads as SWIG provides no locking - for more on that
89
<H2><a name="Modules_nn2"></a>15.2 The SWIG runtime code</H2>
93
Many of SWIG's target languages generate a set of functions commonly known as
94
the "SWIG runtime." These functions are primarily related to the runtime type
95
system which checks pointer types and performs other tasks such as proper
96
casting of pointer values in C++. As a general rule, the statically typed target
97
languages, such as Java, use the language's built in static type checking and
49
98
have no need for a SWIG runtime. All the dynamically typed / interpreted
50
99
languages rely on the SWIG runtime.
54
The runtime functions are private to each SWIG-generated
55
module. That is, the runtime functions are declared with "static"
56
linkage and are visible only to the wrapper functions defined in that
57
module. The only problem with this approach is that when more than one SWIG
58
module is used in the same application, those modules often need to
59
share type information. This is especially true for C++ programs
60
where SWIG must collect and share information about inheritance
103
The runtime functions are private to each SWIG-generated module. That is, the
104
runtime functions are declared with "static" linkage and are visible only to the
105
wrapper functions defined in that module. The only problem with this approach is
106
that when more than one SWIG module is used in the same application, those
107
modules often need to share type information. This is especially true for C++
108
programs where SWIG must collect and share information about inheritance
61
109
relationships that cross module boundaries.
65
113
To solve the problem of sharing information across modules, a pointer to the
66
type information is stored in a global variable in the target language namespace.
67
During module initialization, type information is loaded into the global data
68
structure of type information from all modules.
72
This can present a problem with threads. If two modules try and load at the same
73
time, the type information can become corrupt. SWIG currently does not provide any
74
locking, and if you use threads, you must make sure that modules are loaded serially.
75
Be careful if you use threads and the automatic module loading that some scripting
76
languages provide. One solution is to load all modules before spawning any threads.
79
<H2><a name="external_run_time"></a>15.2 External access to the runtime</H2>
114
type information is stored in a global variable in the target language
115
namespace. During module initialization, type information is loaded into the
116
global data structure of type information from all modules.
120
There are a few trade offs with this approach. This type information is global
121
across all SWIG modules loaded, and can cause type conflicts between modules
122
that were not designed to work together. To solve this approach, the SWIG
123
runtime code uses a define SWIG_TYPE_TABLE to provide a unique type table. This
124
behavior can be enabled when compiling the generated _wrap.cxx or _wrap.c file
125
by adding -DSWIG_TYPE_TABLE=myprojectname to the command line argument.
129
Then, only modules compiled with SWIG_TYPE_TABLE set to myprojectname will share
130
type information. So if your project has three modules, all three should be
131
compiled with -DSWIG_TYPE_TABLE=myprojectname, and then these three modules will
132
share type information. But any other project's types will not interfere or
133
clash with the types in your module.
137
Another issue relating to the global type table is thread safety. If two modules
138
try and load at the same time, the type information can become corrupt. SWIG
139
currently does not provide any locking, and if you use threads, you must make
140
sure that modules are loaded serially. Be careful if you use threads and the
141
automatic module loading that some scripting languages provide. One solution is
142
to load all modules before spawning any threads, or use SWIG_TYPE_TABLE to
143
separate type tables so they do not clash with each other.
147
Lastly, SWIG uses a #define SWIG_RUNTIME_VERSION, located in Lib/swigrun.swg and
148
near the top of every generated module. This number gets incremented when the
149
data structures change, so that SWIG modules generated with different versions
150
can peacefully coexist. So the type structures are separated by the
151
(SWIG_TYPE_TABLE, SWIG_RUNTIME_VERSION) pair, where by default SWIG_TYPE_TABLE
152
is empty. Only modules compiled with the same pair will share type information.
155
<H2><a name="external_run_time"></a>15.3 External access to the runtime</H2>
82
158
<p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
added
removed
Doc/Manual/Modules.html
