/trunk/Examples/python/variables/index.html

# · HTML · 100 lines · 83 code · 17 blank · 0 comment · 0 complexity · 22c0665050da7b79fee887ef39e574f4 MD5 · raw file 

    

  1. <html>
    2. 

  2. <head>
    3. 

  3. <title>SWIG:Examples:python:variables</title>
    4. 

  4. </head>
    5. 

  5. 

  6. <body bgcolor="#ffffff">
    7. 

  7. 

  8. <tt>SWIG/Examples/python/variables/</tt>
    9. 

  9. <hr>
    10. 

  10. 

  11. <H2>Wrapping C Global Variables</H2>
    12. 

  12. 

  13. <p>
    14. 

  14. When a C global variable appears in an interface file, SWIG tries to
    15. 

  15. wrap it using a technique known as "variable linking."  The idea is
    16. 

  16. pretty simple---we try to create a Python variable that magically
    17. 

  17. retrieves or updates the value of the underlying C variable when it is
    18. 

  18. accessed.  Click <a href="example.i">here</a> to see a SWIG interface with some variable
    19. 

  19. declarations in it.
    20. 

  20. 

  21. <h2>Manipulating Variables from Python</h2>
    22. 

  22. 

  23. Before going any further, it is important to understand some important
    24. 

  24. differences between C and Python variables.  In C, a variable is
    25. 

  25. simply a name that refers to a specific location in memory.  For
    26. 

  26. example, when you declare a global variable '<tt>double a</tt>' you
    27. 

  27. know that somewhere in memory, 8 bytes have been set aside to hold a
    28. 

  28. <tt>double</tt> and that <tt>a</tt> is bound to this location for the
    29. 

  29. life of the program.  In Python, variable creation is nothing more
    30. 

  30. than a naming operation.  For example, when you say '<tt>a = 3</tt>',
    31. 

  31. 'a' becomes a name that refers to some object '3'.  Later on, if you say
    32. 

  32. '<tt>a = 7.5</tt>, the name 'a' is bound to an entirely different object
    33. 

  33. containing the value '7.5' (the contents of the original object are not
    34. 

  34. changed).  The end result of this is that a variable in Python can refer
    35. 

  35. to a virtually unlimited number of different objects (memory locations)
    36. 

  36. over the lifetime of a program.
    37. 

  37. 

  38. <p>
    39. 

  39. Because of Python's somewhat unusual variable assignment semantics, it is not
    40. 

  40. possible to directly link a C global variable into an equivalent Python variable.
    41. 

  41. Instead, all C global variables are accessed as attributes of a special object
    42. 

  42. called 'cvar'.  For example, if you had a global variable
    43. 

  43. 

  44. <blockquote>
    45. 

  45. <pre>
    46. 

  46. double foo;
    47. 

  47. </pre>
    48. 

  48. </blockquote>
    49. 

  49. 

  50. it will be accessed in the Python module as <tt>cvar.foo</tt>. Click
    51. 

  51. <a href="example.py">here</a> to see a script that updates and prints
    52. 

  52. out the values of the variables using this technique.
    53. 

  53. 

  54. <h2>Key points</h2>
    55. 

  55. 

  56. <ul>
    57. 

  57. <li>When a global variable has the type "<tt>char *</tt>", SWIG manages it as a character
    58. 

  58. string.   However, whenever the value of such a variable is set from Python, the old
    59. 

  59. value is destroyed using <tt>free()</tt> or <tt>delete</tt> (the choice of which depends
    60. 

  60. on whether or not SWIG was run with the -c++ option).
    61. 

  61. <li><tt>signed char</tt> and <tt>unsigned char</tt> are handled as small 8-bit integers.
    62. 

  62. <li>String array variables such as '<tt>char name[256]</tt>' are managed as Python strings, but
    63. 

  63. when setting the value, the result is truncated to the maximum length of the array.  Furthermore, the string is assumed to be null-terminated.
    64. 

  64. <li>When structures and classes are used as global variables, they are mapped into pointers.
    65. 

  65. 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.
    66. 

  66. </ul>
    67. 

  67. 

  68. <h2>Creating read-only variables</h2>
    69. 

  69. 

  70. The <tt>%immutable</tt> and <tt>%mutable</tt> directives can be used to
    71. 

  71. specify a collection of read-only variables.  For example:
    72. 

  72. 

  73. <blockquote>
    74. 

  74. <pre>
    75. 

  75. %immutable;
    76. 

  76. int    status;
    77. 

  77. double blah;
    78. 

  78. ...
    79. 

  79. %mutable;
    80. 

  80. </pre>
    81. 

  81. </blockquote>
    82. 

  82. 

  83. The <tt>%immutable</tt> directive remains in effect until it is explicitly disabled
    84. 

  84. using the <tt>%mutable</tt> directive.
    85. 

  85. 

  86. <h2>Comments</h2>
    87. 

  87. <ul>
    88. 

  88. <li>Management of global variables is one of the most problematic aspects 
    89. 

  89. of C/C++ wrapping because the scripting interface and resulting memory management
    90. 

  90. is much trickier than simply creating a wrapper function.
    91. 

  91. <p>
    92. 

  92. <li>Because of the potential for a namespace conflict, you should not use
    93. 

  93. the <tt>from module import *</tt> statement for a SWIG module with global
    94. 

  94. variables.  Doing so will cause a collision on the 'cvar' object should 
    95. 

  95. more than one module be loaded in this manner.
    96. 

  96. </ul>
    97. 

  97. 

  98. </body>
    99. 

  99. </html>
    100. 

  100. <hr>
    101.