This is a library that implements POSIX threads in lua. It needs the lua executable and library to be modified in order to let multiple lua threads sharing lua objects.
Evrything in this tarball use the same licence as Lua 5.1.
Some lua packages are also included in this package in the folder luamodules. The packages class and exception are used by the others packages. The package cpackage is used by thread.c.in.lua to generate the thread.c file. The thread.c file is also provided so you won't need to use thread.c.in.lua. The last package, tests is used by the file test.lua (invoked by make test) in order to perform tests on the library.
Normally, you just have to look in the Makefile and eventually modify a little Makefile.config. Then type make on the command line. It will download lua 5.1 package, patch it, compile it, and compile the thread library.
If you do not have Internet connextion or if you don't want to download files, you can simpely put the lua 5.1 tarball on the top of the unpacked folder. it must have tyhe name lua-5.1.tar.gz. You can also tweak the Makefile.config file.
This is a first release ... so it may contains bugs. I tried to avoid them but is not that easy. That's why I created some testcases (not enough yet).
Actually I have an error, a data corruption in libc, an assertion failed in libpthread or simpely a segfault. It happens approximatively evry 1000 times.
Maybe as a result, sometimes, the main mutex used to resume a thread is unlocked. So sometimes the thread is resumed without any parameters. When it happens, the thread library can raise an error or at your choice (modify file config.h) lock the mutex again and wait a real resume :).
thread.create creates a new POSIX thread and creates also a userdata that contains the structure lusertype_thread_t defined in thread.h.
The thread works with an input stack and an output stack. The input stack contains the arguments passed to the thread by the function resume. The output stack contains the returned values of the thread given either by the final return of the function, the function yield or the function send_result.
Before using these stack, make shure you locked them by using the macro lock_thread_stack(th) and unlock them at the end with the macro unlock_thread_stack(th). th refers to a pointer to a structure of type lusertype_thread_t.
These stack are in fact used as FIFO. the first parameters are on the top. To put parameters, in fact, we move the top parameters to a tempoary stack, we push the values we want to be pushed and we move back all the others parameters.
You may notice that functions used to get and put on these stacks takes lists of parameters and returns lists. On the stack, first all the parameters given are pushed, then the number of arguments is pushed as a lua integer. To get a list from the stack, you just have to test if the stack isn't empty, then pop the first value which must be an integer that represents the total number of values that follow. Then pop the others parameters according to the integer.
The empty list is then represented in the stack by the integer 0.
When the thread is created, the thread is represented by an infinite loop. First, this loop wait the unlock of the mutex thread->mutex, done by the resume function. Then it pops parameters from the input stack, call lua_resume. it's there that the lua code is executed. After the death of the lua function, or after the yield, the lua_resume function returns. Then the result values are put in the output stack. After that, if the input stack is empty, the thread keep the lock on thread->mutex, set its state to suspended and loop. If not, the mutex is unlocked to continue over another iteration.
Since I had some problems with resume, that is the resume function locked the mutex thread->mutex just after the thread loop had locked it, and just before the thread state is put to running. This may lead to the resume function blocking forever. That's why I created another mutex, thread->resumeLock to protect that.
that's all isn't it ? Please excuse my english, It's not my natural language.