add doc to explain multithreading

[jokester]

Warning for interested

This PR likely requires major change before merged, if it ever will. The patterns mentioned should mostly work for current Streamlit, but the official team has the decide to how to introduce them.

📚 Context

Surprising many people are confused by multithreading in Streamlit, like in #87 / streamlit/streamlit#1326 / streamlit/streamlit#8490 .

This PR tries to explain the underneath Streamlit-specific things, and provide multithreading patterns to start with.

🧠 Description of Changes

• Add a page to explain Streamlit-created and user-created threads, and how to use them together.

Revised:

see the new file

Current:

(I didn't find document explaining threads and ScriptRunContext, except in the code)

💥 Impact

Size:

• Small
• Not small

🌐 References

• Add documentation about how to use Streamlit with multiple threads. #87
• Improve "missing ReportContext" threading error streamlit#1326
• Add support for multi-threading/multi-processing in Streamlit streamlit#8490

Contribution License Agreement

By submitting this pull request you agree that all contributions to this project are made under the Apache 2.0 license.

[jokester]

I'm happy to hear feedback about content or format 🙏

[jokester]

CI fails but I can't find the error message. The links like https://app.netlify.com/sites/streamlit-docs/deploys/66eaa4a1b1871d000843e854 only says "A fatal rendering error has occurred"

[sfc-gh-dmatthews]

Hi @jokester. Thanks for contributing. The site won't build and the page won't be viewable without correctly updating site navigation. Check out the readme file for docs, specifically Add pages to the menu.

I'm going over items for the next release right now, so it might take me a few weeks to look at this more closely. Multithreading has been on my list for a while, so thanks for taking a stab at it. I'll circle back here when I get the next release fleshed out. 😄

[jokester]

Though I saw people are already going this way (in various GH issues), I'm not really sure about this pattern

1. it exposes internal object to page writers

2. it is less guaranteed. I don't know enough to say the probability where a ScriptRunContext suffices. The other pattern just looks "safer" to me because it assumes less from Streamlit.

[sfc-gh-dmatthews]

Officially, adding your own threads isn't supported. We don't want to include unsupported patterns in the main concepts area. This will likely go out as a Knowledge Base (KB) article. There is a subset of this information that can live in concepts, but it will need to be very carefully separated. For now, we can move this page to the KB so that we can get it published faster and I'll likely follow up with moving some of it back into concepts. (I still haven't read through any of it yet, so I still expect a few weeks before I get to this. Just a heads up about what will likely happen.)

In the longer run, the plan is to properly support multithreading and async tasks, but that work isn't currently on the schedule this quarter or next, so it wouldn't likely happen until next year at the earliest.

[jokester]

That makes sense. I don't really want to promote the hack either.

When you come back, feel free to change or move things or ask me to do so 👍🏽

[jokester]

@sfc-gh-dmatthews Thanks !! I managed to get preview build to work https://deploy-preview-1154--streamlit-docs.netlify.app/develop/concepts/architecture/threading

[sfc-gh-dmatthews]

Sorry for the delay. I've been working on this this week. I think instead of the pseudo code to explain the threading structure, an illustration might be better. I have a much more detailed illustration I want to put into a contributing wiki-type document, but for this guide, I want to make sure it's as accessible to Python developers as possible (who might not ever touch a Tornado server to deal with WebSockets). I'm currently thinking of something like this to just schematically show script threads tied to script runs and that they have to communicate both to the front end and the server.

I should have the PR updated with a first pass by early next week. 😄