classification
Title: multiprocessing Proxy docs need locking semantics explained
Type: Stage:
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, maxpolk, sbt
Priority: normal Keywords:

Created on 2013-12-02 19:00 by maxpolk, last changed 2013-12-03 15:42 by sbt.

Messages (2)
msg205039 - (view) Author: Max Polk (maxpolk) Date: 2013-12-02 19:00
In the docs (both Python 2 and 3) for the multiprocessing module, the Proxy section needs to be explicit about the fact that is does NOT create locks around access to shared objects.

Why?  Because on the same page, we read about multiprocessing.managers.SyncManager's Queue method to create a shared queue.Queue object and return a proxy for it, next to other methods like SyncManager.list to create a "process safe" list.

But later, a willful violation of these semantics exists in the "Using a remote manager" section where a Proxy is implicitly created (via the register method of multiprocessing.managers.BaseManager) surrounding a Queue.Queue object.

Note that it did not create a proxy around a SyncManager.Queue, it created it around a Queue.Queue.  A user who copies this code and replaces Queue.Queue with a plain Python list gets the sense that all the needed locks will be created to protect the shared list.

However, due to lack of documentation in the Proxy section, the user will not know it's an unsafe list, and Proxy isn't helping them.  I'm guessing that Queue.Queue has its own locks to protect it in a process-shared setting, and we "lucked out" in this example, but an unwary reader's luck runs out if they replace it with a plain Python list.

Therefore, may I suggest two changes: (1) replace Queue.Queue with SyncManager.Queue in the "Using a remote manager" section to avoid misleading readers; and (2) be explicit in Proxy class docs that "no locks are created" to protect against concurrent access, and maybe add that the user must go to the multiprocessing.managers.SyncManager methods (Queue, list, etc) to get "process safe" objects to place behind the Proxy.
msg205122 - (view) Author: Richard Oudkerk (sbt) * (Python committer) Date: 2013-12-03 15:42
From what I remember a proxy method will be thread/process-safe if the referent's corresponding method is thread safe.

It should certainly be documented that the exposed methods of a proxied object should be thread-safe.
History
Date User Action Args
2013-12-03 15:42:44sbtsetmessages: + msg205122
2013-12-02 21:54:00ned.deilysetnosy: + sbt

versions: + Python 2.7, Python 3.3, Python 3.4
2013-12-02 19:00:54maxpolkcreate