[docs] [issue19864] multiprocessing Proxy docs need locking semantics explained

[Max Polk]

New submission from Max Polk:

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.

----------
assignee: docs at python
components: Documentation
messages: 205039
nosy: docs at python, maxpolk
priority: normal
severity: normal
status: open
title: multiprocessing Proxy docs need locking semantics explained

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue19864>
_______________________________________