docs: add a section about thread safety

3 files changed, 44 insertions, 0 deletions

diff --git a/docs/reference/client-thread-safety.md b/docs/reference/client-thread-safety.md
new file mode 100644
index 00000000..f75eddb2
--- /dev/null
+++ b/docs/reference/client-thread-safety.md
@@ -0,0 +1,42 @@
+Title: Client thread safety
+Slug: client-thread-safety
+
+# Client thread safety
+
+libsoup is not fully thread safe, but since version 3.2 it's possible
+to send messages from any thread. The recommended and most efficient
+way to use libsoup is using only the async API from a single thread,
+even when it feels natural to use the sync API from a worker
+thread. While there's not much difference in HTTP/1, in the case of
+HTTP/2, two messages for the same host sent from different threads
+will not use the same connection, so the advantage of HTTP/2
+multiplexing is lost.
+
+There are a few important things to consider when using multiple
+threads:
+
+ - Only the API to send messages can be called concurrently from
+   multiple threads. So, in case of using multiple threads, you must
+   configure the session (setting network properties, features, etc.)
+   from the thread it was created and before any request is made.
+
+ - All signals associated to a message
+   ([signal@Session::request-queued],
+   [signal@Session::request-unqueued], and all Message signals) are
+   emitted from the thread that started the request, and all the IO will
+   happen there too.
+
+ - The session can be created in any thread, but all session APIs
+   except the methods to send messages must be called from the thread
+   where the session was created.
+
+ - To use the async API from a thread different than the one where the
+   session was created, the thread must have a thread default main
+   context where the async callbacks are dispatched.
+
+ - The sync API doesn't need any main context at all.
+
+ - All internal session features are thread safe. Any third party
+   feature must be thread safe too in order to work with multiple
+   threads.
+
diff --git a/docs/reference/libsoup.toml.in b/docs/reference/libsoup.toml.in
index f3a8c2e7..0a918ef9 100644
--- a/docs/reference/libsoup.toml.in
+++ b/docs/reference/libsoup.toml.in
@@ -40,6 +40,7 @@ content_files = [
   "build-howto.md",
   'client-basic.md',
   'client-advanced.md',
+  'client-thread-safety.md',
   'client-tls.md',
   'server-howto.md',
   "migrating-from-libsoup-2.md",
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 92710260..4e6da37b 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -2,6 +2,7 @@ expand_content_md_files = [
     'build-howto.md',
     'client-basic.md',
     'client-advanced.md',
+    'client-thread-safety.md',
     'client-tls.md',
     'server-howto.md',
     'migrating-from-libsoup-2.md',