diff options
| -rw-r--r-- | docs/reference/client-thread-safety.md | 42 | ||||
| -rw-r--r-- | docs/reference/libsoup.toml.in | 1 | ||||
| -rw-r--r-- | docs/reference/meson.build | 1 |
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', |