Artifactspublic-v0

curl

master
ply4 git calls42 ms289 KiB3 cachedprotocol v2
127 lines4.9 KiBRaw

NAME

libcurl-thread - libcurl thread-safety

Multi-threading with libcurl

libcurl is thread-safe but has no internal thread synchronization. You may have to provide your own locking should you meet any of the thread-safety exceptions below.

Handles

You must never share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time.

Shared objects

You can share certain data between multiple handles by using the share interface but you must provide your own locking and set curl_share_setopt(3) CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC.

Note that some items are specifically documented as not thread-safe in the share API (the connection pool and HSTS cache for example).

TLS

All current TLS libraries libcurl supports are thread-safe.

OpenSSL

OpenSSL 1.1.0+ can be safely used in multi-threaded applications provided that support for the underlying OS threading API is built-in. For older versions of OpenSSL, the user must set mutex callbacks.

libcurl may not be able to fully clean up after multi-threaded OpenSSL depending on how OpenSSL was built and loaded as a library. It is possible in some rare circumstances a memory leak could occur unless you implement your own OpenSSL thread cleanup.

For example, on Windows if both libcurl and OpenSSL are linked statically to a DLL or application then OpenSSL may leak memory unless the DLL or application calls OPENSSL_thread_stop() before each thread terminates. If OpenSSL is built as a DLL then it does this cleanup automatically and there is no leak. If libcurl is built as a DLL and OpenSSL is linked statically to it then libcurl does this cleanup automatically and there is no leak (added in libcurl 8.8.0).

Please review the OpenSSL documentation for a full list of circumstances: https://docs.openssl.org/3.0/man3/OPENSSL_init_crypto/#notes

mbedTLS

mbedTLS can be used safely in a multi-threaded environment provided that mbedTLS is compiled with MBEDTLS_THREADING_C enabled.

https://mbed-tls.readthedocs.io/en/latest/kb/development/thread-safety-and-multi-threading

Signals

Signals are used for timing out name resolves (during DNS lookup) - when built without using either the c-ares or threaded resolver backends. On systems that have a signal concept.

When using multiple threads you should set the CURLOPT_NOSIGNAL(3) option to 1L for all handles. Everything works fine except that timeouts cannot be honored during DNS lookups - which you can work around by building libcurl with c-ares or threaded-resolver support. c-ares is a library that provides asynchronous name resolves. On some platforms, libcurl cannot function properly multi-threaded unless the CURLOPT_NOSIGNAL(3) option is set.

When CURLOPT_NOSIGNAL(3) is set to 1L, your application needs to deal with the risk of a SIGPIPE (that at least the OpenSSL backend can trigger). Note that setting CURLOPT_NOSIGNAL(3) to 0L does not work in a threaded situation as there is a race condition where libcurl risks restoring the former signal handler while another thread should still ignore it.

Name resolving

The gethostbyname or getaddrinfo and other name resolving system calls used by libcurl are provided by your operating system and must be thread-safe. It is important that libcurl can find and use thread-safe versions of these and other system calls, as otherwise it cannot function fully thread-safe. Some operating systems are known to have faulty thread implementations. We have previously received problem reports on *BSD (at least in the past, they may be working fine these days). Some operating systems that are known to have solid and working thread support are Linux, Solaris and Windows.

curl_global_* functions

These functions are thread-safe since libcurl 7.84.0 if curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set (most platforms).

If these functions are not thread-safe and you are using libcurl with multiple threads it is especially important that before use you call curl_global_init(3) or curl_global_init_mem(3) to explicitly initialize the library and its dependents, rather than rely on the "lazy" fail-safe initialization that takes place the first time curl_easy_init(3) is called. For an in-depth explanation refer to libcurl(3) section GLOBAL CONSTANTS.

Memory functions

These functions, provided either by your operating system or your own replacements, must be thread-safe. You can use curl_global_init_mem(3) to set your own replacement memory functions.

Non-safe functions

CURLOPT_DNS_USE_GLOBAL_CACHE(3) is not thread-safe.

