org.luaj.vm2
Class LuaThread

java.lang.Object
  org.luaj.vm2.Varargs
      org.luaj.vm2.LuaValue
          org.luaj.vm2.LuaThread

public class LuaThread
extends LuaValue

Subclass of LuaValue that implements a lua coroutine thread using Java Threads.

A LuaThread is typically created in response to a scripted call to coroutine.create()

The threads must be initialized with the globals, so that the global environment may be passed along according to rules of lua. This is done via a call to setGlobals(LuaValue) at some point during globals initialization. See BaseLib for additional documentation and example code.

The utility classes JsePlatform and JmePlatform see to it that this initialization is done properly. For this reason it is highly recommended to use one of these classes when initializing globals.

The behavior of coroutine threads matches closely the behavior of C coroutine library. However, because of the use of Java threads to manage call state, it is possible to yield from anywhere in luaj.

Each Java thread wakes up at regular intervals and checks a weak reference to determine if it can ever be resumed. If not, it throws OrphanedThread which is an Error. Applications should not catch OrphanedThread, because it can break the thread safety of luaj.

See Also:

LuaValue, JsePlatform, JmePlatform, CoroutineLib

Nested Class Summary

static class

LuaThread.CallStack

Field Summary

static int	coroutine_count
java.lang.Object	debugState Thread-local used by DebugLib to store debugging state.
LuaValue	err Field to hold state of error condition during debug hook function calls.
static int	GC_INTERVAL Interval to check for LuaThread dereferencing.
static int	MAX_CALLSTACK
static LuaValue	s_metatable

Fields inherited from class org.luaj.vm2.LuaValue

ADD, CALL, CONCAT, DIV, EMPTYSTRING, EQ, FALSE, INDEX, LE, LEN, LT, METATABLE, MINUSONE, MOD, MODE, MUL, NEWINDEX, NIL, NILS, NONE, NOVALS, ONE, POW, SUB, TBOOLEAN, TFUNCTION, TINT, TLIGHTUSERDATA, TNIL, TNONE, TNUMBER, TOSTRING, TRUE, TSTRING, TTABLE, TTHREAD, TUSERDATA, TVALUE, TYPE_NAMES, UNM, ZERO

Constructor Summary

LuaThread(LuaValue func, LuaValue env)
Create a LuaThread around a function and environment

Method Summary

LuaThread	checkthread() Check that this is a LuaThread, or throw LuaError if it is not
static LuaFunction	getCallstackFunction(int level) Get the function called as a specific location on the stack.
LuaValue	getfenv() Get the environemnt for an instance.
static LuaValue	getGlobals() Get the current thread's environment
LuaValue	getmetatable() Get the metatable for this LuaValue
static LuaThread	getRunning() Get the currently running thread.
java.lang.String	getStatus()
static boolean	isMainThread(LuaThread r) Test if this is the main thread
boolean	isthread() Check if this is a thread
static LuaThread.CallStack	onCall(LuaFunction function) Callback used at the beginning of a call to prepare for possible getfenv/setfenv calls
LuaThread	optthread(LuaThread defval) Check that optional argument is a thread and return as LuaThread
Varargs	resume(Varargs args) Start or resume this thread
static LuaValue	setErrorFunc(LuaValue errfunc) Replace the error function of the currently running thread.
void	setfenv(LuaValue env) Set the environment on an object.
static void	setGlobals(LuaValue globals) Set the globals of the current thread.
int	type() Get the enumeration value for the type of this value.
java.lang.String	typename() Get the String name of the type of this value.
static Varargs	yield(Varargs args) Yield the current thread with arguments

Methods inherited from class org.luaj.vm2.LuaValue

