classification
Title: mention in time.sleep() docs that it does not block other Python threads
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: akira, asvetlov, docs@python, georg.brandl, martin.panter, pitrou, python-dev, r.david.murray
Priority: normal Keywords: patch

Created on 2015-01-16 17:01 by akira, last changed 2016-04-19 00:01 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
docs-time.sleep-other-threads-are-not-blocked.diff akira, 2015-01-16 17:01 review
docs-time.sleep-other-threads-are-not-blocked-2.diff akira, 2015-01-25 10:52 review
Messages (19)
msg234135 - (view) Author: Akira Li (akira) * Date: 2015-01-16 17:01
There is the corresponding StackOverflow question with 60K view 
"time.sleep — sleeps thread or process?" [1]

The documentation patch is attached.

[1] http://stackoverflow.com/questions/92928/time-sleep-sleeps-thread-or-process
msg234136 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-01-16 17:42
Can you re-upload the patch without reflowing the paragraph?  I think the only thing needed is the addition of the word thread, to mirror the equivalent unix man page phrasing, and I think that's what you've done, but I can't easily tell from the provided patch.
msg234149 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-01-16 21:58
There is also a new sentence about the GIL at the end, but leaving the inbetween lines as they were would verify this
msg234150 - (view) Author: Akira Li (akira) * Date: 2015-01-16 22:56
I do not understand. Have you tried to look at the patch in Rietveld?

The new content is highlighted in a darker green. It is clearly
visible. I've tested on Chromium, Firefox, Safari.

If I won't reflow then the first line will be longer than the
recommended 80 in devguide:

> The maximum line length is 80 characters for normal text, but
> tables, deeply indented code samples and long links may extend
> beyond that.

I've set *fill-column* to 80 in emacs. Do you suggest other settings?

Anyway, it doesn't affect how the final text is shown in a web
browser.
msg234152 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2015-01-16 23:15
I guess R. David Murray asked you to make the least minimal change,
even it breaks the formatting rules.

Paragraph reflow is safe when it's done by the Core Developer but it
requires additional check (and probably mercurial conflict errors on
merging the change with default branch if the last has changes also).

In your case I see no problems though, but the final decision is on R.
David Murray

On Sat, Jan 17, 2015 at 12:56 AM, Akira Li <report@bugs.python.org> wrote:
>
> Akira Li added the comment:
>
> I do not understand. Have you tried to look at the patch in Rietveld?
>
> The new content is highlighted in a darker green. It is clearly
> visible. I've tested on Chromium, Firefox, Safari.
>
> If I won't reflow then the first line will be longer than the
> recommended 80 in devguide:
>
>> The maximum line length is 80 characters for normal text, but
>> tables, deeply indented code samples and long links may extend
>> beyond that.
>
> I've set *fill-column* to 80 in emacs. Do you suggest other settings?
>
> Anyway, it doesn't affect how the final text is shown in a web
> browser.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue23251>
> _______________________________________
> _______________________________________________
> docs mailing list
> docs@python.org
> https://mail.python.org/mailman/listinfo/docs
msg234153 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-01-16 23:21
What I have sometimes done in this situation is just break the overly long line into two short lines
msg234158 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-01-17 02:51
I actually didn't know that reitveld was smart enough to highlight just the text changes in a reflowed paragraph.

Nevertheless, for ease of looking at diff in the repository using the hg command (which is not that smart), I prefer to commit doc changes without the reflow, then do the reflow in a separate commit.  I don't know if other developers do this or not.

I think the patch is fine.
msg234176 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2015-01-17 16:54
I think it's superfluous to mention the GIL here, since it has no impact on the function.
msg234184 - (view) Author: Akira Li (akira) * Date: 2015-01-17 18:01
> I think it's superfluous to mention the GIL here, since it has no impact on the function.

If GIL is not released then all Python code in other threads is 
effectively blocked.
It is worth mentioning explicitly that it is guaranteed to be released
during the sleep.
msg234185 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2015-01-17 18:03
> If GIL is not released then all Python code in other threads is 
> effectively blocked.

But that would be a stupid implementation of sleep(). It is not desirable to clutter the docs with such mentions: most calls to the OS in the stdlib release the GIL.

