[New-bugs-announce] [issue13686] Some notes on the docs of multiprocessing

[Eli Bendersky]

New submission from Eli Bendersky <eliben at gmail.com>:

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?

----------
assignee: docs at python
components: Documentation
messages: 150409
nosy: docs at python, eli.bendersky, pitrou
priority: normal
severity: normal
status: open
title: Some notes on the docs of multiprocessing
type: behavior
versions: Python 2.7

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