"Fossies" - the Fresh Open Source Software Archive 
Member "swig-4.1.1/Doc/Devel/runtime.txt" (30 Nov 2022, 7981 Bytes) of package /linux/misc/swig-4.1.1.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the last
Fossies "Diffs" side-by-side code changes report for "runtime.txt":
3.0.12_vs_4.0.0.
1 This file describes the necessary functions and interfaces a language module
2 needs to implement to take advantage of the run time type system. I assume you
3 have read the run-time section of the Typemaps chapter in the SWIG
4 documentation.
5
6 Last updated: February 23, 2005
7
8 The file we are concerned with here should be named langrun.swg. A good example
9 of a simple file is the Lib/mzscheme/mzrun.swg file. First, a few requirements
10 and notes:
11
12 1) Every function in this file should be declared static.
13
14 2) It should be inserted into the runtime section of the _wrap file from your
15 config file. The Lib/swigrun.swg file should be included before this file.
16 That is, you need to have
17 %runtime "swigrun.swg"
18 %runtime "langrun.swg"
19
20 3) You must also include the swiginit.swg file in the init section of the
21 wrapper. That is, you should have
22 %insert(init) "swiginit.swg"
23
24 4) From module.cxx, you need to call the SwigType_emit_type_table function, as
25 well as register types with SwigType_remember or SwigType_remember_clientdata
26
27 5) By convention, all functions in this file are of the form
28 SWIG_Language_Whatever, and #defines are used to rename SWIG API functions to
29 these function names
30
31 6) You need to call void SWIG_InitializeModule(void *clientdata) from your init
32 function.
33
34 7) You need to implement the runtimeCode() and defaultExternalRuntimeFilename()
35 functions inside module.cxx. runtimeCode should return all the language
36 specific runtime code as a string, and defaultExternalRuntimeFilename should
37 return a string for the default name of the external runtime header. This is
38 usually "swigpyrun.h", where "py" is replaced by the language name. These
39 two functions are used by the -external-runtime argument.
40
41 -------------------------------------------------------------------------------
42 Required Functions
43 -------------------------------------------------------------------------------
44 swig_module_info *SWIG_GetModule(void *clientdata);
45 void SWIG_SetModule(void *clientdata, swig_module_info *mod);
46
47 The SetModule function should store the mod argument into some globally
48 accessible variable in the target language. The action of these two functions
49 is to provide a way for multiple modules to share information. The SetModule
50 function should create a new global var named something like
51 "swig_runtime_data_type_pointer" SWIG_RUNTIME_VERSION SWIG_TYPE_TABLE_NAME
52 SWIG_RUNTIME_VERSION is currently defined as "2", and SWIG_TYPE_TABLE_NAME is
53 defined by the -DSWIG_TYPE_TABLE=mytable option when compiling the wrapper.
54
55 Alternatively, if the language supports modules, a module named
56 "swig_runtime_data" SWIG_RUNTIME_VERSION can be created, and a global variable
57 named "type_table" SWIG_TYPE_TABLE_NAME can be created inside it. The most
58 common approach is to store the mod pointer in some global variable in the
59 target language, but if the language provides an alternative place to store data
60 then that is good too.
61
62 The way the code is set up, SetModule should only be called when GetModule
63 returns NULL, and if SetModule is called a second time, the behavior is
64 undefined. Just make sure it doesn't crash in the random chance occurrence that
65 SetModule is called twice.
66
67 There are two options here.
68
69 1) The preferred approach is for GetModule and SetModule to not require a
70 clientdata pointer. If you can at all avoid it, please do so. Here, you would
71 write swig_module_info *SWIG_Language_GetModule();
72 void SWIG_Language_SetModule(swig_module_info *mod);
73 and then add
74 #define SWIG_GetModule(clientdata) SWIG_Language_GetModule()
75 #define SWIG_SetModule(cd, ptr) SWIG_Language_SetModule(ptr)
76 You would then call
77 SWIG_InitializeModule(0)
78
79 2) If GetModule and SetModule need to take a custom pointer (most notably an
80 environment pointer, see tcl or mzscheme), then you should write
81 swig_module_info *SWIG_Language_GetModule(void *clientdata)
82 void SWIG_Language_SetModule(void *clientdata, swig_module_info *mod);
83 and also define
84 #define SWIG_GetModule(cd) SWIG_Language_GetModule(cd)
85 #define SWIG_SetModule(cd, ptr) SWIG_Language_SetModule(cd, ptr)
86 #define SWIG_MODULE_CLIENTDATA_TYPE Whatever
87 SWIG_MODULE_CLIENTDATA_TYPE should be defined to whatever the type of
88 clientdata is.
89
90 You would then call SWIG_InitializeModule(clientdata), and clientdata would get
91 passed to GetModule and SetModule. clientdata will not be stored and will only
92 be referenced during the InitializeModule call. After InitializeModule returns,
93 clientdata does not need to be valid any more.
94
95 This method is not preferred, because it makes external access to the type
96 system more complicated. See the Modules chapter of the documentation, and read
97 the "External access to the run-time" section. Then take a look at
98 Lib/runtime.swg. Anybody that calls SWIG_TypeQuery needs to pass along the
99 clientdata pointer, and that is the reason for defining
100 SWIG_MODULE_CLIENTDATA_TYPE.
101
102 -------------------------------------------------------------------------------
103 Standard Functions
104 -------------------------------------------------------------------------------
105 These functions are not required and their API is not formalized, but almost all
106 language modules implement them for consistency across languages. Throughout
107 this discussion, I will use LangType to represent the underlying language type
108 (Scheme_Object * in mzscheme, PyObject * in python, etc)
109
110
111
112 LangObj SWIG_NewPointerObj(void *ptr, swig_type_info *type, int flags);
113 Create and return a new pointer object that has both ptr and type. For almost
114 all language modules, flags is used for ownership. If flags==1, then the
115 created pointer should be registered to be garbage collected.
116
117
118
119 int SWIG_ConvertPtr(LangType obj, void **result, swig_type_info *type, int flags);
120 Convert a language wrapped pointer into a void *. The pointer is returned in
121 result, and the function should return 0 on success, non-zero on error.
122 A sample ConvertPtr is given here:
123
124 swig_cast_info *cast;
125
126 if (<obj is a wrapped pointer type>) {
127 cast = SWIG_TypeCheck(<obj type name>, type);
128 cast = SWIG_TypeCheckStruct(<obj type structure>, type);
129 if (cast) {
130 *result = SWIG_TypeCast(cast, <obj pointer>);
131 return 0;
132 }
133 }
134 return 1;
135
136 Either TypeCheck or TypeCheckStruct can be called, depending on how the pointer
137 is wrapped in langtype. If obj stores the void pointer and the type name, then
138 the TypeCheck function should be used, while if obj stores the void pointer and
139 a pointer to the swig_type_info structure, then the TypeCheckStruct function
140 should be called. The TypeCheckStruct is slightly faster, since it does a
141 pointer comparison instead of a strcmp.
142
143 The flag argument to ConvertPtr is used in some languages for disowning a
144 pointer. If the wrapped C function is taking ownership of the pointer (that
145 means, the wrapped C function is responsible for deleting the object), then that
146 pointer should be removed from the garbage collector. We do that in the
147 ConvertPtr function. The pointer is still valid in the target language, but
148 when the target language type is garbage collected, it will not call the
149 associated destructor. Languages have a special typemap called DISOWN that can be
150 applied which passes this argument. All the languages have the flags argument
151 for consistency, and the flags argument can be ignored or used for some other
152 purpose.
153
154
155 void *SWIG_MustGetPtr(LangType obj, swig_type_info *type, int flags,
156 int argnum, const char *func_name) {
157 void *result;
158 if (SWIG_ConvertPtr(s, &result, type, flags)) {
159 generate runtime type error ("Error in func_name, expected a" +
160 type->str ? type->str : "void *" +
161 "at argument number" + argnum);
162 }
163 return result;
164 }
165 This function is optional, and the number and type of parameters can be
166 different, but is useful for typemap purposes:
167 %typemap(in) SWIGTYPE *, SWIGTYPE &, SWIGTYPE [] {
168 $1 = ($1_ltype)SWIG_MustGetPtr($input, $descriptor, 0, $argnum, FUNC_NAME);
169 }