Rings
Multiple Lua States

Introduction

Rings is a library which provides a way to create new Lua states from within Lua. It also offers a simple way to communicate between the creator (master) and the created (slave) states.

Rings is free software and uses the same license as Lua 5.0.

Rings comprises a single C source file. The distribution provides a Makefile prepared to compile the library and install it. The file config should be edited to suit the needs of the target platform.

Rings also offers Stable, a very simple API to manage a shared table at the master state.

Installation

Rings library follows the package model for Lua 5.1, therefore it should be "installed". Refer to Compat-5.1 configuration section about how to install the compiled binary properly. The compiled binary should be copied to a directory in your LUA_CPATH.

Windows users can use the precompiled versions of Rings available at LuaForge

The file stable.lua should be copied to a directory in your LUA_PATH.

Reference

Master functions

Rings offers a single function which creates a new Lua state and returns an object representing it. The state which creates other states is called the master and the created ones are called slaves. The master can execute code in any of its slaves but each slave only has access to its master (or its own slaves).

All standard Lua libraries are opened automatically in a new state; other libraries have to be loaded explicitly.

The object representing a slave state has a method (dostring) which can execute Lua code in the corresponding state. This method can receive arguments (only numbers, strings, booleans and userdata, which are converted to lightuserdata) and always returns a boolean indicating whether the code executed correctly or not, followed by eventual return values or an error message.

rings.new ()
Returns a newly created Lua state.
state:close ()
Closes the state.
state:dostring (string, ...)
Executes a string in the slave state. The arguments are stored into arg table in the slave state. Valid types of arguments and return values are: number, string, boolean, nil and userdata (which are converted to lightuserdata). Returns a boolean indicating the status of the operation and the returned values or an error message in case of error.

Slave function

The following function is registered in the newly created slave state.

remotedostring (string, ...)
Executes a string in the master state. The arguments are stored into arg table in the master state. Valid types of arguments and return values are: number, string, boolean, nil and userdata (which are converted to lightuserdata). Returns a boolean indicating the status of the operation and the returned values or an error message in case of error.

Stable

Stable is a simple API which provides a way for a slave state to store and retrieve data to and from its master state. This library is not opened automatically in a slave state.

stable.get (key)
Returns the value of a given key.
stable.set (key, value)
Stores a value associated to a key. Returns nothing.

Examples

The following sample shows how to execute code in another state passing arguments and returning values:

require"rings"
S = rings.new ()

data = { 12, 13, 14, }
print (S:dostring ([[
aux = {}
for i, v in ipairs (arg) do
	table.insert (aux, 1, v)
end
return unpack (aux)]], unpack (data))) -- true, 14, 13, 12

S:close ()

The following example uses Stable to store a value in the master state:

require"rings"

local init_cmd = [[
LUA_PATH = "]]..package.path..[["
require"compat-5.1"
require"stable"]]

local count_cmd = [[
count = stable.get"shared_counter" or 0
stable.set ("shared_counter", count + 1)
return count
]]

S = rings.new () -- new state
assert(S:dostring (init_cmd))
print (S:dostring (count_cmd)) -- true, 0
print (S:dostring (count_cmd)) -- true, 1
S:close ()

S = rings.new () -- another new state
assert (S:dostring (init_cmd))
print (S:dostring (count_cmd)) -- true, 2
S:close ()

Valid XHTML 1.0!

$Id: manual.html,v 1.11 2006/03/09 21:35:58 carregal Exp $