Some notes on the docs of multiprocessing

[elibendersky]

BPO	13686
Nosy	@pitrou, @ezio-melotti

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2012-07-13.07:11:11.020>
created_at = <Date 2011-12-31.05:00:12.105>
labels = ['type-bug', 'docs']
title = 'Some notes on the docs of multiprocessing'
updated_at = <Date 2012-07-13.07:11:11.002>
user = 'https://bugs.python.org/elibendersky'

bugs.python.org fields:

activity = <Date 2012-07-13.07:11:11.002>
actor = 'eli.bendersky'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-07-13.07:11:11.020>
closer = 'eli.bendersky'
components = ['Documentation']
creation = <Date 2011-12-31.05:00:12.105>
creator = 'eli.bendersky'
dependencies = []
files = []
hgrepos = []
issue_num = 13686
keywords = []
message_count = 6.0
messages = ['150409', '150411', '165359', '165360', '165364', '165365']
nosy_count = 6.0
nosy_names = ['pitrou', 'jnoller', 'ezio.melotti', 'eli.bendersky', 'docs@python', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue13686'
versions = ['Python 3.3']

[elibendersky]

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?

[elibendersky]

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?

[python-dev]

New changeset caea3c64442b by Eli Bendersky in branch 'default':
Some fixes for the documentation of multiprocessing (per issue bpo-13686)
http://hg.python.org/cpython/rev/caea3c64442b

[elibendersky]

Switching this to 3.3 only

Fixes for 1-3 committed in caea3c64442b

[python-dev]

New changeset 1110692aac71 by Eli Bendersky in branch 'default':
Additional fixes to multiprocessing docs (for issue bpo-13686)
http://hg.python.org/cpython/rev/1110692aac71

[elibendersky]

Done (except 5 and 6, which are non-issues on a second look)