<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Tue, May 5, 2015 at 1:44 PM, Paul Moore <span dir="ltr"><<a href="mailto:p.f.moore@gmail.com" target="_blank">p.f.moore@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div class="HOEnZb"><div class="h5">[Guido]<br></div><div class="h5">
> The run_in_executor call is not callback-based -- the confusion probably<br>
> stems from the name of the function argument ('callback'). It actually<br>
> returns a Future representing the result (or error) of an operation, where<br>
> the operation is represented by the function argument. So if you have e.g. a<br>
> function<br>
><br>
>     def factorial(n):<br>
>         return 1 if n <= 0 else n*factorial(n-1)<br>
><br>
> you can run it in an executor from your async(io) code like this:<br>
><br>
>     loop = asyncio.get_event_loop()<br>
>     result = yield from loop.run_in_executor(factorial, 100)<br>
><br>
> (In a PEP 492 coroutine substitute await for yield from.)<br>
<br>
</div></div>Thanks, that's an important correction. Given that, run_in_executor is<br>
the link to blocking calls that I was searching for. And yes, the<br>
"callback" terminology does make this far from obvious, unfortunately.<br>
As does the point at which it's introduced (before futures have been<br>
described) and the fact that it says "this method is a coroutine"<br>
rather than "this method returns a Future"[1].<br>
<br>
Paul<br>
<br>
[1] I'm still struggling to understand the terminology, so if those<br>
two statements are equivalent, that's not yet obvious to me.<br>
</blockquote></div><br></div><div class="gmail_extra">I apologize for the confusing documentation. We need more help from qualified tech writers! Writing PEP 3156 was a huge undertaking for me; after that I was exhausted and did not want to take on writing the end user documentation as well, so it was left unfinished. :-(<br><br></div><div class="gmail_extra">In PEP 3156 (asyncio package) there are really three separate concepts:<br><br></div><div class="gmail_extra">- Future, which is a specific class (of which Task is a subclass);<br><br></div><div class="gmail_extra">- coroutine, by which in this context is meant a generator object obtained by calling a generator function decorated with @asyncio.coroutine and written to conform to the asyncio protocol for coroutines (i.e. don't use bare yield, only use yield from, and the latter always with either a Future or a coroutine as argument);<br><br></div><div class="gmail_extra">- either of the above, which is actually the most common requirement -- most asyncio functions that support one also support the other, and either is allowable as the argument to `yield from`.<br><br></div><div class="gmail_extra">In the implementation we so often flipped between Future and coroutine that I imagine sometimes the implementation and docs differ; also, we don't have a good short name for "either of the above" so we end up using one or the other as a shorthand.<br><br></div><div class="gmail_extra">*Unless* you want to attach callbacks, inspect the result or exception, or cancel it (all of which require a Future), your code shouldn't be concerned about the difference -- you should just use `res = yield from func(args)` and use try/except to catch exceptions if you care. And if you do need a Future, you can call the function asyncio.async() on it (which in PEP 492 is renamed to ensure_future()).<br><br></div><div class="gmail_extra">In the PEP 492 world, these concepts map as follows:<br><br>- Future translates to "something with an __await__ method" (and asyncio Futures are trivially made compliant by defining Future.__await__ as an alias for Future.__iter__);<br><br>- "asyncio coroutine" maps to "PEP 492 coroutine object" (either defined with `async def` or a generator decorated with @types.coroutine -- note that @asyncio.coroutine incorporates the latter);<br><br>- "either of the above" maps to "awaitable".</div><div class="gmail_extra"><br>-- <br><div class="gmail_signature">--Guido van Rossum (<a href="http://python.org/~guido" target="_blank">python.org/~guido</a>)</div>
</div></div>