Implement asyncio.run_in_executor shortcut

[asvetlov]

BPO	32309
Nosy	@vstinner, @asvetlov, @cjerdonek, @1st1, @miss-islington, @primal100, @aeros
PRs	bpo-32311: Implement asyncio.create_task() shortcut #4848 bpo-32309: Implement asyncio.ThreadPool #18410 bpo-32309: Implement asyncio.to_thread() #20143 [3.9] bpo-32309: Implement asyncio.to_thread() (GH-20143) #20212 bpo-32309: Add support for contextvars in asyncio.to_thread() #20278 [3.9] bpo-32309: Add support for contextvars in asyncio.to_thread() (GH-20278) #20279

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-05-21.05:58:41.914>
created_at = <Date 2017-12-13.19:54:21.835>
labels = ['docs', '3.9', 'expert-asyncio']
title = 'Implement asyncio.run_in_executor shortcut'
updated_at = <Date 2020-05-21.05:58:41.913>
user = 'https://github.com/asvetlov'

bugs.python.org fields:

activity = <Date 2020-05-21.05:58:41.913>
actor = 'aeros'
assignee = 'none'
closed = True
closed_date = <Date 2020-05-21.05:58:41.914>
closer = 'aeros'
components = ['Documentation', 'asyncio']
creation = <Date 2017-12-13.19:54:21.835>
creator = 'asvetlov'
dependencies = []
files = []
hgrepos = []
issue_num = 32309
keywords = ['patch']
message_count = 43.0
messages = ['308238', '308239', '308243', '308245', '341352', '355771', '355773', '355796', '355798', '355799', '355800', '355802', '355804', '355805', '355807', '355809', '355811', '355842', '355846', '355852', '355854', '355855', '355857', '355858', '355862', '355863', '355881', '355883', '355938', '355957', '355975', '355978', '356242', '356303', '356776', '356792', '360725', '369318', '369331', '369408', '369493', '369495', '369497']
nosy_count = 7.0
nosy_names = ['vstinner', 'asvetlov', 'chris.jerdonek', 'yselivanov', 'miss-islington', 'primal', 'aeros']
pr_nums = ['4848', '18410', '20143', '20212', '20278', '20279']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue32309'
versions = ['Python 3.9']

[asvetlov]

loop.create_task() and loop.run_in_executor are present very often in user code. But they are require a loop instance, actual call looks like

loop = asyncio.get_running_loop()
loop.create_task(coro())

The proposal adds create_task(coro) and run_in_executor(executor, func, *args) shortcuts for this.

[1st1]

I don't like the low-level API of run_in_executor. "executor" being the first argument, the inability to pass **kwargs, etc.

I'd expect to see a more high-level API, perhaps the one that supports 'async with':

    async with asyncio.ThreadPool() as pool:
        f1 = pool.run(func1)
        f2 = pool.run(func2)
        r3 = await pool.run(func3)

    r1 = f1.result()
    r2 = f2.result()
    print(r1, r2, r3)

I mean it's great that we can use 'concurrent.futures' in asyncio, but having native asyncio pools implementation would be way more convenient to the users.

In any case, can we focus this issue on the "run_in_executor" API, and open a new one for "create_task"?

[asvetlov]

Removed create_task() from title

[asvetlov]

https://bugs.python.org/issue32311 opened for create_task()

[asvetlov]

In Python 3.7 loop.run_in_executor() is the only user-faced method that requires a loop.

asyncio.ThreadPool() sounds great. Maybe thread group can provide better api.

But for Python 3.8 adding run_in_executor top-level function looks the only easy and obvious way to help people getting rid of explicit loop usage.

Yuri, what do you think?

[aeros]

I don't like the low-level API of run_in_executor. "executor" being the first argument, the inability to pass **kwargs, etc.

I mean it's great that we can use 'concurrent.futures' in asyncio, but having native asyncio pools implementation would be way more convenient to the users.

I agree that there's an issue with this, but I think for the high level API it can be an asynchronous context manager that makes use of concurrent.futures.ThreadPoolExecutor, since that one seems to fit the majority of asyncio use cases. If users want to utilize concurrent.futures.ProcessPoolExecutor or a customized one, they can use loop.run_in_executor() instead.

Unless there's something I'm missing with regards to concurrent.futures.ThreadPoolExecutor that specifically makes it less usable. Can't asyncio.ThreadPool make use of concurrent.futures.ThreadPoolExecutor in the internal details while providing a better API?

I'd expect to see a more high-level API, perhaps the one that supports 'async with':

asyncio.ThreadPool() sounds great. Maybe thread group can provide better api.

I'd be willing to work on implementing the asyncio.ThreadPool API as Yury described it.

But for Python 3.8 adding run_in_executor top-level function looks the only easy and obvious way to help people getting rid of explicit loop usage.

I can see your point Andrew, but I think that if we implement asyncio.run_in_executor() and then later add asyncio.ThreadPool(), it's going to be against "one obvious way" and we'll end up adding two high-level functions for the same purpose. This principle can't always be adhered to, but I think we should try to when it's possible.

Personally, I think the API for asyncio.ThreadPool would be much more robust, so it seems worthwhile to try implementing this one first. If there are a number of unforeseen complications, asyncio.run_in_executor() might still be a decent fallback.

[aeros]

end up adding two high-level functions

Clarification: asyncio.run_in_executor() would be a function, but asyncio.ThreadPool would be a context manager class.

[aeros]

So, here's a prototype implementation of asyncio.ThreadPool that would function exactly as Yury described, but I'm not convinced about the design. Usually, it seems preferred to separate the context manager from the rest of the class (as was done with asyncio.Lock), but I think this one might be simple enough to be a single class:

class ThreadPool:
    def __init__(self, timeout=None):
        self.timeout = timeout
        self._loop = None
    
    async def __aenter__(self):
        self._loop = asyncio.get_running_loop()
        # Ensure that ThreadPoolExecutor is being used
        self._loop.default_executor = concurrent.futures.ThreadPoolExecutor()
        return self

    async def __aexit__(self, *args):
        await self._loop.shutdown_default_executor(timeout=self.timeout)

    def run(self, func, *args, **kwargs):
        call = functools.partial(func, *args, **kwargs)
        return self._loop.run_in_executor(None, call)

It utilizes the existing lower level event loop API to provide an asynchronous context manager. I'd say the main advantage is that it's significantly more user friendly, as there's no loop or executor argument to be specified, and users can freely pass kwargs to run() thanks to functools.partial().

Additionally, I also included a timeout parameter for shutting down the ThreadPoolExecutor, which will depend upon #60564. This can be used as such:

async def main():
    async with asyncio.ThreadPool(timeout=600) as pool:
        fut1 = pool.run(func)
        fut2 = pool.run(func, arg1, arg2)
        fut2 = pool.run(func, arg1, kwarg1=True)
    print(await asyncio.gather(fut1, fut2, fut3))

asyncio.run(main())

I don't expect that this would be the final design, but I think it's a decent prototype to demonstrate the functionality. Thoughts?

[asvetlov]

run should be awaitable method, see bpo-38430