/trunk/Examples/python/variables/index.html
HTML | 100 lines | 83 code | 17 blank | 0 comment | 0 complexity | 22c0665050da7b79fee887ef39e574f4 MD5 | raw file
1<html> 2<head> 3<title>SWIG:Examples:python:variables</title> 4</head> 5 6<body bgcolor="#ffffff"> 7 8<tt>SWIG/Examples/python/variables/</tt> 9<hr> 10 11<H2>Wrapping C Global Variables</H2> 12 13<p> 14When a C global variable appears in an interface file, SWIG tries to 15wrap it using a technique known as "variable linking." The idea is 16pretty simple---we try to create a Python variable that magically 17retrieves or updates the value of the underlying C variable when it is 18accessed. Click <a href="example.i">here</a> to see a SWIG interface with some variable 19declarations in it. 20 21<h2>Manipulating Variables from Python</h2> 22 23Before going any further, it is important to understand some important 24differences between C and Python variables. In C, a variable is 25simply a name that refers to a specific location in memory. For 26example, when you declare a global variable '<tt>double a</tt>' you 27know that somewhere in memory, 8 bytes have been set aside to hold a 28<tt>double</tt> and that <tt>a</tt> is bound to this location for the 29life of the program. In Python, variable creation is nothing more 30than a naming operation. For example, when you say '<tt>a = 3</tt>', 31'a' becomes a name that refers to some object '3'. Later on, if you say 32'<tt>a = 7.5</tt>, the name 'a' is bound to an entirely different object 33containing the value '7.5' (the contents of the original object are not 34changed). The end result of this is that a variable in Python can refer 35to a virtually unlimited number of different objects (memory locations) 36over the lifetime of a program. 37 38<p> 39Because of Python's somewhat unusual variable assignment semantics, it is not 40possible to directly link a C global variable into an equivalent Python variable. 41Instead, all C global variables are accessed as attributes of a special object 42called 'cvar'. For example, if you had a global variable 43 44<blockquote> 45<pre> 46double foo; 47</pre> 48</blockquote> 49 50it will be accessed in the Python module as <tt>cvar.foo</tt>. Click 51<a href="example.py">here</a> to see a script that updates and prints 52out the values of the variables using this technique. 53 54<h2>Key points</h2> 55 56<ul> 57<li>When a global variable has the type "<tt>char *</tt>", SWIG manages it as a character 58string. However, whenever the value of such a variable is set from Python, the old 59value is destroyed using <tt>free()</tt> or <tt>delete</tt> (the choice of which depends 60on whether or not SWIG was run with the -c++ option). 61<li><tt>signed char</tt> and <tt>unsigned char</tt> are handled as small 8-bit integers. 62<li>String array variables such as '<tt>char name[256]</tt>' are managed as Python strings, but 63when setting the value, the result is truncated to the maximum length of the array. Furthermore, the string is assumed to be null-terminated. 64<li>When structures and classes are used as global variables, they are mapped into pointers. 65Getting the "value" returns a pointer to the global variable. Setting the value of a structure results in a memory copy from a pointer to the global. 66</ul> 67 68<h2>Creating read-only variables</h2> 69 70The <tt>%immutable</tt> and <tt>%mutable</tt> directives can be used to 71specify a collection of read-only variables. For example: 72 73<blockquote> 74<pre> 75%immutable; 76int status; 77double blah; 78... 79%mutable; 80</pre> 81</blockquote> 82 83The <tt>%immutable</tt> directive remains in effect until it is explicitly disabled 84using the <tt>%mutable</tt> directive. 85 86<h2>Comments</h2> 87<ul> 88<li>Management of global variables is one of the most problematic aspects 89of C/C++ wrapping because the scripting interface and resulting memory management 90is much trickier than simply creating a wrapper function. 91<p> 92<li>Because of the potential for a namespace conflict, you should not use 93the <tt>from module import *</tt> statement for a SWIG module with global 94variables. Doing so will cause a collision on the 'cvar' object should 95more than one module be loaded in this manner. 96</ul> 97 98</body> 99</html> 100<hr>