doc/rings/us/manual.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html>
   4 <head>
   5     <title>Rings: Multiple Lua States</title>
   6     <link rel="stylesheet" href="http://www.keplerproject.org/doc.css" type="text/css"/>
   7         <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
   8 </head>
   9
  10 <body>
  11 <div id="container">
  12
  13 <div id="product">
  14         <div id="product_logo"><a href="http://www.keplerproject.org">
  15                 <img alt="Rings logo" src="rings.png"/>
  16         </a></div>
  17         <div id="product_name"><big><strong>Rings</strong></big></div>
  18         <div id="product_description">Multiple Lua States</div>
  19 </div> <!-- id="product" -->
  20
  21 <div id="main">
  22
  23 <div id="navigation">
  24 <h1>Rings</h1>
  25         <ul>
  26                 <li><a href="index.html">Home</a>
  27                         <ul>
  28                                 <li><a href="index.html#overview">Overview</a></li>
  29                                 <li><a href="index.html#status">Status</a></li>
  30                                 <li><a href="index.html#download">Download</a></li>
  31                                 <li><a href="index.html#history">History</a></li>
  32                                 <li><a href="index.html#credits">Credits</a></li>
  33                                 <li><a href="index.html#contact">Contact us</a></li>
  34                         </ul>
  35                 </li>
  36                 <li><strong>Manual</strong>
  37                         <ul>
  38                                 <li><a href="manual.html#introduction">Introduction</a></li>
  39                                 <li><a href="manual.html#building">Building</a></li>
  40                                 <li><a href="manual.html#installation">Installation</a></li>
  41                                 <li><a href="manual.html#reference">Reference</a>
  42                     <ul>
  43                         <li><a href="manual.html#master_functions">Master functions</a></li>
  44                         <li><a href="manual.html#slave_functions">Slave functions</a></li>
  45                         <li><a href="manual.html#stable">Stable</a></li>
  46                             </ul>
  47                 </li>
  48                                 <li><a href="manual.html#examples">Examples</a></li>
  49                         </ul>
  50                 </li>
  51         <li><a href="http://luaforge.net/projects/rings/">Project</a>
  52             <ul>
  53                 <li><a href="http://luaforge.net/tracker/?group_id=147">Bug Tracker</a></li>
  54                 <li><a href="http://luaforge.net/scm/?group_id=147">CVS</a></li>
  55             </ul>
  56         </li>
  57                 <li><a href="license.html">License</a></li>
  58         </ul>
  59 </div> <!-- id="navigation" -->
  60
  61 <div id="content">
  62
  63 <h2><a name="introduction"></a>Introduction</h2>
  64
  65 <p>Rings is a library which provides a way to create new Lua states from within
  66 Lua. It also offers a simple way to communicate between the creator (master) and
  67 the created (slave) states.</p>
  68
  69 <p>Rings is free software and uses the same <a href="license.html">license</a>
  70 as Lua 5.1.</p>
  71
  72 <p>Rings also offers <a href="manual.html#stable">Stable</a>,
  73 a very simple API to manage a shared table at the master state.</p>
  74
  75
  76 <h2><a name="building"></a>Building</h2>
  77
  78 <p>
  79 Rings version 1.1.0 is for Lua 5.1 only. In order to build it
  80 the language library and header files for the desired Lua version must be
  81 installed properly.
  82 </p>
  83 <p>
  84 Rings comprises a single C source file.
  85 The distribution provides a
  86 <code>Makefile</code>
  87 prepared to compile the library and install it.
  88 The file
  89 <code>config</code>
  90 should be edited to suit the particularities of the target platform
  91 before running
  92 <code>make</code>.
  93 This file has some definitions like paths to the external libraries,
  94 compiler options and the like.
  95 One important definition is the Lua version,
  96 which is not obtained from the installed software.
  97 </p>
  98
  99 <h2><a name="installation"></a>Installation</h2>
 100
 101 <p>
 102 The compiled binary file should be copied to a directory in your
 103 <a href="http://www.lua.org/manual/5.1/manual.html#pdf-package.cpath">C
 104 path</a>.
 105 </p>
 106
 107 <p>
 108 Windows users can use the precompiled versions of Rings available at
 109 <a href="http://luaforge.net/projects/rings/files">LuaForge</a></p>
 110
 111 <p>
 112 The file <code>stable.lua</code> should be copied to a directory in your
 113 <a href="http://www.lua.org/manual/5.1/manual.html#pdf-package.path">Lua
 114 path</a>.
 115 </p>
 116
 117
 118 <h2><a name="reference"></a>Reference</h2>
 119
 120 <h3><a name="master_functions"></a>Master functions</h3>
 121
 122 <p>Rings offers a single function which creates a new Lua state and returns
 123 an object representing it. The state which creates other states is called
 124 the master and the created ones are called slaves.
 125 The master can execute code in any of its slaves but each slave only has
 126 direct access to its master (or its own slaves).</p>
 127
 128 <p>All standard Lua libraries are opened automatically in a new state;
 129 other libraries have to be loaded explicitly.</p>
 130
 131 <p>The object representing a slave state has a method (<code>dostring</code>)
 132 which can execute Lua code in the corresponding state.
 133 This method can receive arguments (only numbers, strings, booleans and userdata,
 134 which are converted to lightuserdata) and always returns a boolean indicating
 135 whether the code executed correctly or not, followed by eventual return values
 136 or an error message.</p>
 137
 138 <dl>
 139     <dt><strong><a name="rings_new"></a>rings.new ()</strong></dt>
 140     <dd>Returns a newly created Lua state.</dd>
 141
 142     <dt><strong><a name="rings_close"></a><em>state</em>:close ()</strong></dt>
 143     <dd>Closes the state.</dd>
 144
 145     <dt><strong><a name="rings_dostring"></a><em>state</em>:dostring (string, ...)</strong></dt>
 146     <dd>Executes a string in the slave state.
 147         The arguments could be accessed exactly as in a
 148         <a href="http://www.lua.org/manual/5.1/manual.html#2.5.9">vararg
 149         function</a>:
 150         in Lua 5.0, they are stored into the <code>arg</code> table;
 151         in Lua 5.1, the expression <code>...</code> represents all arguments.
 152         Valid types of arguments and return values are:
 153         number, string, boolean, nil and userdata (which are converted
 154         to lightuserdata).
 155         <br />
 156         Returns a boolean indicating the status of the operation,
 157         followed by the returned values or an error message in case of error.
 158     </dd>
 159 </dl>
 160
 161 <h3><a name="slave_functions"></a>Slave function</h3>
 162
 163 <p>The following function is registered in the newly created slave state.</p>
 164
 165 <dl>
 166
 167     <dt><strong><a name="rings_remotedostring"></a>remotedostring (string, ...)</strong></dt>
 168     <dd>Executes a string in the master state.
 169         Behaves exactly as the method <a href="#rings_dostring">dostring</a>
 170         except that it acts in the master state.
 171     </dd>
 172 </dl>
 173
 174 <h3><a name="stable"></a>Stable</h3>
 175
 176 <p>Stable is a simple API which provides a way for a slave state to store
 177 and retrieve data to and from its master state.
 178 This library is not opened automatically in a slave state.</p>
 179
 180 <dl>
 181
 182     <dt><strong><a name="stable_get"></a>stable.get (key)</strong></dt>
 183     <dd>Returns the value of a given <em>key</em>.</dd>
 184
 185     <dt><strong><a name="stable_set"></a>stable.set (key, value)</strong></dt>
 186     <dd>Stores a <em>value</em> associated to a <em>key</em>.
 187         Returns nothing.</dd>
 188
 189 </dl>
 190
 191
 192 <h2><a name="examples"></a>Examples</h2>
 193
 194 <p>The following sample shows how to execute code in another state passing
 195 arguments and returning values:</p>
 196
 197 <pre class="example">
 198 require"rings"
 199 S = rings.new ()
 200
 201 data = { 12, 13, 14, }
 202 print (S:dostring ([[
 203 aux = {}
 204 for i, v in ipairs (arg) do
 205         table.insert (aux, 1, v)
 206 end
 207 return unpack (aux)]], unpack (data))) -- true, 14, 13, 12
 208
 209 S:close ()
 210 </pre>
 211
 212 <p>The following example uses Stable to store a value in the master state:</p>
 213
 214 <pre class="example">
 215 require"rings"
 216
 217 local init_cmd = [[
 218 require"stable"]]
 219
 220 local count_cmd = [[
 221 count = stable.get"shared_counter" or 0
 222 stable.set ("shared_counter", count + 1)
 223 return count
 224 ]]
 225
 226 S = rings.new () -- new state
 227 assert(S:dostring (init_cmd))
 228 print (S:dostring (count_cmd)) -- true, 0
 229 print (S:dostring (count_cmd)) -- true, 1
 230 S:close ()
 231
 232 S = rings.new () -- another new state
 233 assert (S:dostring (init_cmd))
 234 print (S:dostring (count_cmd)) -- true, 2
 235 S:close ()
 236 </pre>
 237
 238 </div> <!-- id="content" -->
 239
 240 </div> <!-- id="main" -->
 241
 242 <div id="about">
 243         <p><a href="http://validator.w3.org/check?uri=referer">
 244     <img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
 245         <p><small>$Id: manual.html,v 1.14 2007/06/11 23:36:37 carregal Exp $</small></p>
 246 </div> <!-- id="about" -->
 247
 248 </div> <!-- id="container" -->
 249
 250 </body>
 251 </html>