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 the constructor arguments LuaThread(Globals) or LuaThread(Globals, LuaValue).

The utility classes JsePlatform and JmePlatform see to it that this Globals are initialized properly.

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. The value controlling the polling interval is thread_orphan_check_interval and may be set by the user.

There are two main ways to abandon a coroutine. The first is to call yield() from lua, or equivalently Globals.yield(Varargs), and arrange to have it never resumed possibly by values passed to yield. The second is to throw OrphanedThread, which should put the thread in a dead state. In either case all references to the thread must be dropped, and the garbage collector must run for the thread to be garbage collected.

See Also:

LuaValue, JsePlatform, JmePlatform, CoroutineLib

Nested Class Summary

static class

LuaThread.State

Field Summary

java.lang.Object	callstack Thread-local used by DebugLib to store debugging state.
static int	coroutine_count The current number of coroutines.
LuaValue	errorfunc Error message handler for this thread, if any.
Globals	globals
static int	MAX_CALLSTACK
static LuaValue	s_metatable Shared metatable for lua threads.
LuaThread.State	state
static int	STATUS_DEAD
static int	STATUS_INITIAL
static java.lang.String[]	STATUS_NAMES
static int	STATUS_NORMAL
static int	STATUS_RUNNING
static int	STATUS_SUSPENDED
static long	thread_orphan_check_interval Polling interval, in milliseconds, which each thread uses while waiting to return from a yielded state to check if the lua threads is no longer referenced and therefore should be garbage collected.

Fields inherited from class org.luaj.vm2.LuaValue

ADD, CALL, CONCAT, DIV, EMPTYSTRING, ENV, 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(Globals globals)
Private constructor for main thread only

LuaThread(Globals globals, LuaValue func)
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
LuaValue	getmetatable() Get the metatable for this LuaValue
java.lang.String	getStatus()
boolean	isMainThread()
boolean	isthread() Check if this is a thread
LuaThread	optthread(LuaThread defval) Check that optional argument is a thread and return as LuaThread
Varargs	resume(Varargs args)
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.

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, call, callmt, checkboolean, checkclosure, checkdouble, checkfunction, checkglobals, checkint, checkinteger, checkjstring, checklong, checkmetatag, checknotnil, checknumber, checknumber, checkstring, checktable, checkuserdata, checkuserdata, compareerror, compareerror, comparemt, concat, concat, concatmt, concatTo, concatTo, concatTo, div, div, div, divInto, eq_b, eq, eqmtcall, equals, error, get, get, get, gettable, gt_b, gt_b, gt_b, gt, gt, gt, gteq_b, gteq_b, gteq_b, gteq, gteq, gteq, illegal, inext, initupvalue1, invoke, invoke, invoke, invoke, invoke, invoke, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, isboolean, isclosure, isfunction, isint, isinttype, islong, isnil, isnumber, isstring, istable, isuserdata, isuserdata, isvalidkey, len, lenerror, length, listOf, listOf, load, lt_b, lt_b, lt_b, lt, lt, lt, lteq_b, lteq_b, lteq_b, lteq, lteq, lteq, metatableOf, 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, rawlen, rawset, rawset, rawset, rawset, rawset, rawset, rawset, rawsetlist, set, set, set, set, set, set, set, setmetatable, settable, strcmp, strcmp, strongvalue, strvalue, sub, sub, sub, subargs, 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, 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

Shared metatable for lua threads.

coroutine_count

public static int coroutine_count

The current number of coroutines. Should not be set.

thread_orphan_check_interval

public static long thread_orphan_check_interval

Polling interval, in milliseconds, which each thread uses while waiting to return from a yielded state to check if the lua threads is no longer referenced and therefore should be garbage collected. A short polling interval for many threads will consume server resources. Orphaned threads cannot be detected and collected unless garbage collection is run. This can be changed by Java startup code if desired.

STATUS_INITIAL

public static final int STATUS_INITIAL

See Also:

Constant Field Values

STATUS_SUSPENDED

public static final int STATUS_SUSPENDED

See Also:

Constant Field Values

STATUS_RUNNING

public static final int STATUS_RUNNING

See Also:

Constant Field Values

STATUS_NORMAL

public static final int STATUS_NORMAL

See Also:

Constant Field Values

STATUS_DEAD

public static final int STATUS_DEAD

See Also:

Constant Field Values

STATUS_NAMES

public static final java.lang.String[] STATUS_NAMES

state

public final LuaThread.State state

MAX_CALLSTACK

public static final int MAX_CALLSTACK

See Also:

Constant Field Values

callstack

public java.lang.Object callstack

Thread-local used by DebugLib to store debugging state. This is an opaque value that should not be modified by applications.

globals

public final Globals globals

errorfunc

public LuaValue errorfunc

Error message handler for this thread, if any.

Constructor Detail

LuaThread

public LuaThread(Globals globals)

Private constructor for main thread only

LuaThread

public LuaThread(Globals globals,
                 LuaValue func)

Create a LuaThread around a function and environment

Parameters:

func - The function to execute

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 LuaValue.TNIL, LuaValue.TBOOLEAN, LuaValue.TNUMBER, LuaValue.TSTRING, LuaValue.TTABLE, LuaValue.TFUNCTION, LuaValue.TUSERDATA, LuaValue.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

getStatus

public java.lang.String getStatus()

isMainThread

public boolean isMainThread()

resume

public Varargs resume(Varargs args)