Only if the behaviour was unintuitive (i.e. if it *didn't* release the GIL) would it make sense to document it.
msg234188 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-01-17 18:35
Yes, on consideration I agree with Antoine.  That last sentence should be deleted.  Otherwise we'd need to mention that the gil was released every place that the gil was released, which would be very redundant.  The general rule is that anything that blocks in python releases the GIL, therefore as Antoine says the only time we need to document GIL behavior is when that *doesn't* happen.
msg234251 - (view) Author: Akira Li (akira) * Date: 2015-01-18 14:36
> Only if the behaviour was unintuitive (i.e. if it *didn't* release the
> GIL) would it make sense to document it.

There is no intuitive interface, not even the nipple. It's all learned. [1]

> Yes, on consideration I agree with Antoine.  That last sentence should
> be deleted.  Otherwise we'd need to mention that the gil was released
> every place that the gil was released, which would be very redundant.

Whether or not other places mention it is unrelated to the current
issue.

Though the documentation should mention it more. Many programmers are
convinced that Python threads can't be executed in parallel.

> The general rule is that anything that blocks in python releases the
> GIL, therefore as Antoine says the only time we need to document GIL
> behavior is when that *doesn't* happen.

The reader of Python documentation is intelegent but not all-knowing.

"Blocking" is the first and only job for time.sleep() function.
GIL "blocks" Python code.
You can't understand what time.sleep does without knowing what happens
to GIL.

Ask yourself who and why reads the time.sleep() documentation (novice
and/or exprerienced Python user). Put yourself into the mind of the
reader.


[1] http://www.greenend.org.uk/rjk/misc/nipple.html
msg234252 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2015-01-18 14:39
Please let's stop it. Mentioning the GIL in every place in the documentation will only make people more worried and confused about something they shouldn't be confused or worried about.

If you think some docs should discuss the GIL and its effect on running threads then I suggest writing a separate document (a HOWTO for example, like the Unicode HOWTO).
msg234280 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2015-01-18 21:35
I'm with Antoine.

Yes, GIL is extremely important but please don't put GIL mentions everywhere.

On Sun, Jan 18, 2015 at 4:39 PM, Antoine Pitrou <report@bugs.python.org> wrote:
>
> Antoine Pitrou added the comment:
>
> Please let's stop it. Mentioning the GIL in every place in the documentation will only make people more worried and confused about something they shouldn't be confused or worried about.
>
> If you think some docs should discuss the GIL and its effect on running threads then I suggest writing a separate document (a HOWTO for example, like the Unicode HOWTO).
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue23251>
> _______________________________________
msg234281 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2015-01-18 21:47
Agreed. "of the current thread" is a good addition.  The sleep() docs are already longer than I would like.
msg234660 - (view) Author: Akira Li (akira) * Date: 2015-01-25 10:52
I've removed mentioning of GIL and uploaded a new patch.
msg234686 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-01-25 20:49
New changeset 55ad65c4f9e2 by R David Murray in branch '3.4':
#23251: Note that time.sleep affects the calling thread only.
https://hg.python.org/cpython/rev/55ad65c4f9e2

New changeset 5e01c68cabbf by R David Murray in branch '2.7':
#23251: note that time.sleep affects the current thread only.
https://hg.python.org/cpython/rev/5e01c68cabbf

New changeset 5db28a3199b2 by R David Murray in branch '2.7':
#23251: Reflow paragraph.
https://hg.python.org/cpython/rev/5db28a3199b2
msg234688 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-01-25 20:51
Oops, typoed the issue number.

New changeset 3a9b1e5fe179 by R David Murray in branch '3.4':
#23215: reflow paragraph.
https://hg.python.org/cpython/rev/3a9b1e5fe179

New changeset 52a06812d5da by R David Murray in branch 'default':
Merge: #23215: note that time.sleep affects the current thread only.
https://hg.python.org/cpython/rev/52a06812d5da
msg234690 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-01-25 20:52
Thanks, Akira, but I did not use your patch, since it still had the paragraph reflow in it.
History
Date User Action Args
2016-04-19 00:01:54berker.peksagsetstatus: open -> closed
2015-01-25 20:52:50r.david.murraysetresolution: fixed
messages: + msg234690
stage: commit review -> resolved
2015-01-25 20:51:27r.david.murraysetmessages: + msg234688
2015-01-25 20:49:57python-devsetnosy: + python-dev
messages: + msg234686
2015-01-25 10:52:47akirasetfiles: + docs-time.sleep-other-threads-are-not-blocked-2.diff

messages: + msg234660
2015-01-18 21:47:37georg.brandlsetnosy: + georg.brandl
messages: + msg234281
2015-01-18 21:35:21asvetlovsetmessages: + msg234280
2015-01-18 14:39:56pitrousetmessages: + msg234252
2015-01-18 14:36:41akirasetmessages: + msg234251
2015-01-17 18:35:58r.david.murraysetmessages: + msg234188
2015-01-17 18:03:47pitrousetmessages: + msg234185
2015-01-17 18:01:25akirasetmessages: + msg234184
2015-01-17 16:54:12pitrousetnosy: + pitrou
messages: + msg234176
2015-01-17 02:51:23r.david.murraysetstage: commit review
messages: + msg234158
versions: + Python 2.7, Python 3.4
2015-01-16 23:21:13martin.pantersetmessages: + msg234153
2015-01-16 23:15:08asvetlovsetnosy: + asvetlov
messages: + msg234152
2015-01-16 22:56:22akirasetmessages: + msg234150
2015-01-16 21:58:14martin.pantersetnosy: + martin.panter
messages: + msg234149
2015-01-16 17:42:06r.david.murraysetnosy: + r.david.murray
messages: + msg234136
2015-01-16 17:01:06akiracreate