From 2697e929d05fc16ce6322c9eb0c17ed5cb2ce760 Mon Sep 17 00:00:00 2001
From: Peter Hinch <peter@hinch.me.uk>
Date: Mon, 30 Nov 2015 07:14:40 +0000
Subject: [PATCH] mutex readme updated

---
 mutex/README.md | 47 ++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 44 insertions(+), 3 deletions(-)

diff --git a/mutex/README.md b/mutex/README.md
index 00d9fe1..2435624 100644
--- a/mutex/README.md
+++ b/mutex/README.md
@@ -1,7 +1,48 @@
-# mutex.py mutex_test.py
+# A very simple mutex class.
 
-Implementation of a very simple mutex class
+Files mutex.py mutex_test.py
 
+A mutex is an object enabling threads of execution to protect critical sections of code from reentrancy
+or to temporarily protect critical data sets from being updated by other threads. The term "mutex"
+derives from the notion of mutual exclusion. A mutex usually provides three methods:
 
+lock() (POSIX pthread_mutex_lock): wait until the mutex is free, then lock it  
+unlock() (POSIX pthread_mutex_unlock): Immediate return. unlock the mutex.  
+test() (POSIX pthread_mutex_trylock): Immediate return. test if it is locked.  
 
-[reference](http://www.geeksforgeeks.org/mutex-vs-semaphore/)
+In this implementation lock and unlock is controlled by a context manager.
+
+In the context of MicroPython a mutex provides a mechanism where an interrupt service routine (ISR) can
+test whether the main loop was using critical variables at the time the interrupt occurred, and if so
+avoid modifying those variables. Typical use is as follows:
+
+```python
+import pyb, mutex
+mutex = mutex.Mutex()
+data_ready = False
+
+def callback(): # Timer or interrupt callback
+    if mutex.test():
+        data_ready = True
+        # Update critical variables
+    else:
+        # defer any update
+# Associate callback with device (pin or timer)
+
+while True:
+    # code
+    if data_ready:
+        with mutex:
+            data_ready = False
+            # Access critical variables
+    # more code
+```
+Note that the ``with`` statement will execute immediately because no other process runs a ``with`` block
+on the same mutex instance.
+
+[Linux man page](http://linux.die.net/man/3/pthread_mutex_lock)
+
+References describing mutex and semaphore objects
+[geeksforgeeks](http://www.geeksforgeeks.org/mutex-vs-semaphore/)
+[stackoverflow](http://stackoverflow.com/questions/62814/difference-between-binary-semaphore-and-mutex)
+[differencebetween](http://www.differencebetween.net/language/difference-between-mutex-and-semaphore/)