update readme

Author: Jack Tang

README.md

@@ -4,28 +4,39 @@ Simplify Nim Inter-Thread Communication
 
 ## Overview 
 
-- Each thread has a fixed unique `name`.
-- Each thread is associated with one [`Channel`](https://nim-lang.org/docs/channels.html#Channel). 
-- Each thread processes its channel with `threadproxy.poll`.
-- JSON is the data exchange format.
+ThreadProxy help you manage threads and channels. You don't have to declare them explicitly. 
+ThreadProxy also provide a little thread-name-system and do name resolution for you. 
+
+Some key-points:
+
+- Each thread has a unique `name` assigned at creation.
+- Each thread start processesing its messages with `poll()`.
+- JSON is the *ONLY* data exchange format.
 - Threads can talk with each other with `name` reference. 
-- Threads can talk with each other in one-way with `send()`.
-- Threads can talk with each other in two-way with `ask()`.
+- Threads can talk with each other in one-way with `send(...): Future[void]`.
+- Threads can talk with each other in two-way with `ask(...): Future[JsonNode]`.
 - The order of creation of threads does not matter as long as the target thread is running at the time of calling `send` or `ask`.
 
 ## Usage 
 
 The typical pattern should look like the following.
 
 ```nim
-import threadproxy
+import threadproxy                                  # ---- 1
 
-proc fooMain(proxy: ThreadProxy) {.thread.} =
+proc fooMain(proxy: ThreadProxy) {.thread.} =       # ---- 2 
   # setup and then poll threadProxy
-  proxy.onData "action1": result = action1(data)
-  proxy.onData "action2": result = action2(data)
+  proxy.on "action1", proc(data: JsonNode): Future[JsonNode] {.gcsafe.} =   # ---- 3 
+    result = action1(data)
+  
+  proxy.onData "action2":                           # ---- 4
+    result = action2(data)
+
+  proxy.onDefault proc(action: string, data: JsonNode): Future[JsonNode] {.gcsafe.} =  # ---- 5
+    reuslt = ...
+
   # ... 
-  asyncCheck proxy.poll()
+  asyncCheck proxy.poll()                           # ---- 6
 
   # ... 
   # do something here
@@ -35,14 +46,13 @@ proc fooMain(proxy: ThreadProxy) {.thread.} =
 
 proc main() =
   # create, setup and then poll mainThreadProxy
-  let proxy = newMainThreadProxy("main")
-  proxy.onData "action1": result = action1(data)
-  proxy.onData "action2": result = action2(data)
+  let proxy = newMainThreadProxy("main")            # ---- 7
+  proxy.onData "action1": result = action1(data)    # ---- 8
   # ...
-  asyncCheck proxy.poll()
+  asyncCheck proxy.poll()                           # ---- 9
 
   # create threads
-  proxy.createThread("foo1", fooMain)
+  proxy.createThread("foo1", fooMain)               # ---- 10
   proxy.createThread("foo2", fooMain)
   #... 
 
@@ -56,18 +66,31 @@ when isMainModeul:
   main()
 ```
 
+1. `import threadproxy` will also `import json, asyncdispatch`. They are almost always used together.
+2. Define an entry function for threads. If you don't want to declare thread on your own, the argument must be a `ThreadProxy`. Also note that the `{.thread.}` pragma must be present.
+3. Define a handler for `action`. The handler function is responsible for both `send` and `ask` handling. A `nil` return value will be converted to `JNull`
+4. Similar to `on`, but a template version that save you from typing `proc...` everytime. The argument `data` is injected and so the name `onData`
+5. Default handler for all unregistered actions. There is also a templated version `onDefaultData` that work similarly.
+6. Start processing messages on channels asychronously . This must be called exactly once, otherwise nothing will happen.
+7. Create a `MainThreadProxy` with a name.  `MainThreadProxy` is also a `ThreadProxy` with responsibilities to handle threads and channels. 
+8. Define handlers for MainThreadProxy similar to that in fooMain.
+9. Start processing messages similar to that in fooMain.
+10. Create thread with a name and entry function.
+
 ## Examples
 
 Example 1: simple ask
 
 ```nim
-import threadproxy, asyncdispatch
+import threadproxy
 
 proc workerMain(proxy: ThreadProxy) {.thread.} =
   # register action handler
-  proxy.onData "double":
-    let x = data.getInt()
-    return %(2*x)
+  proxy.onData "sum":
+    var x = 0
+    for n in data:
+      x += n.getInt()
+    return %x
 
   # start processing channel
   waitFor proxy.poll()
@@ -80,8 +103,8 @@ proc main() =
   proxy.createThread("worker_0", workerMain)
 
   # ask worker_0 to double 10
-  let answer = waitFor proxy.ask("worker_0", "double", %10)
-  assert answer == %20
+  let answer = waitFor proxy.ask("worker_0", "sum", %[2,3,5,7])
+  assert answer == %17
 
 when isMainModule:
   main()

examples/simple_ask.nim

@@ -1,10 +1,12 @@
-import threadproxy, asyncdispatch
+import threadproxy
 
 proc workerMain(proxy: ThreadProxy) {.thread.} =
   # register action handler
-  proxy.onData "double":
-    let x = data.getInt()
-    return %(2*x)
+  proxy.onData "sum":
+    var x = 0
+    for n in data:
+      x += n.getInt()
+    return %x
 
   # start processing channel
   waitFor proxy.poll()
@@ -17,8 +19,8 @@ proc main() =
   proxy.createThread("worker_0", workerMain)
 
   # ask worker_0 to double 10
-  let answer = waitFor proxy.ask("worker_0", "double", %10)
-  assert answer == %20
+  let answer = waitFor proxy.ask("worker_0", "sum", %[2,3,5,7])
+  assert answer == %17
 
 when isMainModule:
   main()