Document how to use threaded_cached_property and it's place in history

diff --git a/HISTORY.rst b/HISTORY.rst
index 54efc9a001533f1d84193f96622d8cb28236bed4..18d5858b37b1d031e93db612679a7ffe8ce9a28f 100644 (file)
--- a/HISTORY.rst
+++ b/HISTORY.rst
@@ -3,9 +3,10 @@
 History
 -------
 
-0.1.4 (2014-05-18)
+0.1.5 (2014-05-20)
 ++++++++++++++++++
 
+* Added threading support with new `threaded_cached_property` decorator
 * Documented cache invalidation
 * Updated credits
 * Sourced the bottle implementation

diff --git a/README.rst b/README.rst
index a447a7cb426df263fb86333912bc7df065402201..78c66915492025860ab161d9dc8f5fa50ae62edf 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -104,10 +104,51 @@ Results of cached functions can be invalidated by outside forces. Let's demonstr
     >>> m.boardwalk
     600
 
-Warning
--------
+Working with Threads
+---------------------
+
+What if a whole bunch of people want to stay at Boardwalk all at once? This means using threads, which unfortunately causes problems with the standard `cached_property`. In this case, switch to using the `threaded_cached_property`:
+
+.. code-block:: python
+
+    import threading
+
+    from cached_property import cached_property
+
+    class Monopoly(object):
+
+        def __init__(self):
+            self.boardwalk_price = 500
+            self.lock = threading.Lock()
+
+        @threaded_cached_property
+        def boardwalk(self):
+            """threaded_cached_property is really nice for when no one waits
+                for other people to finish their turn and rudely start rolling
+                dice and moving their pieces."""
+
+            sleep(1)
+            # Need to guard this since += isn't atomic.
+            with self.lock:
+                self.boardwalk_price += 50
+            return self.boardwalk_price
+
+.. code-block:: python
+
+    >>> from threading import Thread
+    >>> from monopoly import Monopoly
+    >>> monopoly = Monopoly()
+    >>> threads = []
+    >>> for x in range(10):
+    >>>     thread = Thread(target=lambda: monopoly.boardwalk)
+    >>>     thread.start()
+    >>>     threads.append(thread)
+
+    >>> for thread in threads:
+    >>>     thread.join()
+
+    >>> self.assertEqual(m.boardwalk, 550)
 
-This library currently doesn't work with threads. Please see https://github.com/pydanny/cached-property/issues/6.
 
 Credits
 --------