From: seantywork <seantywork@gmail.com>
Date: Wed, 24 Sep 2025 09:39:02 +0000 (+0000)
Subject: working krcu-cmap readme
X-Git-Url: https://git.feebdaed.xyz/?a=commitdiff_plain;h=cd6c1603f46441fa1b6afa984f29adcb700e6f77;p=linuxyz.git

working krcu-cmap readme
---

diff --git a/krcu-cmap/README.md b/krcu-cmap/README.md
index 22b3f5d..a61ec23 100644
--- 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