curl_version_info(3) is not thread-safe before libcurl initialization.

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: libcurl-thread
5Section: 3
6Source: libcurl
7See-also:
8 - libcurl-security (3)
9Protocol:
10 - All
11Added-in: n/a
12---
14# NAME
16libcurl-thread - libcurl thread-safety
18# Multi-threading with libcurl
20libcurl is thread-safe but has no internal thread synchronization. You may have
21to provide your own locking should you meet any of the thread-safety exceptions
22below.
24# Handles
26You must **never** share the same handle in multiple threads. You can pass the
27handles around among threads, but you must never use a single handle from more
28than one thread at any given time.
30# Shared objects
32You can share certain data between multiple handles by using the share
33interface but you must provide your own locking and set
34curl_share_setopt(3) CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC.
36Note that some items are specifically documented as not thread-safe in the
37share API (the connection pool and HSTS cache for example).
39# TLS
41All current TLS libraries libcurl supports are thread-safe.
43## OpenSSL
45OpenSSL 1.1.0+ can be safely used in multi-threaded applications provided that
46support for the underlying OS threading API is built-in. For older versions of
47OpenSSL, the user must set mutex callbacks.
49libcurl may not be able to fully clean up after multi-threaded OpenSSL
50depending on how OpenSSL was built and loaded as a library. It is possible in
51some rare circumstances a memory leak could occur unless you implement your own
52OpenSSL thread cleanup.
54For example, on Windows if both libcurl and OpenSSL are linked statically to a
55DLL or application then OpenSSL may leak memory unless the DLL or application
56calls OPENSSL_thread_stop() before each thread terminates. If OpenSSL is built
57as a DLL then it does this cleanup automatically and there is no leak. If
58libcurl is built as a DLL and OpenSSL is linked statically to it then libcurl
59does this cleanup automatically and there is no leak (added in libcurl 8.8.0).
61Please review the OpenSSL documentation for a full list of circumstances:
62https://docs.openssl.org/3.0/man3/OPENSSL_init_crypto/#notes
64## mbedTLS
66mbedTLS can be used safely in a multi-threaded environment provided that mbedTLS is
67compiled with MBEDTLS_THREADING_C enabled.
69https://mbed-tls.readthedocs.io/en/latest/kb/development/thread-safety-and-multi-threading
71# Signals
73Signals are used for timing out name resolves (during DNS lookup) - when built
74without using either the c-ares or threaded resolver backends. On systems that
75have a signal concept.
77When using multiple threads you should set the CURLOPT_NOSIGNAL(3)
78option to 1L for all handles. Everything works fine except that timeouts
79cannot be honored during DNS lookups - which you can work around by building
80libcurl with c-ares or threaded-resolver support. c-ares is a library that
81provides asynchronous name resolves. On some platforms, libcurl cannot
82function properly multi-threaded unless the CURLOPT_NOSIGNAL(3) option
83is set.
85When CURLOPT_NOSIGNAL(3) is set to 1L, your application needs to deal
86with the risk of a SIGPIPE (that at least the OpenSSL backend can
87trigger). Note that setting CURLOPT_NOSIGNAL(3) to 0L does not work in a
88threaded situation as there is a race condition where libcurl risks restoring
89the former signal handler while another thread should still ignore it.
91# Name resolving
93The **gethostbyname** or **getaddrinfo** and other name resolving system
94calls used by libcurl are provided by your operating system and must be
95thread-safe. It is important that libcurl can find and use thread-safe versions
96of these and other system calls, as otherwise it cannot function fully
97thread-safe. Some operating systems are known to have faulty thread
98implementations. We have previously received problem reports on *BSD (at least
99in the past, they may be working fine these days). Some operating systems that
100are known to have solid and working thread support are Linux, Solaris and
101Windows.
103# curl_global_* functions
105These functions are thread-safe since libcurl 7.84.0 if
106curl_version_info(3) has the **CURL_VERSION_THREADSAFE** feature bit
107set (most platforms).
109If these functions are not thread-safe and you are using libcurl with multiple
110threads it is especially important that before use you call
111curl_global_init(3) or curl_global_init_mem(3) to explicitly
112initialize the library and its dependents, rather than rely on the "lazy"
113fail-safe initialization that takes place the first time
114curl_easy_init(3) is called. For an in-depth explanation refer to
115libcurl(3) section **GLOBAL CONSTANTS**.
117# Memory functions
119These functions, provided either by your operating system or your own
120replacements, must be thread-safe. You can use curl_global_init_mem(3)
121to set your own replacement memory functions.
123# Non-safe functions
125CURLOPT_DNS_USE_GLOBAL_CACHE(3) is not thread-safe.
127curl_version_info(3) is not thread-safe before libcurl initialization.
Diagnostics4 git calls · 42 ms
CallStatusSizeTime042 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=2
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=38
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.3 KiB · hit38 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2319
git.response.cache=HIT
git.response.duration_ms=38
git.fetch.wants=9b26224ce6e64a6adb5cc9576fd04cf73e200370
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2319
git.pkt.payload.max=2298
git.sideband.band1.bytes=2297
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e309903e90ee28
Request
815552c6…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format