Examples/ruby/variables/index.html

   1 <html>
   2 <head>
   3 <title>SWIG:Examples:ruby:variables</title>
   4 </head>
   5
   6 <body bgcolor="#ffffff">
   7
   8 <tt>SWIG/Examples/ruby/variables/</tt>
   9 <hr>
  10
  11 <H2>Wrapping C Global Variables</H2>
  12
  13 <p>
  14 When a C global variable appears in an interface file, SWIG tries to
  15 wrap it using a technique known as "variable linking."  The idea is
  16 pretty simple---we try to create a Ruby variable (actually module method) that
  17 magically retrieves or updates the value of the underlying C variable when it is
  18 accessed.  Click <a href="example.i">here</a> to see a SWIG interface with some variable
  19 declarations in it.
  20
  21 <h2>Manipulating Variables from Ruby</h2>
  22
  23 Before going any further, it is important to understand some important
  24 differences between C and Ruby variables.  In C, a variable is
  25 simply a name that refers to a specific location in memory.  For
  26 example, when you declare a global variable '<tt>double a</tt>' you
  27 know 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
  29 life of the program.  In Ruby, variable creation is nothing more
  30 than 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
  33 containing the value '7.5' (the contents of the original object are not
  34 changed).  The end result of this is that a variable in Ruby can refer
  35 to a virtually unlimited number of different objects (memory locations)
  36 over the lifetime of a program.
  37
  38 <p>
  39 Because of Ruby's somewhat unusual variable assignment semantics, it is not
  40 possible to directly link a C global variable into an equivalent Ruby variable.
  41 Instead, all C global variables are accessed as attributes of the module.
  42 For example, if you had a global variable
  43
  44 <blockquote>
  45 <pre>
  46 double foo;
  47 </pre>
  48 </blockquote>
  49
  50 it will be accessed in the Ruby module as <tt>Example.foo</tt>. Click
  51 <a href="runme.rb">here</a> to see a script that updates and prints
  52 out 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
  58 string.   However, whenever the value of such a variable is set from Ruby, the old
  59 value is destroyed using <tt>free()</tt>.
  60 <li><tt>signed char</tt> and <tt>unsigned char</tt> are handled as small 8-bit integers.
  61 <li>String array variables such as '<tt>char name[256]</tt>' are managed as Ruby strings, but
  62 when setting the value, the result is truncated to the maximum length of the array.  Furthermore, the string is assumed to be null-terminated.
  63 <li>When structures and classes are used as global variables, they are mapped into pointers.
  64 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.
  65 </ul>
  66
  67 <h2>Creating read-only variables</h2>
  68
  69 The <tt>%immutable</tt> and <tt>%mutable</tt> directives can be used to
  70 specify a collection of read-only variables.  For example:
  71
  72 <blockquote>
  73 <pre>
  74 %immutable;
  75 int    status;
  76 double blah;
  77 ...
  78 %mutable;
  79 </pre>
  80 </blockquote>
  81
  82 The <tt>%immutable</tt> directive remains in effect until it is explicitly disabled
  83 using the <tt>%mutable</tt> directive.
  84
  85 <h2>Comments</h2>
  86 <ul>
  87 <li>Management of global variables is one of the most problematic aspects
  88 of C/C++ wrapping because the scripting interface and resulting memory management
  89 is much trickier than simply creating a wrapper function.
  90 </ul>
  91
  92 </body>
  93 </html>
  94 <hr>