LuaThread: Multi-(platform|threading) support for the Lua language

Reference

thread.newthread(func, arg)

Creates a new thread of execution.

Func is the function that will be executed in the new thread. Arg is a table with the arguments to be passed to func as in func(unpack(arg)).

The new execution thread lasts until func returns.

thread.newmutex()

Creates new mutex, a mutual exclusion synchronization object. A mutex can be in locked or unlocked state (initially unlocked). The thread has locked a mutex is said to own the mutex. A mutex can be owned by only one thread at any given time. If a thread attempts to lock a mutex owned by another thread, it will be blocked until the owner thread unlocks the mutex.

The function returns the newly created unlocked mutex.

Note: LuaThread mutexes are recursive in the sense that successive calls to mutex:lock() nest. If the mutex owner locks a mutex n times, it has to unlock the mutex the same n times before the mutex switches to unlocked state.

mutex:lock()

Locks a mutex. If the mutex is owned by another thread, the function blocks the caller thread until the owner unlocks the mutex.

mutex:unlock()

Unlocks the given mutex. Calling mutex:unlock() without owning the mutex is an error.

thread.newcond()

Creates and a new cond, a condition variable. Condition variables allow threads to wait for a predicate to be satisfied, and to signal to waiting threads that the predicate status has been changed.

The condition variable is used in association with a mutex that protects the predicate from race conditions. Before waiting or signaling a condition variable, the mutex associated with the predicate has to be locked.

The function returns the newly created condition variable.

cond:wait(mutex)

Waits on a condition variable.

Mutex is the mutex associated with the predicate. In order to use this function, the calling thread has to own the mutex. Before the thread is put to wait (if need be), however, the mutex is unlocked (see comments). Upon return, the thread owns the mutex again.

To wait on a condition variable, proceed as follows:

-- make sure we are the only currently accessing the predicate
predicate.mutex:lock()                   
-- while the predicate is not what we want
while unsatisfactory(predicate) do
    -- wait until someone changes the predicate
    predicate.cond:wait(predicate.mutex)
end
-- at this point, the predicate is valid AND we own it 
use(predicate)
-- unlock the mutex, so that other threads can access the predicate
predicate.mutex:unlock()

Note: LuaThread conditions are safe in the sense that even if a thread has more than one lock over a mutex, cond:wait(mutex) manages to unlock the mutex before blocking the caller thread. Upon return, the same number of locks is restored into the mutex.

cond:signal()

Releases one of the threads blocked on the condition variable. Before signaling, the caller thread should own the mutex associated to the predicate.

To signal a condition variable, proceed as follows:

-- make sure we are the only currently accessing the predicate
predicate.mutex:lock()                   
-- change the predicate
update(predicate)
-- release one of the threads blocked on cond
predicate.cond:signal()
-- unlock the mutex, so that other threads can access the predicate
predicate.mutex:unlock()

cond:broadcast()

Similar to cond:signal(), but releases all threads blocked on the condition variable.