This document describes what things to consider when using Kahlua inside your java application

Garbage collection

In the original Lua, garbage collection was done inside the Lua engine, which meant that it could not expose its objects to C directly since it would mean the garbage collector wouldn't know which objects had become unreachable. In Kahlua, garbage collection is handled fully by Java, which means that you can access and interact with objects in the Lua engine just as any other java object.

Userdata

The original Lua has userdata to support extending it with useful custom types. Kahlua also has this. You can pass any object into the lua engine, and by setting a metatable for it you can even use ordinary operators on them. Metatables are set pre class, and not per object. There's a very simple example on usage in se.krka.kahlua.test.UserdataArray

LuaState.setUserdataMetatable(Class c, LuaTable metatable) Use this to assign a metatable to a custom type. Use null as metatable to unset.

Differences compared to standard Lua

All metatable keys except for gc are supported. gc is unsupported because CLDC 1.1 doesn't have a way to report when an object gets garbage collected. Weak tables are implemented in the latest SVN. Kahlua requires that the mode entry be present once the metatable gets set. On this event, all keys and/or values will be made weak/un-weak references, depending on the mode setting.

Strings

Kahlua assumes the equality is identity for strings: In practice this means that all strings that you pass to Kahlua must have be interned. You may also assume that all strings that are values inside Kahlua are interned.

Thread safety

Kahlua is not thread safe in any way. Do not attempt to use a LuaState concurrently from different threads. Sharing LuaTables are possible, but you have to manually ensure that no two threads try to access a LuaTable at the same time.

Native functions

You most likely want to provide more functions for your lua environment to use. Any object that implements the JavaFunction interface may be passed to Kahlua. See the classes in se.krka.kahlua.stdlib for examples on usage. StringLib is probably the easiest to take a look at.

Loading Lua code

Kahlua does not come with a Lua compiler (unlike standard Lua). Instead Kahlua can load precompiled lua 5.1b bytecode.

Use luac -o output.lbc input.lua to compile a lua source file to bytecode. You can then use LuaPrototype.loadBytecode to get a lua closure. See se.krka.kahlua.test.Test to see examples of usage

Supported Lua versions

Kahlua only supports Lua 5.1 bytecode, without any of the 5.0 compat options.