add, add, add, and, arg, arg1, argerror, argerror, aritherror, aritherror, arithmt, arithmtwith, assert_, buffer, call, call, call, call, callmt, checkboolean, checkclosure, checkdouble, checkfunction, checkint, checkinteger, checkjstring, checklong, checkmetatag, checknotnil, checknumber, checknumber, checkstring, checktable, checkuserdata, checkuserdata, checkvalidkey, compareerror, compareerror, comparemt, concat, concat, concatmt, concatTo, concatTo, concatTo, div, div, div, divInto, eq_b, eq, eqmtcall, equals, error, get, get, get, getn, gettable, gt_b, gt_b, gt_b, gt, gt, gt, gteq_b, gteq_b, gteq_b, gteq, gteq, gteq, illegal, inext, invoke, invoke, invoke, invoke, invoke, invoke, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, isboolean, isclosure, isfunction, isint, isinttype, islong, isnil, isnumber, isstring, istable, isuserdata, isuserdata, isweaknil, len, lenerror, length, listOf, listOf, load, lt_b, lt_b, lt_b, lt, lt, lt, lteq_b, lteq_b, lteq_b, lteq, lteq, lteq, metatag, method, method, method, method, method, method, mod, mod, mod, modFrom, mul, mul, mul, narg, neg, neq_b, neq, next, not, onInvoke, optboolean, optclosure, optdouble, optfunction, optint, optinteger, optjstring, optlong, optnumber, optstring, opttable, optuserdata, optuserdata, optvalue, or, pow, pow, pow, powWith, powWith, presize, raweq, raweq, raweq, raweq, raweq, rawget, rawget, rawget, rawset, rawset, rawset, rawset, rawset, rawset, rawset, rawsetlist, set, set, set, set, set, set, set, setmetatable, settable, strcmp, strcmp, strongkey, strongvalue, strvalue, sub, sub, sub, subFrom, subFrom, tableOf, tableOf, tableOf, tableOf, tableOf, tableOf, tailcallOf, testfor_b, toboolean, tobyte, tochar, todouble, tofloat, toint, tojstring, tolong, tonumber, toshort, tostring, toString, touserdata, touserdata, typerror, unimplemented, userdataOf, userdataOf, valueOf, valueOf, valueOf, valueOf, valueOf, valueOf, varargsOf, varargsOf, varargsOf, varargsOf, varargsOf, varargsOf

Methods inherited from class org.luaj.vm2.Varargs

argcheck, checkboolean, checkclosure, checkdouble, checkfunction, checkint, checkinteger, checkjstring, checklong, checknotnil, checknumber, checkstring, checktable, checkthread, checkuserdata, checkuserdata, checkvalue, eval, isfunction, isnil, isnoneornil, isnumber, isstring, istable, isTailcall, isthread, isuserdata, isvalue, optboolean, optclosure, optdouble, optfunction, optint, optinteger, optjstring, optlong, optnumber, optstring, opttable, optthread, optuserdata, optuserdata, optvalue, subargs, toboolean, tobyte, tochar, todouble, tofloat, toint, tojstring, tolong, toshort, touserdata, touserdata, type

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

s_metatable

public static LuaValue s_metatable

coroutine_count

public static int coroutine_count

err

public LuaValue err

Field to hold state of error condition during debug hook function calls.

MAX_CALLSTACK

public static final int MAX_CALLSTACK

See Also:

Constant Field Values

GC_INTERVAL

public static int GC_INTERVAL

Interval to check for LuaThread dereferencing.

debugState

public java.lang.Object debugState

Thread-local used by DebugLib to store debugging state.

Constructor Detail

LuaThread

public LuaThread(LuaValue func,
                 LuaValue env)

Create a LuaThread around a function and environment

Parameters:

func - The function to execute

env - The environment to apply to the thread

Method Detail

type

public int type()

Description copied from class: LuaValue

Get the enumeration value for the type of this value.

Specified by:

type in class LuaValue

Returns:

value for this type, one of TNIL, TBOOLEAN, TNUMBER, TSTRING, TTABLE, TFUNCTION, TUSERDATA, TTHREAD

See Also:

LuaValue.typename()

typename

public java.lang.String typename()

Description copied from class: LuaValue

Get the String name of the type of this value.

Specified by:

typename in class LuaValue

Returns:

name from type name list LuaValue.TYPE_NAMES corresponding to the type of this value: "nil", "boolean", "number", "string", "table", "function", "userdata", "thread"

