bpo-32309: Implement asyncio.to_thread()

[aeros]

Implements asyncio.to_thread, a coroutine for asynchronously running IO-bound functions in a separate thread without blocking the event loop. See the discussion starting from here in GH-18410 for context.

https://bugs.python.org/issue32309

Automerge-Triggered-By: @aeros

[aeros]

/cc @1st1

[1st1]

This looks great to me. Please don't merge before @asvetlov and @cjerdonek approve.

[tmewett]

Is the name finalised? I saw the discussion about run_in_thread being a bit ambiguous but personally I don't think to_thread is very clear either.

I would suggest create_thread. Then, this would match up almost exactly with the semantics of asyncio.create_task

create_task: Wrap the coroutine into a Task and schedule its execution. Return the Task object.

create_thread: Wrap the function in a thread and start its execution. Return a future object.

If you see what I mean? The functions are very similar but one is for coros concurrently in the event loop and the other is for functions concurrently in threads.

[cjerdonek]

Thanks. @tmewett I think the proposed name is good enough. Re: create_thread(), I think it has the issue that when backed by a pool, it's not necessarily creating a new thread. With to_thread(), you can think of it as "going to" a thread in the pool.

[asvetlov]

I have a little doubt for the documentation text; the code itself and test are fine.

[1st1]

@aeros Looks like everybody approves this so you can go ahead and merge!

Next todo:

• Implement asyncio.from_thread
• Implement auto-scaling of the default thread pool.

[aeros]

@aeros Looks like everybody approves this so you can go ahead and merge!

Awesome, thanks for the reviews @1st1, @cjerdonek, and @asvetlov!

I'll discuss the documentation a bit more w/ Andrew regarding the examples, and then proceed w/ merging it.

[aeros]

Thanks for the review as well @methane. :-)

[aeros]

Status check is done, and it's a failure x .

This occurred from a minor doctest warning, apparently having tildes in the code comments of example code is flagged as "suspicious". The latest commit should address it.

[miss-islington]

@aeros: Status check is done, and it's a success ✅ .

[zware]

Note that this missed the 3.9 boat; it's now merged into 3.10. The whatsnew entry should be moved accordingly :)

(The documentation needs the appropriate .. versionadded: 3.10 marker, as well.)

[aeros]

Note that this missed the 3.9 boat; it's now merged into 3.10. The whatsnew entry should be moved accordingly :)

Currently, I'm reaching out to Łukasz to see if we could consider including this in 3.9b2 since it was so close to the deadline (it's been a WIP since last year and would have otherwise made it on-time, if not for some last minute changes). If he decides that it's too late, I'll update the whatsnew entry.

(I'll also add the versionadded marker as well, good catch.)

[miss-islington]

Thanks @aeros for the PR 🌮🎉.. I'm working now to backport this PR to: 3.9.
🐍🍒⛏🤖

[bedevere-bot]

GH-20212 is a backport of this pull request to the 3.9 branch.

[aeros]

Thanks, @ambv!

I'll try to open a PR to add the versionadded to the docs in the next couple of days, as @zware mentioned earlier.