Doc/Devel/runtime.txt

   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 (like the chicken module), 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 (C_word in chicken, 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 }