See Also:

LuaValue.type()

isthread

public boolean isthread()

Description copied from class: LuaValue

Check if this is a thread

Overrides:

isthread in class LuaValue

Returns:

true if this is a thread, otherwise false

See Also:

LuaValue.checkthread(), LuaValue.optthread(LuaThread), LuaValue.TTHREAD

optthread

public LuaThread optthread(LuaThread defval)

Description copied from class: LuaValue

Check that optional argument is a thread and return as LuaThread

Overrides:

optthread in class LuaValue

Parameters:

defval - LuaThread to return if this is nil or none

Returns:

this cast to LuaTable if a thread, defval if nil or none, throws LuaError if some other type

See Also:

LuaValue.checkthread(), LuaValue.isthread(), LuaValue.TTHREAD

checkthread

public LuaThread checkthread()

Description copied from class: LuaValue

Check that this is a LuaThread, or throw LuaError if it is not

Overrides:

checkthread in class LuaValue

Returns:

this if it is a LuaThread

See Also:

LuaValue.isthread(), LuaValue.optthread(LuaThread), LuaValue.TTHREAD

getmetatable

public LuaValue getmetatable()

Description copied from class: LuaValue

Get the metatable for this LuaValue

For LuaTable and LuaUserdata instances, the metatable returned is this instance metatable. For all other types, the class metatable value will be returned.

Overrides:

getmetatable in class LuaValue

Returns:

metatable, or null if it there is none

See Also:

LuaBoolean.s_metatable, LuaNumber.s_metatable, LuaNil.s_metatable, LuaFunction.s_metatable, s_metatable

getfenv

public LuaValue getfenv()

Description copied from class: LuaValue

Get the environemnt for an instance.

Overrides:

getfenv in class LuaValue

Returns:

LuaValue currently set as the instances environent.

setfenv

public void setfenv(LuaValue env)

Description copied from class: LuaValue

Set the environment on an object.

Typically the environment is created once per application via a platform helper method such as JsePlatform.standardGlobals() However, any object can serve as an environment if it contains suitable metatag values to implement LuaValue.get(LuaValue) to provide the environment values.

Overrides:

setfenv in class LuaValue

Parameters:

env - LuaValue (typically a LuaTable) containing the environment.

See Also:

JmePlatform, JsePlatform

getStatus

public java.lang.String getStatus()

getRunning

public static LuaThread getRunning()

Get the currently running thread.

Returns:

LuaThread that is currenly running

isMainThread

public static boolean isMainThread(LuaThread r)

Test if this is the main thread

Returns:

true if this is the main thread

setGlobals

public static void setGlobals(LuaValue globals)

Set the globals of the current thread.

This must be done once before any other code executes.

Parameters:

globals - The global variables for the main ghread.

getGlobals

public static LuaValue getGlobals()

Get the current thread's environment

Returns:

LuaValue containing the global variables of the current thread.

onCall

public static final LuaThread.CallStack onCall(LuaFunction function)

Callback used at the beginning of a call to prepare for possible getfenv/setfenv calls

Parameters:

function - Function being called

Returns:

CallStack which is used to signal the return or a tail-call recursion

See Also:

DebugLib

getCallstackFunction

public static final LuaFunction getCallstackFunction(int level)

Get the function called as a specific location on the stack.

Parameters:

level - 1 for the function calling this one, 2 for the next one.

Returns:

LuaFunction on the call stack, or null if outside of range of active stack

setErrorFunc

public static LuaValue setErrorFunc(LuaValue errfunc)

Replace the error function of the currently running thread.

Parameters:

errfunc - the new error function to use.

Returns:

the previous error function.

yield

public static Varargs yield(Varargs args)

Yield the current thread with arguments

Parameters:

args - The arguments to send as return values to resume(Varargs)

Returns:

Varargs provided as arguments to resume(Varargs)

resume

public Varargs resume(Varargs args)

Start or resume this thread

Parameters:

args - The arguments to send as return values to yield(Varargs)

Returns:

Varargs provided as arguments to yield(Varargs)