more doc

1 files changed, 70 insertions, 4 deletions

diff --git a/README.md b/README.md
index 9cd76c3..6720885 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ The magic of the *threads* package lies in the seven following points:
 *   Threads are created on demand (usually once in the program).
 *   Jobs are submitted to the threading system in the form of a callback function. The job will be executed on the first free thread.
 *   An ending callback will be executed in the main thread, when a job finishes.
-*   Job callback are fully serialized (including upvalues!), which allows a transparent copy of the data to any thread.
+*   Job callback are fully serialized (including upvalues!), which allows transparent copy of data to any thread.
 *   Values returned by a job callback will be passed to the ending callback (serialized transparently).
 *   As ending callbacks stay on the main thread, they can directly "play" with upvalues of the main thread.
 *   Synchronization between threads is easy.
@@ -30,8 +30,8 @@ very portable, I believe this dependency should not be a problem. If there
 are enough requests, I might propose alternatives to SDL2 threads.
 
 Torch is used for full serialization. One could easily get inspired from
-torch serialization system to adapt the package to its own needs. Soon
-(with torch9), torch should be straighforward to install, so this
+Torch serialization system to adapt the package to its own needs. Soon
+(with torch9), Torch should be straighforward to install, so this
 dependency should be minor too.
 
 At this time, if you have torch7 installed:
@@ -42,5 +42,71 @@ torch-rocks install https://raw.github.com/andresy/threads-ffi/master/rocks/thre
 
 If you do not have torch7 installed, well... wait for torch9, or try to install torch7.
 
-# Usage #
+# Example Usage #
 
+An example is better than convoluted explanations.
+
+```lua
+local Threads = require 'threads'
+local sdl = require 'sdl2'
+
+local nthread = 4
+local njob = 10
+local msg = "hello from a satellite thread"
+
+-- init SDL (follow your needs)
+sdl.init(0)
+
+-- init the thread system
+-- one lua state is created for each thread
+
+-- the function takes several callbacks as input, which will be executed
+-- sequentially on each newly created lua state
+local threads = Threads(nthread,
+                        -- typically the first callback requires module
+                        -- necessary to serialize the second callback
+                        function()
+                           gsdl = require 'sdl2'
+                        end,
+
+                        -- other callbacks prepare stuff you need
+                        -- to run your program
+                        function()
+                           print('starting a new thread/state')
+                           gmsg = msg -- we copy here an upvalue of the main thread
+                        end)
+
+-- now add jobs
+local jobdone = 0
+for i=1,njob do
+   threads:addjob(
+                  -- the job callback
+                  function()
+                     local id = tonumber(gsdl.threadID())
+                     print(string.format('%s -- thread ID is %x', gmsg, id))
+
+                     -- return a value to the end callback
+                     return id
+                  end,
+
+                  -- the end callback
+                  -- ran in the main thread
+                  function(id)
+                     print(string.format("task %d finished (ran on thread ID %x)", i, id))
+
+                     -- note that we can manipulate upvalues of the main thread
+                     -- as this callback is ran in the main thread!
+                     jobdone = jobdone + 1 
+                  end)
+end
+
+-- wait for all jobs to finish
+threads:synchronize()
+
+print(string.format('%d jobs done', jobdone))
+
+-- of course, one can run more jobs if necessary!
+
+-- terminate threads
+threads:terminate()
+```