60 |
61 |
Introduction
62 |
63 |
Rings is a library which provides a way to create new Lua states from within
64 | Lua. It also offers a simple way to communicate between the creator (master) and
65 | the created (slave) states.
66 |
67 |
Rings is free software and uses the same license
68 | as Lua 5.x (MIT).
69 |
70 |
Rings also offers Stable,
71 | a very simple API to manage a shared table at the master state.
72 |
73 |
74 |
Building
75 |
76 |
77 | Rings works with Lua 5.1, 5.2, 5.3, and LuaJIT. In order to build it the language library and header files
78 | for the desired Lua version must be installed properly.
79 |
80 |
81 |
82 | If you wish to install by hand, the distribution provides a
83 | Makefile prepared to compile the library and install it.
84 | The file config should be edited to suit the particularities of the target platform
85 | before running make.
86 | This file has some definitions like paths to the external libraries,
87 | compiler options and the like.
88 | One important definition is the Lua version,
89 | which is not obtained from the installed software.
90 |
91 |
92 |
Installation
93 |
94 |
95 | If you are using LuaRocks, just type
96 |
97 |
98 |
99 | luarocks install rings
100 |
101 |
102 |
103 | If you prefer to install manually, the compiled binary file should be copied to a directory in your
104 | C path.
105 | The file stable.lua should be copied to a directory in your
106 | Lua path.
107 |
108 |
109 |
Reference
110 |
111 |
Master functions
112 |
113 |
Rings offers a single function which creates a new Lua state and returns
114 | an object representing it. The state which creates other states is called
115 | the master and the created ones are called slaves.
116 | The master can execute code in any of its slaves but each slave only has
117 | direct access to its master (or its own slaves).
118 |
119 |
All standard Lua libraries are opened automatically in a new state;
120 | other libraries have to be loaded explicitly.
121 |
122 |
The object representing a slave state has a method (dostring)
123 | which can execute Lua code in the corresponding state.
124 | This method can receive arguments (only numbers, strings, booleans and userdata,
125 | which are converted to lightuserdata) and always returns a boolean indicating
126 | whether the code executed correctly or not, followed by eventual return values
127 | or an error message.
128 |
129 |
130 | - rings.new (env)
131 | - Returns a newly created Lua state. Takes an optional environment to be used by
132 |
remotedostring.
133 | If the environment is nil, it defaults to the master_M or _G tables.
134 |
135 | - state:close ()
136 | - Closes the state.
137 |
138 | - state:dostring (string, ...)
139 | - Executes a string in the slave state.
140 | The arguments could be accessed exactly as in a
141 | vararg
142 | function. Valid types of arguments and return values are:
143 | number, string, boolean, nil and userdata (which are converted
144 | to lightuserdata).
145 |
146 | Returns a boolean indicating the status of the operation,
147 | followed by the returned values or an error message in case of error.
148 |
149 |
150 |
151 |
Slave function
152 |
153 |
The following function is registered in the newly created slave state.
154 |
155 |
156 |
157 | - remotedostring (string, ...)
158 | - Executes a string in the master state.
159 | Behaves exactly as the method dostring
160 | except that it acts in the master state.
161 |
162 |
163 |
164 |
Stable
165 |
166 |
Stable is a simple API which provides a way for a slave state to store
167 | and retrieve data to and from its master state.
168 | This library is not opened automatically in a slave state.
169 |
170 |
171 |
172 | - stable.get (key)
173 | - Returns the value of a given key.
174 |
175 | - stable.set (key, value)
176 | - Stores a value associated to a key.
177 | Returns nothing.
178 |
179 |
180 |
181 |
182 |
Examples
183 |
184 |
The following sample shows how to execute code in another state passing
185 | arguments and returning values:
186 |
187 |
188 | local rings = require "rings"
189 |
190 | local code = [[
191 | local args_reversed = {}
192 |
193 | for _, value in ipairs({...}) do
194 | table.insert(args_reversed, 1, value)
195 | end
196 |
197 | return table.unpack(args_reversed)
198 | ]]
199 |
200 | local state = rings.new()
201 | print(state:dostring(code, 1, 2, 3)) -- true, 3, 2, 1
202 | state:close()
203 |
204 |
205 |
The following example uses Stable to store a value in the master state:
206 |
207 |
208 | local rings = require "rings"
209 |
210 | local code = [[
211 | local stable = require "stable"
212 |
213 | local count = stable.get("shared_counter") or 0
214 | stable.set("shared_counter", count + 1)
215 | return count
216 | ]]
217 |
218 | local state = rings.new()
219 | print(state:dostring(code)) -- true, 0
220 | print(state:dostring(code)) -- true, 1
221 | state:close()
222 |
223 | local another_state = rings.new()
224 | print(another_state:dostring(code)) -- true, 2
225 | another_state:close()
226 |
227 |
228 |
17 |