diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2009-08-18 20:56:02 +0000 |
|---|---|---|
| committer | Lorry <lorry@roadtrain.codethink.co.uk> | 2012-09-25 16:59:08 +0000 |
| commit | 9f8a09ed743cedd9547bf0661d518647966ab114 (patch) | |
| tree | 9c7803d3b27a8ec22e91792ac7f7932efa128b20 /Examples/python/variables/index.html | |
| download | swig-tarball-master.tar.gz | |
Imported from /srv/lorry/lorry-area/swig-tarball/swig-1.3.40.tar.gz.HEADswig-1.3.40master
Diffstat (limited to 'Examples/python/variables/index.html')
| -rw-r--r-- | Examples/python/variables/index.html | 100 |
1 files changed, 100 insertions, 0 deletions
diff --git a/Examples/python/variables/index.html b/Examples/python/variables/index.html new file mode 100644 index 0000000..2940d8a --- /dev/null +++ b/Examples/python/variables/index.html @@ -0,0 +1,100 @@ +<html> +<head> +<title>SWIG:Examples:python:variables</title> +</head> + +<body bgcolor="#ffffff"> + +<tt>SWIG/Examples/python/variables/</tt> +<hr> + +<H2>Wrapping C Global Variables</H2> + +<p> +When a C global variable appears in an interface file, SWIG tries to +wrap it using a technique known as "variable linking." The idea is +pretty simple---we try to create a Python variable that magically +retrieves or updates the value of the underlying C variable when it is +accessed. Click <a href="example.i">here</a> to see a SWIG interface with some variable +declarations in it. + +<h2>Manipulating Variables from Python</h2> + +Before going any further, it is important to understand some important +differences between C and Python variables. In C, a variable is +simply a name that refers to a specific location in memory. For +example, when you declare a global variable '<tt>double a</tt>' you +know that somewhere in memory, 8 bytes have been set aside to hold a +<tt>double</tt> and that <tt>a</tt> is bound to this location for the +life of the program. In Python, variable creation is nothing more +than a naming operation. For example, when you say '<tt>a = 3</tt>', +'a' becomes a name that refers to some object '3'. Later on, if you say +'<tt>a = 7.5</tt>, the name 'a' is bound to an entirely different object +containing the value '7.5' (the contents of the original object are not +changed). The end result of this is that a variable in Python can refer +to a virtually unlimited number of different objects (memory locations) +over the lifetime of a program. + +<p> +Because of Python's somewhat unusual variable assignment semantics, it is not +possible to directly link a C global variable into an equivalent Python variable. +Instead, all C global variables are accessed as attributes of a special object +called 'cvar'. For example, if you had a global variable + +<blockquote> +<pre> +double foo; +</pre> +</blockquote> + +it will be accessed in the Python module as <tt>cvar.foo</tt>. Click +<a href="example.py">here</a> to see a script that updates and prints +out the values of the variables using this technique. + +<h2>Key points</h2> + +<ul> +<li>When a global variable has the type "<tt>char *</tt>", SWIG manages it as a character +string. However, whenever the value of such a variable is set from Python, the old +value is destroyed using <tt>free()</tt> or <tt>delete</tt> (the choice of which depends +on whether or not SWIG was run with the -c++ option). +<li><tt>signed char</tt> and <tt>unsigned char</tt> are handled as small 8-bit integers. +<li>String array variables such as '<tt>char name[256]</tt>' are managed as Python strings, but +when setting the value, the result is truncated to the maximum length of the array. Furthermore, the string is assumed to be null-terminated. +<li>When structures and classes are used as global variables, they are mapped into pointers. +Getting 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. +</ul> + +<h2>Creating read-only variables</h2> + +The <tt>%immutable</tt> and <tt>%mutable</tt> directives can be used to +specify a collection of read-only variables. For example: + +<blockquote> +<pre> +%immutable; +int status; +double blah; +... +%mutable; +</pre> +</blockquote> + +The <tt>%immutable</tt> directive remains in effect until it is explicitly disabled +using the <tt>%mutable</tt> directive. + +<h2>Comments</h2> +<ul> +<li>Management of global variables is one of the most problematic aspects +of C/C++ wrapping because the scripting interface and resulting memory management +is much trickier than simply creating a wrapper function. +<p> +<li>Because of the potential for a namespace conflict, you should not use +the <tt>from module import *</tt> statement for a SWIG module with global +variables. Doing so will cause a collision on the 'cvar' object should +more than one module be loaded in this manner. +</ul> + +</body> +</html> +<hr> |