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.
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)
creates a new threaded lua state object.
returns true if the thread is still running
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:
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.
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
returns a value for the key from the global environment table of the exchangestate
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.
sets a value for the key in the global environment table of the exchangestate
unlocks the exchange state