classification
Title: Update multiprocessing docs re: freeze_support
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: davin Nosy List: Winterflower, asksol, bcorfman, berker.peksag, davin, docs@python, eric.araujo, georg.brandl, jnoller, python-dev, rhettinger, sandro.tosi, terry.reedy
Priority: low Keywords: patch

Created on 2009-03-17 18:01 by bcorfman, last changed 2016-01-07 16:54 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
issue5501-v1.patch Winterflower, 2015-12-09 21:42 review
issue_5501_explicit_freeze_support_nonWin_v27.patch davin, 2015-12-17 01:43 doc change for freeze_support, 2.7 branch review
issue_5501_explicit_freeze_support_nonWin_v3x.patch davin, 2015-12-17 01:44 doc change for freeze_support, 3.x branches review
Messages (12)
msg83690 - (view) Author: Brandon Corfman (bcorfman) Date: 2009-03-17 18:01
Indicate in docs whether freeze_support() can be called without issues
on Unix or OS X, so the user knows whether they can have a single code
base that works correctly on all platforms.
msg113203 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-07 21:06
I think that question is covered by "If the module is being run normally by the Python interpreter then freeze_support() has no effect."

Jesse, do you think anything more is needed, like '(on any platform)' after 'interpreter', or should be close this?
msg117823 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2010-10-01 18:44
Hello,
well it's just 3 words that can clarify the situation, so maybe just add them would be nice

Regards,
Sandro
msg117837 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-10-01 21:16
I’m assuming this is a feature new in 2.7 and 3.2, please add 3.1 if this is wrong.
msg117974 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2010-10-04 17:47
Sorry Éric, I don't get it: do you mean that the fact that "freeze_support() can be called without issues on Unix or OS X" is a new feature? or I misread it completely?
msg117975 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-10-04 18:13
Rephrased: Is this relevant for 3.1?

(Bug and doc fixes go into 3.2, 3.1 and 2.7, but here only 3.2 and 2.7 are selected, so I asked if the bugfix/new feature/behavior in question was something new in 3.2 and thus not in 3.1.)
msg256163 - (view) Author: Camilla Montonen (Winterflower) Date: 2015-12-09 21:42
Hi everyone!
It has been a while since this issue has been updated. 
The addition requested by Brandon Corfman is a simple clarification of what happens when the freeze_support function from multiprocessing is called on non-Windows platforms (if I understand correctly, the primary purpose of freeze_support is to help in creating Windows executables). 
Although there is already some documentation which suggests that no adverse effects will occur when running code that calls freeze_support on OS X and Unix, I added a sentence in the docs that will hopefully clarify this. 

Patch attached.
msg256570 - (view) Author: Davin Potts (davin) * (Python committer) Date: 2015-12-17 01:43
Thank you, Winterflower, for the nudge to see this set right.

In truth, invoking multiprocessing.freeze_support() has zero effect on platforms other than Windows.

This should be reflected in the 2.7 docs as well as the 3.x docs that are still actively being updated.

Attached are 2 patches -- they should be cleanly applied to the 2.7, 3.5, and default (3.6) branches.  This change clarifies the last line of existing documentation around freeze_support() as well as clearly states what I mentioned above.
msg257126 - (view) Author: Camilla Montonen (Winterflower) Date: 2015-12-28 18:40
Patch review:

3.X patch:
Applied to docs locally in the default branch(3.6). Docs build passes, doc layout has not been broken. 

Applied to branch 3.5. Docs build passes, doc layout has not been broken.

2.X patch:
Applied to docs locally in the 2.7 branch. Docs build passes, doc layout has not been broken. 


Comments on the contents of the patch:

if the module is being run normally by the Python interpreter on Windows (the program has not been frozen)

For a newbie Python user it might not be entirely clear what 'run normally by the Python interpreter' means. Perhaps it would be nice to add a clarifying clause 

if the module is being run normally by the Python interpreter ( for example, by running python <filename.py> from the command prompt) on Windows (the program has not been frozen)

or something similar.
msg257700 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-01-07 16:46
New changeset f08d4712a055 by Berker Peksag in branch '3.5':
Issue #5501: Clarify that invoking freeze_support() on non-Windows platforms has no effect
https://hg.python.org/cpython/rev/f08d4712a055

New changeset 2902f32d1ae9 by Berker Peksag in branch 'default':
Issue #5501: Clarify that invoking freeze_support() on non-Windows platforms has no effect
https://hg.python.org/cpython/rev/2902f32d1ae9
msg257701 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-01-07 16:50
New changeset 8b20a606ecde by Berker Peksag in branch '2.7':
Issue #5501: Clarify that invoking freeze_support() on non-Windows platforms has no effect
https://hg.python.org/cpython/rev/8b20a606ecde
msg257702 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-01-07 16:54
Thanks Davin and Camilla.
History
Date User Action Args
2016-01-07 16:54:59berker.peksagsetstatus: open -> closed

nosy: + berker.peksag
messages: + msg257702

resolution: fixed
stage: patch review -> resolved
2016-01-07 16:50:04python-devsetmessages: + msg257701
2016-01-07 16:46:00python-devsetnosy: + python-dev
messages: + msg257700
2015-12-28 18:40:31Winterflowersetmessages: + msg257126
2015-12-17 01:45:42davinsetnosy: + rhettinger
2015-12-17 01:44:39davinsetfiles: + issue_5501_explicit_freeze_support_nonWin_v3x.patch
2015-12-17 01:43:18davinsetfiles: + issue_5501_explicit_freeze_support_nonWin_v27.patch
versions: + Python 3.5, Python 3.6, - Python 3.2
messages: + msg256570

assignee: jnoller -> davin
stage: patch review
2015-12-12 00:12:40berker.peksagsetnosy: + davin
2015-12-09 21:42:41Winterflowersetfiles: + issue5501-v1.patch

nosy: + Winterflower
messages: + msg256163

keywords: + patch
2010-10-04 18:13:45eric.araujosetmessages: + msg117975
2010-10-04 17:47:37sandro.tosisetmessages: + msg117974
2010-10-01 21:16:25eric.araujosetnosy: + eric.araujo, docs@python
messages: + msg117837
2010-10-01 18:44:33sandro.tosisetnosy: + sandro.tosi
messages: + msg117823
2010-08-31 10:58:25asksolsetnosy: + asksol
2010-08-07 21:06:16terry.reedysetversions: + Python 2.7, Python 3.2, - Python 2.6
2010-08-07 21:06:03terry.reedysetnosy: + terry.reedy
messages: + msg113203
2009-03-29 14:35:53jnollersetpriority: low
2009-03-17 18:03:01jnollersetassignee: georg.brandl -> jnoller
2009-03-17 18:01:43bcorfmancreate