Add some light docs for mutexed access

1 files changed, 24 insertions, 0 deletions

diff --git a/docs/mutexed.md b/docs/mutexed.md
new file mode 100644
index 00000000..eebf9015
--- /dev/null
+++ b/docs/mutexed.md
@@ -0,0 +1,24 @@
+# Mutexed Data
+
+To serve the general case of synchronizing access to shared datastructures,
+Tomo uses the `mutexed` keyword, which returns a function which can be used
+to ensure that all access to a datastructure is guarded by a mutex:
+
+```tomo
+with_nums := mutexed [10, 20, 30]
+
+thread := Thread.new(func():
+    with_nums(func(nums:&[Int]):
+        nums:insert(30)
+    )
+)
+
+with_nums(func(nums:&[Int]):
+    nums:insert(40)
+)
+    
+thread:join()
+```
+
+Without having a mutex guard, the code above could run into concurrency issues
+leading to data corruption.