This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: The gloss on asyncio "future with run_forever" example is confusing
Type: behavior Stage: resolved
Components: asyncio, Documentation Versions: Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, giampaolo.rodola, gvanrossum, pitrou, python-dev, r.david.murray, vstinner, yselivanov
Priority: normal Keywords:

Created on 2014-09-23 23:46 by r.david.murray, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Messages (4)
msg227398 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-09-23 23:46
In https://docs.python.org/3/library/asyncio-task.html#example-future-with-run-forever we have the sentence

  In this example, the future is responsible to display the result and to stop the loop.

We could dune up the English by rewriting it:

  In this example, the future is responsible for displaying the result and stopping the loop.

But that isn't quite true.  It is the callback associated with the future that is displaying the result and stopping the loop.  So, perhaps the correct gloss is:

  In this example, the got_result callback is responsible for displaying the result and stopping the loop.
msg227455 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2014-09-24 14:39
"But that isn't quite true.  It is the callback associated with the future that is displaying the result and stopping the loop."

I wrote this example to show that setting the result of a future can schedule a callback. I mean something like:

"In this example, the future is used to link slow_operation() to got_result(): when slow_operation() is done, got_result() is called with the result."

The main idea behind Future is to chain callbacks and the link is done externally. It's different from this design:

    def slow_operation(done_callback):
        ...
        done_callback()
msg232018 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-12-02 16:53
New changeset a4b58e779a16 by Victor Stinner in branch '3.4':
Close #22473: asyncio doc: rephrase Future with run_forever() example
https://hg.python.org/cpython/rev/a4b58e779a16
msg232019 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2014-12-02 16:54
I rephrase the explanation of the example and I removed the useless note. Thanks for your feedback David. Don't hesitate to propose other enhancements to the documentation!
History
Date User Action Args
2022-04-11 14:58:08adminsetgithub: 66663
2014-12-02 16:54:03vstinnersetmessages: + msg232019
2014-12-02 16:53:13python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg232018

resolution: fixed
stage: resolved
2014-09-24 14:42:21vstinnersetcomponents: + asyncio
2014-09-24 14:39:36vstinnersetmessages: + msg227455
2014-09-24 08:50:59pitrousetnosy: + gvanrossum, pitrou, vstinner, giampaolo.rodola, yselivanov
2014-09-23 23:46:15r.david.murraycreate