working krcu-cmap readme

diff --git a/krcu-cmap/README.md b/krcu-cmap/README.md
index 22b3f5d505a6352b90df9771e59af74ade5bf00e..a61ec232353e96c8a809670a51ac7da4691499e5 100644 (file)
--- a/krcu-cmap/README.md
+++ b/krcu-cmap/README.md
@@ -1,5 +1,138 @@
 # krcu-cmap
 
 - source: [linuxyz/krcu-cmap](https://github.com/seantywork/linuxyz/tree/main/krcu-cmap)
-- date: 2509-
+- date: 2509-24
 
+In user space on Linux, we can utilize pthread_rwlock to design a read-heavy data structure.
+
+A similar thing in the Linux kernel space is called `rcu`, a shorthand for "read, copy, update".
+
+Full documentation on it is [here](https://www.kernel.org/doc/html/next/RCU/whatisRCU.html)
+
+However, with pthread_rwlock in mind, it could be a little bit puzzling (at least it was for me) \
+to grasp the proper use and order of apis unlike in the case of \
+pthread_rwlock where you simply call *_rdlock on read and *_wrlock \
+on update
+
+Reading the docs wasn't enough for me.
+
+So I did the thing when I'm confused about the concept of multi-threading \
+and syncing mechanism: \
+**Building a concurrent map example!**
+
+Here, this is the outlay of this example.
+
+
+```shell
+# a regular old concurrent map...
+concurrent_map
+|     bucket_count
+|     bucket_0-------
+|     |     spin_lock      
+|     |     node_0----node_1----node_n
+|     bucket_1-------
+|     |     spin_lock
+|     |     node_0----node_1----node_n
+|     bucket_2-------
+|     |     spin_lock
+|     |     node_0----node_1----node_n
+|     bucket_n-------
+|     |     spin_lock
+|     |     node_0----node_1----node_n
+|     ----------------
+|     |
+---------------
+```
+However, in this case, our `node` data structure here \
+contains the magic element
+
+```c
+struct node {
+    int key;
+    int value;
+       struct list_head _node; 
+       struct rcu_head _rcu; // <----- hello!
+};
+```
+
+
+
+```shell
+
+[Sep24 09:06] r: init
+[  +0.000007] r: wait...
+[  +0.000087] w: init
+[  +0.000038] w: updating cmap
+[  +0.000003] w: update cmap: 0
+[  +0.000001] w: update cmap: 5
+[  +0.000001] w: update cmap: 2
+[  +0.000001] w: update cmap: 9
+[  +0.000001] w: update cmap: 5
+[  +0.000001] w: update cmap: 2
+[  +0.000000] w: update cmap: 8
+[  +0.000001] w: update cmap: 3
+[  +0.000001] w: update cmap: 1
+[  +0.000000] w: update cmap: 7
+[  +0.000001] w: ready
+[  +0.103514] r: run
+[  +0.000017] r: continue: sum: 45
+[  +0.100011] r: continue: sum: 45
+[  +0.100018] r: continue: sum: 45
+[  +0.100057] r: continue: sum: 45
+[  +0.100018] r: continue: sum: 45
+[  +0.100015] r: continue: sum: 45
+[  +0.100015] r: continue: sum: 45
+[  +0.100016] r: continue: sum: 45
+[  +0.100020] r: continue: sum: 45
+[  +0.100021] r: continue: sum: 45
+[  +0.100025] r: continue: sum: 45
+[  +0.100070] r: continue: sum: 45
+[  +0.100025] r: continue: sum: 45
+[  +0.100032] r: continue: sum: 45
+[  +0.100033] r: continue: sum: 45
+[  +0.100060] r: continue: sum: 45
+[  +0.100054] r: continue: sum: 45
+[  +0.100030] r: continue: sum: 45
+[  +0.100021] r: continue: sum: 45
+[  +0.100018] r: continue: sum: 90
+[  +0.100021] r: continue: sum: 90
+[  +0.100018] r: continue: sum: 90
+[  +0.100021] r: continue: sum: 90
+[  +0.100019] r: continue: sum: 90
+[  +0.100017] r: continue: sum: 90
+[  +0.100016] r: continue: sum: 90
+[  +0.100025] r: continue: sum: 90
+[  +0.100017] r: continue: sum: 90
+[  +0.100019] r: continue: sum: 90
+[  +0.100018] r: continue: sum: 135
+[  +0.100022] r: continue: sum: 135
+[  +0.100015] r: continue: sum: 135
+[  +0.100015] r: continue: sum: 135
+[  +0.100036] r: continue: sum: 135
+[  +0.100053] r: continue: sum: 135
+[  +0.100020] r: continue: sum: 135
+[  +0.100028] r: continue: sum: 135
+[  +0.100041] r: continue: sum: 135
+[  +0.100021] r: continue: sum: 135
+[  +0.096219] w: removing from cmap
+[  +0.000004] w: remove cmap: 0
+[  +0.000002] w: remove cmap: 5
+[  +0.000001] w: remove cmap: 2
+[  +0.000001] w: remove cmap: 9
+[  +0.000000] w: remove cmap: 5
+[  +0.000001] w: remove cmap: 2
+[  +0.000001] w: remove cmap: 8
+[  +0.000000] w: remove cmap: 3
+[  +0.000001] w: remove cmap: 1
+[  +0.000000] w: remove cmap: 7
+[  +0.000039] w: done
+[  +0.003755] r: done: sum == 0
+
+
+```
+
+```shell
+[ +17.767446] rcucmap: deleting cmap
+[  +0.000007] rcucmap: exit
+
+```
\ No newline at end of file