Better usability for threads

[njsmith]

I was ok with run_sync_in_worker_thread having a slightly-awkward name because threads are going to make your life awkward so, you know, it's fair warning. But when you're stuck using threads to hack around missing trio libraries, it can feel like a bit of extra punishment on top, which is not so nice.

Maybe we should rename it to run_sync_in_thread?

[njsmith]

Well, that seems popular.

Related idea: the whole "portal" design seems a bit more awkward than I was anticipating. I was imagining that threads were a mostly-for-experts kind of thing, and "foreign" threads would be as common as trio-spawned threads, but I feel like maybe it's not turning out that way.

Alternative idea (inspired by curio and anyio): provide a standard way to re-enter trio from a trio thread. Basically stash the token in thread-local storage, and then use it.

One possible API:

trio.run_from_thread(async_fn, *args, *, token=None)
trio.run_sync_from_thread(fn, *args, *, token=None)
trio.sync_cm_from_thread(cm, *, token=None)
trio.async_cm_from_thread(cm, *, token=None)

trio.run_sync_in_thread(fn, *args, *, ...)
trio.sync_cm_in_thread(cm, *, ...)

So the general idea is that from_thread is for going thread->trio, and in_thread is for going trio->thread. (It's taken for granted that one end is trio, because of course trio is the center of the universe. Also it's in the name of the functions.)

This pattern might be used for other projects too, like trio-asyncio – run_in_aio, run_from_aio. trio-asyncio has really struggled with making these names easy to understand – @smurfix, do you think this would do any better?

Alternatively, we could group these into a namespace, like:

trio.from_thread.run(...)
trio.from_thread.run_sync(...)
trio.from_thread.sync_cm(...)
trio.from_thread.async_cm(...)

trio.in_thread.run_sync(...)
trio.in_thread.sync_cm(...)

This would group related functions together for tab-completion, and avoid "polluting" the main trio namespace. OTOH it looks a bit weird, and flat is better than nested...

Another alternative, or complement: we could do async with trio.in_thread: .../async with trio.from_thread – see python-trio/trio-asyncio#42 for a discussion of why this is nice – in particular it automatically works for context managers.

See also: #680 for context managers across threads, #606 for propagating cancellation across trio->thread->trio transitions, and #648 for preserving contextvars across thread switches

[smurfix]

trio.from_thread.async_cm(...)
trio.in_thread.run_sync(...)

The opposite of "from" is "to", so to_thread.* would work for me. in_thread is confusing because I read that as "I'm supposed to call these in a thread".

[njsmith]

Another possible approach:

trio.run_sync_in_thread(...)

trio.threadsafe.check_cancelled()
trio.threadsafe.run_in_trio(...)
trio.threadsafe.run_sync_in_trio(...)
trio.threadsafe.async_cm(...)

The idea is that in a thread, you're only allowed to use threadsafe functions (which makes the safety rules very easy to document!), and otherwise it uses the same naming conventions as regular trio.

[njsmith]

Another reason to reconsider the BlockingTrioPortal API: it's not currently compatible with having a global deadlock detector (#1085).

[njsmith]

I guess a downside to trio.threadsafe is that it suggests that they're safe to call anywhere, but we probably don't want allow them to be called from inside the trio thread itself.

I think these are unambiguous and fairly terse:

# These are the ones that are safe to use from a thread
trio.from_thread.run(...)
trio.from_thread.run_sync(...)
trio.from_thread.cm(...)
trio.from_thread.async_cm(...)
trio.from_thread.check_cancel()

# These are what you use from Trio
trio.to_thread.run_sync(...)
trio.to_thread.cm(...)

Alternative bikeshed color no. 1:

trio.to_trio.run(...)
trio.to_trio.run_sync(...)
trio.to_trio.cm(...)
trio.to_trio.async_cm(...)
trio.to_trio.check_cancel()

trio.to_thread.run_sync(...)
trio.to_thread.cm(...)

Alternative bikeshed color no. 2:

trio.trioify.run(...)
trio.trioify.run_sync(...)
trio.trioify.cm(...)
trio.trioify.async_cm(...)
trio.trioify.check_cancel()

trio.threadify.run_sync(...)
trio.threadify.cm(...)

Alternative bikeshed no. 3:

trio.as_trio.run(...)
trio.as_trio.run_sync(...)
trio.as_trio.cm(...)
trio.as_trio.async_cm(...)
trio.as_trio.check_cancel()

trio.as_thread.run_sync(...)
trio.as_thread.cm(...)

Alternative bikeshed no. I lost count:

# These are the ones that are safe to use from a thread
trio.from_thread.run(...)
trio.from_thread.run_sync(...)
trio.from_thread.cm(...)
trio.from_thread.async_cm(...)
trio.from_thread.check_cancel()

# These are what you use from Trio
trio.use_thread.run_sync(...)
trio.use_thread.cm(...)

Hmm. I think I prefer the "from thread" style over the "to trio" style, because if you're starting in asyncio or something then you need a different way to get "to trio". These are specifically: to trio from a thread that's running synchronous, blocking code. Which "from thread" doesn't exactly say, but if you had from_asyncio and from_thread next to each other then I think it would be pretty clear what each one meant, while if you had to_trio_from_asyncio and to_trio next to each other then it would just be confusing.

OTOH, trio.to_thread is OK because like, obviously you are starting from Trio. You don't use trio.to_thread to get from asyncio to a worker thread.

There's still the use_thread vs to_thread. Doesn't seem like a huge difference, and I guess to is shorter and more parallel, so maybe we'll just go with to. I'm pleased at how trio.run_sync_in_thread and trio.to_thread.run_sync have the same number of characters, and mostly the same characters at that.

The context manager terminology is a bit confusing:

• For run/run_sync, the default is async, but for cm/async_cm, the default is sync
• For trio.use_thread.cm, you give it a sync context manager and it returns an async context manager

Maybe it's better to explicitly use sync_cm & async_cm? I doubt there's any perfect answer here, because we're not going to rename trio.run to trio.run_async, and the larger Python community is never going to rename context manager → sync context manager, async context manager → context manager, so some inconsistency is unavoidable.

For the unusual case where someone wants to get into Trio from a thread that wasn't started by Trio: one option would be to have an object that implements the same stuff as from_thread. But another interesting possibility would be to lean into the thread-local idea – Trio threads get some kind of "entry handle" stashed in a thread-local by default, or, if you have an "entry handle" object, you could temporarily stash it in the thread-local by doing something like:

with entry_handle.register_thread():
    trio.from_thread.run(...)

Possibly this should automatically close the handle at the end?

I guess there's an argument for using a ContextVar instead of a thread-local. Imagine two trio threads talking to each other. Within a single trio thread, two different branches of the task tree might each want their own entry handles, maybe? Seems obscure but using a ContextVar is probably just as easy and fast as a thread-local, so why not.

[njsmith]

Maybe #1099 was a mistake though... if we're going to settle on trio.to_thread.run_sync as the final name, then asking everyone to make a detour through run_sync_in_thread is silly.

[pquentin]

(Note that it's cheap to change #1099 before the next release.)