Python Trio and thread safety.

Help and advice
1

Unfortunately, after looking at the Python Trio documentation, it is not clear to me, which items in the Trio API are thread safe.

I know the documentation says “The vast majority of Trio’s API is not thread safe”.
The documentation also shows examples of using Trio Memory channels and Context Variables with threads.

However, in the actual trio.open_memory_channel detail section, for example, it refers to “tasks within a process”.
I tend to understand tasks being associated with async operation vs threads. Although “a process” might mean that the definition of task is widened to include threads?
(“Task Object… A Future-like object that runs a Python coroutine. Not thread-safe.” See [Coroutines and Tasks — Python 3.11.2 documentation)]

So, the Trio Documentation doesn’t seem explicit as which of Trio’s API is thread safe, some seem implied, like this one.

  1. So, I wonder what other Trio API elements are thread safe?
    1a. Is there a list of them?

The documentation also says “Personally, I find that events and channels are usually enough to implement most things I care about…”

  1. So I wonder in particular, if trio.Event is also thread safe?
  2. If trio.Event is thread safe, then an example of its use would be helpful to ensure I have the correct paradigm.

Thanks.

2

Heya! Sorry I missed your message in the moderation queue.

Trio memory channels aren’t thread-safe – where did you see otherwise? trio.Event is also not thread-safe. Basically the only things that are thread-safe are the ones where the reference docs have some explicit statement like “This is thread-safe”.

However, trio.from_thread is thread-safe, and you can use it from a thread to access Trio APIs that are normally not thread-safe, e.g.:

# Equivalent to `await some_event.wait()`, but from a thread
trio.from_thread.run(some_event.wait)
3

NB Sorry for the tardiness of my reply to your helpful message, but a family member has developed a serious illness.

I have incorrectly inferred the thread-safety for Trio memory channels from the documentation examples that feature thread interaction. (Trio’s core functionality — Trio 0.21.0+dev documentation).
Whereas, it is only thread-safe because of trio.to_thread.run_sync(), trio.from_thread.run() and trio.from_thread.run_sync() functions?!

Some parts of the Trio documentation are reasonably clear regarding thread-safety, like the actual function specification:
trio.lowlevel.start_thread_soon(fn, deliver)
says “It is safe to call this function simultaneously from multiple threads.”

Whereas trio.from_thread.run in its reference documentation, doesn’t explicitly say so! So, I start to infer and maybe incorrectly.

I personally don’t find the documentation clear regarding thread-safety, as explicit statements regarding thread-safety appear to me to be missing, especially from the function reference. I think if possible, a uniform method of marking function thread safe from a Trio point of view in the documentation would be great. Alternatively, a list of them would also be great. Until that time I will use trio.to_thread and sister trio.from_thread functions, so that I can safely incorporate non-async, legacy :slight_smile: APIs.

Thanks