classification
Title: Some notes on the docs of multiprocessing
Type: behavior Stage:
Components: Documentation Versions: Python 3.3
process
Status: closed Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eli.bendersky, ezio.melotti, jnoller, pitrou, python-dev
Priority: normal Keywords:

Created on 2011-12-31 05:00 by eli.bendersky, last changed 2012-07-13 07:11 by eli.bendersky. This issue is now closed.

Messages (6)
msg150409 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-12-31 05:00
I've decided to study the multiprocessing module a bit, and carefully went over the docs (for 2.7). Some small fixes I will commit myself, but a few issues came up on which I'd like some opinion from others. In rough order of appearance in the doc:

1. In the documentation of the 'name' argument of the multiprocessing.Process constructor, it mentions that the length of the generated name depends on the "generation", without elaborating. It could be better to briefly describe the algorithm in a sentence or two.
2. Section 16.6.2.1. is called "Process and exceptions". It only documents one exception from multiprocessing: BufferTooShort. Other exception classes exported by the module aren't documented similarly: ProcessError, TiemoutError, AuthenticationError.
3. AuthenticationError is documented as multiprocessing.connection.AuthenticationError, although in reality it exists in the root multiprocessing module, and multiprocessing.connection just imports it
4. The doc of JoinableQueue.task_done() says "Used by queue consumer threads". Shouldn't that be "consumer processes"?
5. The doc of active_children() should probably mention that it returns a list of Process objects (similarly to what current_process() says)
6. multiprocessing.freeze_support() says "If the freeze_support() line is omitted then trying to run the frozen executable will raise RuntimeError.". *Who* will raise the error?
7. class multiprocessing.Event says "This method returns..." - what method? Seems like an irrelevant documentation piece was intermixed here
8. 16.6.2.7. Managers starts by saying that Managers provide a way to create data which can be shared between different processes. Since it comes right after the section about Shared objects, I think it would be nice to mention in a sentence or two what Managers give above normal synchonized objects in multiprocessing (i.e. sharing between different machines)
9. In the programming guidelines about "Avoid shared state" it says "It is probably best to stick to using queues or pipes for communication between processes rather than using the lower level synchronization primitives from the threading module.". Surely not the "threading" module is meant here?
msg150411 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-12-31 07:24
10. Unless I'm missing something entirely obvious, except in the examples it says that Value has a "value" attribute for actual data access. One is expected to look in the docs of ctypes to find that?
msg165359 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-07-13 06:45
New changeset caea3c64442b by Eli Bendersky in branch 'default':
Some fixes for the documentation of multiprocessing (per issue #13686)
http://hg.python.org/cpython/rev/caea3c64442b
msg165360 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-07-13 06:46
Switching this to 3.3 only

Fixes for 1-3 committed in caea3c64442b
msg165364 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-07-13 07:10
New changeset 1110692aac71 by Eli Bendersky in branch 'default':
Additional fixes to multiprocessing docs (for issue #13686)
http://hg.python.org/cpython/rev/1110692aac71
msg165365 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-07-13 07:11
Done (except 5 and 6, which are non-issues on a second look)
History
Date User Action Args
2012-07-13 07:11:11eli.benderskysetstatus: open -> closed

messages: + msg165365
versions: + Python 3.3, - Python 2.7
2012-07-13 07:10:22python-devsetmessages: + msg165364
2012-07-13 06:46:34eli.benderskysetmessages: + msg165360
2012-07-13 06:45:47python-devsetnosy: + python-dev
messages: + msg165359
2012-01-24 10:40:28ezio.melottisetnosy: + ezio.melotti
2012-01-07 00:08:49terry.reedysetnosy: + jnoller
2011-12-31 07:24:44eli.benderskysetmessages: + msg150411
2011-12-31 05:00:12eli.benderskycreate