# HG changeset patch # Parent a9c34db88d798e514c1dc25c914d35647e2d97d7 diff -r a9c34db88d79 Doc/glossary.rst --- a/Doc/glossary.rst Sat Jun 13 11:19:43 2015 +0300 +++ b/Doc/glossary.rst Sun Jun 14 12:42:57 2015 +0000 @@ -94,8 +94,8 @@ awaitable An object that can be used in an :keyword:`await` expression. Can be - a :term:`coroutine` or an object with an :meth:`__await__` method. - See also :pep:`492`. + a native :term:`coroutine` object or an object with an + :meth:`__await__` method. See also :pep:`492`. BDFL Benevolent Dictator For Life, a.k.a. `Guido van Rossum @@ -169,18 +169,25 @@ statement by defining :meth:`__enter__` and :meth:`__exit__` methods. See :pep:`343`. - coroutine function - A function which returns a :term:`coroutine` object. It is defined - with an :keyword:`async def` keyword, and may contain :keyword:`await`, - :keyword:`async for`, and :keyword:`async with` keywords. Introduced - by :pep:`492`. - coroutine Coroutines is a more generalized form of subroutines. Subroutines are - entered at one point and exited at another point. Coroutines, can be - entered, exited, and resumed at many different points. See - :keyword:`await` expressions, and :keyword:`async for` and - :keyword:`async with` statements. See also :pep:`492`. + entered at one point and exited at another point. Coroutines can be + entered, exited, and resumed at many different points. They can + be scheduled with an event loop or trampoline function to allow one + coroutine to yield control to other routines without blocking. + + :dfn:`Native coroutines` may use :keyword:`await` expressions, and + :keyword:`async for` and :keyword:`async with` statements. Coroutines + may also be implemented using :term:`generator` functions. See + :pep:`342` about generator-based coroutines, and :pep:`492` about + native coroutines. + + coroutine function + A function which returns a :term:`coroutine` object. A :dfn:`native + coroutine function` is defined with the :keyword:`async def` keywords, + and may contain :keyword:`await`, :keyword:`async for`, and + :keyword:`async with` keywords. Native coroutines were introduced + by :pep:`492`. CPython The canonical implementation of the Python programming language, as diff -r a9c34db88d79 Doc/howto/functional.rst --- a/Doc/howto/functional.rst Sat Jun 13 11:19:43 2015 +0300 +++ b/Doc/howto/functional.rst Sun Jun 14 12:42:57 2015 +0000 @@ -607,7 +607,8 @@ The cumulative effect of these changes is to turn generators from one-way producers of information into both producers and consumers. -Generators also become **coroutines**, a more generalized form of subroutines. +Generators also become :term:`coroutines `, +a more generalized form of subroutines. Subroutines are entered at one point and exited at another point (the top of the function, and a ``return`` statement), but coroutines can be entered, exited, and resumed at many different points (the ``yield`` statements). diff -r a9c34db88d79 Doc/library/asyncio-task.rst --- a/Doc/library/asyncio-task.rst Sat Jun 13 11:19:43 2015 +0300 +++ b/Doc/library/asyncio-task.rst Sun Jun 14 12:42:57 2015 +0000 @@ -8,7 +8,9 @@ Coroutines ---------- -A coroutine is a generator that follows certain conventions. For +In the context of the :mod:`asyncio` module, a +:dfn:`coroutine` is a :term:`generator` or native +:term:`coroutine` that follows certain conventions. For documentation purposes, all coroutines should be decorated with ``@asyncio.coroutine``, but this cannot be strictly enforced. diff -r a9c34db88d79 Doc/library/asyncio.rst --- a/Doc/library/asyncio.rst Sat Jun 13 11:19:43 2015 +0300 +++ b/Doc/library/asyncio.rst Sun Jun 14 12:42:57 2015 +0000 @@ -18,7 +18,8 @@ -------------- This module provides infrastructure for writing single-threaded concurrent -code using coroutines, multiplexing I/O access over sockets and other +code using :term:`coroutines `, +multiplexing I/O access over sockets and other resources, running network clients and servers, and other related primitives. Here is a more detailed list of the package contents: diff -r a9c34db88d79 Doc/library/collections.abc.rst --- a/Doc/library/collections.abc.rst Sat Jun 13 11:19:43 2015 +0300 +++ b/Doc/library/collections.abc.rst Sun Jun 14 12:42:57 2015 +0000 @@ -157,14 +157,14 @@ ABC for classes that provide ``__await__`` method. Instances of such classes can be used in ``await`` expression. - :term:`coroutine` objects and instances of - :class:`~collections.abc.Coroutine` are too instances of this ABC. + Native :term:`coroutine` objects and instances of + :class:`~collections.abc.Coroutine` are both instances of this ABC. .. versionadded:: 3.5 .. class:: Coroutine - ABC for coroutine compatible classes that implement a subset of + ABC for native coroutine compatible classes that implement a subset of generator methods defined in :pep:`342`, namely: :meth:`~generator.send`, :meth:`~generator.throw`, :meth:`~generator.close` methods. :meth:`__await__` must also be diff -r a9c34db88d79 Doc/library/dis.rst --- a/Doc/library/dis.rst Sat Jun 13 11:19:43 2015 +0300 +++ b/Doc/library/dis.rst Sun Jun 14 12:42:57 2015 +0000 @@ -508,12 +508,13 @@ Implements ``del TOS1[TOS]``. -**Coroutines opcodes** +**Coroutine opcodes** .. opcode:: GET_AWAITABLE - Implements ``TOS = get_awaitable(TOS)``; where ``get_awaitable(o)`` - returns ``o`` if ``o`` is a coroutine object; or resolved ``o.__await__``. + Implements ``TOS = get_awaitable(TOS)``, where ``get_awaitable(o)`` + returns ``o`` if ``o`` is a native coroutine object, or resolves + ``o.__await__``. .. opcode:: GET_AITER diff -r a9c34db88d79 Doc/library/inspect.rst --- a/Doc/library/inspect.rst Sat Jun 13 11:19:43 2015 +0300 +++ b/Doc/library/inspect.rst Sun Jun 14 12:42:57 2015 +0000 @@ -279,10 +279,8 @@ .. function:: iscoroutinefunction(object) - Return true if the object is a :term:`coroutine function`. - - Coroutine functions are defined with an ``async def`` syntax, - or are generators decorated with :func:`types.coroutine` + Return true if the object is a native :term:`coroutine function`, + or a generator decorated with :func:`types.coroutine` or :func:`asyncio.coroutine`. The function will return false for plain Python generator @@ -293,11 +291,9 @@ .. function:: iscoroutine(object) - Return true if the object is a :term:`coroutine`. - - Coroutines are results of calls of coroutine functions or - generator functions decorated with :func:`types.coroutine` - or :func:`asyncio.coroutine`. + Return true if the object is a native + :term:`coroutine` object, or the result of a calling a + generator function decorated with :func:`types.coroutine`. The function will return false for plain python generators. @@ -1119,7 +1115,7 @@ Current State of a Generator ---------------------------- -When implementing coroutine schedulers and for other advanced uses of +When implementing :term:`coroutine` schedulers and for other advanced uses of generators, it is useful to determine whether a generator is currently executing, is waiting to start or resume or execution, or has already terminated. :func:`getgeneratorstate` allows the current state of a diff -r a9c34db88d79 Doc/library/sys.rst --- a/Doc/library/sys.rst Sat Jun 13 11:19:43 2015 +0300 +++ b/Doc/library/sys.rst Sun Jun 14 12:42:57 2015 +0000 @@ -1075,9 +1075,9 @@ .. function:: set_coroutine_wrapper(wrapper) - Allows to intercept creation of :term:`coroutine` objects. + Allows intercepting creation of native :term:`coroutine` objects. - *wrapper* must be either: + The *wrapper* argument must be either: * a callable that accepts one argument (a coroutine object); * ``None``, to reset the wrapper. @@ -1085,7 +1085,8 @@ If called twice, the new wrapper replaces the previous one. The function is thread-specific. - The *wrapper* callable cannot define new coroutines directly or indirectly:: + The *wrapper* callable cannot define new native coroutines directly or + indirectly:: def wrapper(coro): async def wrap(coro): diff -r a9c34db88d79 Doc/library/types.rst --- a/Doc/library/types.rst Sat Jun 13 11:19:43 2015 +0300 +++ b/Doc/library/types.rst Sun Jun 14 12:42:57 2015 +0000 @@ -273,13 +273,14 @@ .. versionadded:: 3.4 -Coroutines Utility Functions ----------------------------- +Coroutine Utility Functions +--------------------------- .. function:: coroutine(gen_func) - The function transforms a generator function to a :term:`coroutine function`, - so that it returns a :term:`coroutine` object. + The function transforms a :term:`generator` function into a + :term:`coroutine function` that returns a :term:`coroutine` object + compatible with native coroutines. *gen_func* is modified in-place, hence the function can be used as a decorator. diff -r a9c34db88d79 Doc/reference/compound_stmts.rst --- a/Doc/reference/compound_stmts.rst Sat Jun 13 11:19:43 2015 +0300 +++ b/Doc/reference/compound_stmts.rst Sun Jun 14 12:42:57 2015 +0000 @@ -666,6 +666,23 @@ Coroutines ========== +Python :term:`coroutines ` can be used in conjunction with an +event loop or "trampoline" function. When a coroutine wishes to allow +other routines to run, it yields control to the event loop. The event loop +uses :meth:`~generator.send` to resume the coroutines as needed. + +Python coroutines cannot choose what coroutine to transfer control to +when they suspend, unlike those in some other languages. Instead, the +choice of what runs next must be handled by the event loop. Indeed, if +coroutines try to use :meth:`~generator.send` to transfer control directly +between each other, an exception will be raised ("ValueError: generator already +executing"). + +This section deals with native coroutines. Coroutines may also be +implemented as :term:`generators ` with the :keyword:`yield` +expression. + + .. _`async def`: Coroutine function definition @@ -681,7 +698,8 @@ Functions defined with ``async def`` syntax are always coroutine functions, even if they do not contain ``await`` or ``async`` keywords. -It is a :exc:`SyntaxError` to use :keyword:`yield` expressions in coroutines. +It is a :exc:`SyntaxError` to use :keyword:`yield` expressions in native +coroutines. .. versionadded:: 3.5 diff -r a9c34db88d79 Doc/reference/datamodel.rst --- a/Doc/reference/datamodel.rst Sat Jun 13 11:19:43 2015 +0300 +++ b/Doc/reference/datamodel.rst Sun Jun 14 12:42:57 2015 +0000 @@ -616,15 +616,15 @@ exception is raised and the iterator will have reached the end of the set of values to be returned. - Coroutine functions + Native coroutine functions .. index:: single: coroutine; function A function or method which is defined using :keyword:`async def` is called - a :dfn:`coroutine function`. Such a function, when called, returns a - :term:`coroutine` object. It may contain :keyword:`await` expressions, + a :dfn:`native coroutine function`. Such a function, when called, returns a + native :term:`coroutine` object. It may contain :keyword:`await` expressions, as well as :keyword:`async with` and :keyword:`async for` statements. See - also :ref:`coroutines` section. + also the :ref:`coroutines` section. Built-in functions .. index:: @@ -2278,7 +2278,7 @@ An *awaitable* object can be one of the following: -* A :term:`coroutine` object returned from a :term:`coroutine function`. +* A :term:`coroutine` object returned from a native :term:`coroutine function`. * A :term:`generator` decorated with :func:`types.coroutine` (or :func:`asyncio.coroutine`) decorator. diff -r a9c34db88d79 Doc/reference/expressions.rst --- a/Doc/reference/expressions.rst Sat Jun 13 11:19:43 2015 +0300 +++ b/Doc/reference/expressions.rst Sun Jun 14 12:42:57 2015 +0000 @@ -343,7 +343,8 @@ .. index:: single: coroutine -All of this makes generator functions quite similar to coroutines; they yield +All of this makes generator functions quite similar +to :term:`coroutines `; they yield multiple times, they have more than one entry point and their execution can be suspended. The only difference is that a generator function cannot control where the execution should continue after it yields; the control is always @@ -817,7 +818,7 @@ ================ Suspend the execution of :term:`coroutine` on an :term:`awaitable` object. -Can only be used inside a :term:`coroutine function`. +Can only be used inside a native :term:`coroutine function`. .. productionlist:: await: ["await"] `primary`