PageRenderTime 9ms CodeModel.GetById 2ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 0ms

/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>