[NSE] Patch to add worker threads to NSE for scripts to use. Right

now a script is limited in parallelism to working on one socket at any
time. A script can now create a worker thread that will be capable of
doing work on sockets in parallel with the parent script. See [1] for
more information.

This patch also comes with condition variables that are similar to
POSIX condition variables. They are used in the same fashion as
NSE's mutexes (nmap.mutex).

[1] http://seclists.org/nmap-dev/2009/q4/294

nselib/nmap.luadoc

@@ -172,6 +172,54 @@ function get_interface_link(interface_name)
 -- end
 function mutex(object)
 
+--- Create a condition variable for an object.
+--
+-- This function returns a function that works as a Condition Variable for the
+-- given object parameter. The object can be any Lua data type except
+-- <code>nil</code>, Booleans, and Numbers. The Condition Variable (returned
+-- function) allows you wait, signal, and broadcast on the condition variable.
+-- The Condition Variable function takes only one argument, which must be one of
+-- * <code>"wait"</code>: Wait on the condition variable until another thread wakes us.
+-- * <code>"signal"</code>: Wake up a single thread from the waiting set of threads for this condition variable.
+-- * <code>"broadcast"</code>: Wake up all threads in the waiting set of threads for this condition variable.
+--
+-- NSE maintains a weak reference to the Condition Variable so other calls to
+-- nmap.condvar with the same object will return the same function (Condition
+-- Variable); however, if you discard your reference to the Condition
+-- Variable then it may be collected; and, Subsequent calls to nmap.condvar with
+-- the object will return a different Condition Variable function!
+--
+-- In NSE, Condition Variables are typically used to coordinate with threads
+-- created using the stdnse.new_thread facility. The worker threads must
+-- wait until work is available that the master thread (the actual running
+-- script) will provide. Once work is created, the master thread will awaken
+-- one or more workers so that the work can be done.
+--
+-- It is important to check the predicate (the test to see if your worker
+-- thread should "wait" or not) BEFORE and AFTER the call to wait. You are
+-- not guaranteed spurious wakeups will not occur (that is, there is no
+-- guarantee your thread will not be awakened when no thread called
+-- <code>"signal"</code> or <code>"broadcast"</code> on the condition variable).
+-- One important check for your worker threads, before and after waiting,
+-- should be to check that the master <b>script</b> thread is still alive.
+-- (To check that the master script thread is alive, obtain the "base" thread
+-- using stdnse.base and use coroutine.status). You do not want your worker
+-- threads to continue when the script has ended for reasons unknown to your
+-- worker thread.  <b>You are guaranteed that all threads waiting on a condition
+-- variable will be awakened if any thread that has accessed the condition
+-- variable via <code>nmap.condvar</code> ends for any reason.</b> This is
+-- essential to prevent deadlock with threads waiting for another thread to awaken
+-- them that has ended unexpectedly.
+-- @see stdnse.new_thread
+-- @see stdnse.base
+-- @param object Object to create a condition variable for.
+-- @return ConditionVariable Condition variable function.
+-- @usage
+-- local myobject = {}
+-- local cv = nmap.condvar(myobject)
+-- cv "wait" -- waits until another thread calls cv "signal"
+function condvar(object)
+
 --- Creates a new exception handler.
 --
 -- This function returns an exception handler function. The exception handler is