[pypy-commit] pypy default: Expand the text on threadlocalproperty.

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r76610:cda2320ed4dc
Date: 2015-03-28 09:38 +0100
http://bitbucket.org/pypy/pypy/changeset/cda2320ed4dc/

Log:	Expand the text on threadlocalproperty.

diff --git a/pypy/doc/stm.rst b/pypy/doc/stm.rst
--- a/pypy/doc/stm.rst
+++ b/pypy/doc/stm.rst
@@ -396,18 +396,30 @@
   and ``y`` that are thread-local: reading or writing them from
   concurrently-running transactions will return independent results.
   (Any other attributes of ``Foo`` instances will be globally visible
-  from all threads, as usual.)  The optional argument to
-  ``threadlocalproperty()`` is the default value factory: in case no
-  value was assigned in the current thread yet, the factory is called
-  and its result becomes the value in that thread (like
-  ``collections.defaultdict``).  If no default value factory is
-  specified, uninitialized reads raise ``AttributeError``.  Note that
-  with ``TransactionQueue`` you get a pool of a fixed number of
-  threads, each running the transactions one after the other; such
-  thread-local properties will have the value last stored in them in
-  the same thread,, which may come from a random previous transaction.
-  This means that ``threadlocalproperty`` is useful mainly to avoid
-  conflicts from cache-like data structures.
+  from all threads, as usual.)  This is useful together with
+  ``TransactionQueue`` for these two cases:
+
+  - For attributes of long-lived objects that change during one
+    transaction, but should always be reset to some initial value
+    around transaction (for example, initialized to 0 at the start of
+    a transaction; or, if used for a list of pending things to do
+    within this transaction, it will always be empty at the end of one
+    transaction).
+
+  - For general caches across transactions.  With ``TransactionQueue``
+    you get a pool of a fixed number N of threads, each running the
+    transactions serially.  A thread-local property will have the
+    value last stored in it by the same thread, which may come from a
+    random previous transaction.  Basically, you get N copies of the
+    property's value, and each transaction accesses a random copy.  It
+    works fine for caches.
+
+  In more details, the optional argument to ``threadlocalproperty()``
+  is the default value factory: in case no value was assigned in the
+  current thread yet, the factory is called and its result becomes the
+  value in that thread (like ``collections.defaultdict``).  If no
+  default value factory is specified, uninitialized reads raise
+  ``AttributeError``.
 
 * In addition to all of the above, there are cases where write-write
   conflicts are caused by writing the same value to an attribute again