"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.
    6 Last updated: February 23, 2005
    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:
   12 1) Every function in this file should be declared static.  
   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"
   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"
   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
   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
   31 6) You need to call void SWIG_InitializeModule(void *clientdata) from your init
   32 function.
   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.
   41 -------------------------------------------------------------------------------
   42 Required Functions
   43 -------------------------------------------------------------------------------
   44 swig_module_info *SWIG_GetModule(void *clientdata);
   45 void SWIG_SetModule(void *clientdata, swig_module_info *mod);
   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.
   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.
   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.
   67 There are two options here.  
   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)
   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.
   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.
   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
  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)
  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.
  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:
  124   swig_cast_info *cast;
  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;
  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.  
  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.
  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 }