[Python-checkins] cpython (2.7): Issue 16998: Clarify that += on a shared value is not atomic.

[richard.oudkerk]

http://hg.python.org/cpython/rev/7aabbe919f55
changeset:   87205:7aabbe919f55
branch:      2.7
user:        Richard Oudkerk <shibturn at gmail.com>
date:        Sun Nov 17 17:00:38 2013 +0000
summary:
  Issue 16998: Clarify that += on a shared value is not atomic.

files:
  Doc/library/multiprocessing.rst |  24 +++++++++++++++-----
  1 files changed, 18 insertions(+), 6 deletions(-)


diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -960,12 +960,24 @@
    ctypes type or a one character typecode of the kind used by the :mod:`array`
    module.  *\*args* is passed on to the constructor for the type.
 
-   If *lock* is ``True`` (the default) then a new lock object is created to
-   synchronize access to the value.  If *lock* is a :class:`Lock` or
-   :class:`RLock` object then that will be used to synchronize access to the
-   value.  If *lock* is ``False`` then access to the returned object will not be
-   automatically protected by a lock, so it will not necessarily be
-   "process-safe".
+   If *lock* is ``True`` (the default) then a new recursive lock
+   object is created to synchronize access to the value.  If *lock* is
+   a :class:`Lock` or :class:`RLock` object then that will be used to
+   synchronize access to the value.  If *lock* is ``False`` then
+   access to the returned object will not be automatically protected
+   by a lock, so it will not necessarily be "process-safe".
+
+   Operations like ``+=`` which involve a read and write are not
+   atomic.  So if, for instance, you want to atomically increment a
+   shared value it is insufficient to just do ::
+
+       counter.value += 1
+
+   Assuming the associated lock is recursive (which it is by default)
+   you can instead do ::
+
+       with counter.get_lock():
+           counter.value += 1
 
    Note that *lock* is a keyword-only argument.
 

-- 
Repository URL: http://hg.python.org/cpython