Improved README.

README.md

@@ -1,7 +1,38 @@
 About
 =====
 
-A simple low-level Lua wrapper for pthreads.
+A simple Lua wrapper for pthreads.
+
+Each thread gets it's own `lua_State` and there is no shared global state.
+The parent thread can pass data to a child thread only as parameters when creating
+the child thread.  The child threads can return data back to the parent thread only
+when it return (i.e. ends).  The parent needs to call child:join() to get the return
+values from a child thread, this call will block until the child thread ends.
+
+The design goals of this module is only provide support for creating new `lua_State`
+and running them in a different thread.  This module will not provide any
+methods of thread-to-thread data passing between running threads (i.e. no locks, no shared state).
+
+Thread to Thread communication methods
+======================================
+
+* The recommend method of passing data between threads is to use [ZeroMQ](http://github.com/Neopallium/lua-zmq).
+
+* Another method is to use sockets library like [LuaSocket](http://w3.impa.br/~diego/software/luasocket) or [Nixio](http://neopallium.github.com/nixio/).
+
+Installation
+============
+
+With LuaRocks 2.0.4.1:
+	$ sudo luarocks install https://github.com/Neopallium/lua-llthreads/raw/master/rockspecs/lua-llthreads-scm-0.rockspec
+
+With CMake:
+	$ git clone git://github.com/Neopallium/lua-llthreads.git
+	$ cd lua-llthreads ; mkdir build ; cd build
+	$ cmake ..
+	$ make
+	$ sudo make install
+
 
 Example usage
 =============

tests/test_llthreads.lua

@@ -28,7 +28,7 @@ local function detached_thread(...)
 end
 
 local function print_thread(...)
-	local thread = llthreads.new([[ return print("print_thread:", ...) ]], ...)
+	local thread = llthreads.new([[ print("print_thread:", ...); ]], ...)
 	-- start joinable thread
 	assert(thread:start())
 	return thread
@@ -43,11 +43,15 @@ end
 
 local thread1 = detached_thread("number:", 1234, "nil:", nil, "bool:", true)
 
+os.execute("sleep 1");
+
 local thread2 = print_thread("number:", 1234, "nil:", nil, "bool:", true)
-print(thread2:join())
+print("thread2:join: results # = ", select('#', thread2:join()))
+
+os.execute("sleep 1");
 
 local thread3 = pass_through_thread("number:", 1234, "nil:", nil, "bool:", true)
-print("resuls:", thread3:join())
+print("thread3:join:", thread3:join())
 
-os.execute("sleep 2");
+os.execute("sleep 1");