Document how to resize the threadpool (#2881)

diff --git a/docs/threadpool.md b/docs/threadpool.md
new file mode 100644 (file)
index 0000000..eec3677
--- /dev/null
+++ b/docs/threadpool.md
@@ -0,0 +1,24 @@
+# Thread Pool
+
+When you're using `def` instead of `async def`, Starlette will run your code in a thread pool to avoid
+blocking the event loop. This applies for endpoint functions and background tasks you create, but also
+for internal Starlette code.
+
+To be more precise, Starlette uses `anyio.to_thread.run_sync` to run the synchronous code.
+
+## Limitation
+
+The default thread pool size is only 40 _tokens_. This means that only 40 threads can run at the same time.
+
+If you need to run more threads, you can increase the number of _tokens_:
+
+```py
+import anyio.to_thread
+
+limiter = anyio.to_thread.current_default_thread_limiter()
+limiter.total_tokens = 100
+```
+
+The above code will increase the number of _tokens_ to 100.
+
+Increasing the number of threads may have a performance and memory impact, so be careful when doing so.

diff --git a/mkdocs.yml b/mkdocs.yml
index 02aae146e0871cdae52c8d01b14788b3ba0e074a..6cf43e1ee4eadb6bd4a8fa511608fff7f414eac3 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -48,6 +48,7 @@ nav:
       - Server Push: "server-push.md"
       - Exceptions: "exceptions.md"
       - Configuration: "config.md"
+      - Thread Pool: "threadpool.md"
       - Test Client: "testclient.md"
   - Release Notes: "release-notes.md"
   - Community: