Add some light docs for mutexed access

3 files changed, 26 insertions, 1 deletions

diff --git a/docs/README.md b/docs/README.md
index c1e6cf88..e5253963 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -27,6 +27,7 @@ Information about Tomo's built-in types can be found here:
 - [Integer Ranges](ranges.md)
 - [Integers](integers.md)
 - [Languages](langs.md)
+- [Mutexed Data](mutexed.md)
 - [Paths](paths.md)
 - [Random Number Generators](rng.md)
 - [Sets](sets.md)
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.
diff --git a/docs/threads.md b/docs/threads.md
index 44f5967e..4d91e8bd 100644
--- a/docs/threads.md
+++ b/docs/threads.md
@@ -2,7 +2,7 @@
 
 Tomo supports POSIX threads (pthreads) through the `Thread` type. The
 recommended practice is to have each thread interact with other threads only
-through mutex-guarded datastructures.
+through [mutex-guarded datastructures](mutexed.md).
 
 ## Thread Methods