Class: tls

LuxModule: luxinialuacore

TLS stands for 'threaded lua state' and is part of the luacore inside luxinia, which is the reason why it is not documented in the common way.

Luxinia is running in a single thread, and only the main thread has the functionality to access the core library. It is not possible for a thread to execute any function of the core directly.

If a new threading state is created, luxinia creates two new states, where one is running as a complete new thread, including all the default libraries that are included in lua, however without any additional functionality.

A threaded state can reload DLLs at any point and thus can access most other functions that are provided by the external lua libs.

This is for example the filesystem, the xml parser, and all networking functionality and so on.

One of the created luastates acts as a communicator between the main thread and the slave thread, which is running in the second luastate. The communicator or exchange state is always used exclusivly, which means that if the main thread or the slave thread is accessing it, any other access is being blocked. The exchange state is loaded without library functions and thus cannot execute much code, however, it is possible to execute code within that state, which can is injected as a string and can come from one of both threads. The results of the execution is then returned to the executing thread.

The current implementation is limited to the exchange of numbers and strings at the moment.

It is important that the mainthread keeps a reference to the thread, otherwise the thread is stopped when the garbage collector destroys the thread.

The package paths are automaticly copied from the main thread.

Example:

This example creates a new state and let it execute a loop, sleeping half a second and printing out the clock's time, until it is stopped by setting the requested variable value to nil:

 state = tls.new()
 state:xset("run",1)
 state:start(
 "	while xget 'run' do "..
 "		sleep(.5) print(os.clock()) "..
 "	end "..
 "	print 'finished'")
 TimerTask.new(function () state:xset("run",nil) end,2000)

Methods:

Method overview:


new ()
returns: (tls)

creates a new threaded lua state object.

running (tls)
returns: (boolean isrunning)

returns true if the thread is still running

start (tls,string code)
returns: ([boolean success],[string errormsg])

Starts the thread, running the given code. Once the execution is finished, the thread will terminate normaly. It can then be restarted, the states are not modified in that case.

If an error occures, the function returns nil plus the error message.

It is not possible to start the tls if it is still running.

The started thread has a few global functions available, that allows it to control its execution:

  1. (return_values) xdostring (string code) - executes a piece of code within the exchange state
  2. ([nil,errormsg]) xset (key,value) - sets a key/value pair in the exchange state
  3. (value / [nil,type]) xget (key) - returns a value for the given key in the exchange state
  4. () xlock () - locks the mutex of the exchange thread, pausing any access on the exchange state
  5. () xunlock () - unlocks the mutex of the exchange thread
  6. () sleep (seconds) - sleeps for the given amount of time
  7. () killme () - destroys the thread, effectivly kills the execution instantly

stop (tls)
returns: ()

destroys the thread, but waits until the mutex was unlocked. Don't use this function unless really required, as it might damage the luastate which can lead to a crash once it is reused.

xdostring (string code)
returns: ([true,... / nil, error])

executes a piece of code in the exchange thread, returning true in case of success and the returned values of the code or nil and the error message

xget (tls, key)
returns: (boolean value / [nil, typename])

returns a value for the key from the global environment table of the exchangestate

xlock (tls)
returns: ()

locks the exchange state until it is unlocked. The other thread cannot access the exchange thread then. Use the lock when you need to make some atomic changes to the exchange state.

xset (tls, key,value)
returns: ([nil, error])

sets a value for the key in the global environment table of the exchangestate

xunlock (tls)
returns: ()

unlocks the exchange state