# LuaThread (Luaj API)
Date: 2015-04-29

## 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)

Copyright © 2007-2015 Luaj.org. All Rights Reserved.