classification
Title: Manager documentation unclear about lists and thread safeness
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Irvin.Probst, docs@python, erlendaasland, sbt
Priority: normal Keywords:

Created on 2014-02-14 14:56 by Irvin.Probst, last changed 2021-04-04 14:33 by erlendaasland.

Files
File name Uploaded Description Edit
example.py Irvin.Probst, 2014-02-14 14:56
Messages (2)
msg211220 - (view) Author: Irvin Probst (Irvin.Probst) Date: 2014-02-14 14:56
In the the Manager's lists documentation one can read:

"""
list()
list(sequence)
Create a shared list object and return a proxy for it.
"""

IMHO it is really unclear whether these lists have something more than traditionnal lists or not. 

When you have a look at managers.py it is quite obvious, unless I'm completely wrong, that the underlying shared object is a standard list with a basic proxy to expose all the "underscore underscore stuff".

"""
BaseListProxy = MakeProxyType('BaseListProxy', (
    '__add__', '__contains__', '__delitem__', '__getitem__', '__len__',
    '__mul__', '__reversed__', '__rmul__', '__setitem__',
    'append', 'count', 'extend', 'index', 'insert', 'pop', 'remove',
    'reverse', 'sort', '__imul__'
    ))

class ListProxy(BaseListProxy):
    def __iadd__(self, value):
        self._callmethod('extend', (value,))
        return self
    def __imul__(self, value):
        self._callmethod('__imul__', (value,))
        return self

    [snip a couple of lines]

SyncManager.register('list', list, ListProxy)
"""

That's really confusing because, unless reading managers.py, you have the feeling that the manager's lists() are somehow different than standard lists.

The other problem is that, if you don't know what level of thread-safeness the GIL guarantees on the lists in the manager's server thread, you have the feeling that the safeness comes from some obscure Manager's black magic managing concurrent access for you.

May I suggest to add in the documentation:


1/

"""
list()
list(sequence)
Create a shared list (add here a link to http://docs.python.org/3.3/library/stdtypes.html#list) object and return a proxy for it.
"""

2/ 

Clearly state somewhere in the manager's documentation that it's the developper's job to ensure that the proxied methods are thread safe. Write it in bold and red please :-) 

3/ 
Perhaps add an example with a custom object like the code I attached to this report.


Thanks for your time.
msg390190 - (view) Author: Erlend Egeberg Aasland (erlendaasland) * Date: 2021-04-04 14:33
1. A link was added in commit 86a76684269f940a20366cb42668f1acb0982dca
2. The Programming Guidelines mentions thread safety of proxies: https://docs.python.org/3/library/multiprocessing.html#programming-guidelines


Can this be closed?
History
Date User Action Args
2021-04-04 14:33:26erlendaaslandsetnosy: + erlendaasland
messages: + msg390190
2014-02-14 21:35:31berker.peksagsetnosy: + sbt
2014-02-14 17:34:22zach.waresetstage: needs patch
type: enhancement
versions: - Python 3.1, Python 3.2, Python 3.5
2014-02-14 16:02:30Irvin.Probstsetassignee: docs@python

nosy: + docs@python
components: + Documentation
versions: + Python 3.1, Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5
2014-02-14 14:56:06Irvin.Probstcreate