romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-08-26 17:03:32 +03:00
Code Issues Projects Releases Packages Wiki Activity

libcurl-thread.3: Consolidate thread safety info

Browse source 
This is a new document to consolidate our thread safety information from
several documents (curl-www:features, libcurl.3, libcurl-tutorial.3).
Each document's section on multi-threading will now point to this one.
This commit is contained in:
Jay Satiro 2015-07-13 16:15:55 -04:00 • committed by Daniel Stenberg
parent 7db03e5c21
commit 279965c923
5 changed files with 127 additions and 79 deletions
Download patch file Download diff file Expand all files Collapse all files

54
docs/libcurl/libcurl-tutorial.3
View file

@ -256,58 +256,8 @@ complication for you. Given simply the URL to a file, libcurl will take care
of all the details needed to get the file moved from one machine to another.
.SH "Multi-threading Issues"
The first basic rule is that you must \fBnever\fP simultaneously share a
libcurl handle (be it easy or multi or whatever) between multiple
threads. Only use one handle in one thread at any time. 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.
libcurl is completely thread safe, except for two issues: signals and SSL/TLS
handlers. Signals are used for timing out name resolves (during DNS lookup) -
when built without using either the c-ares or threaded resolver backends.
If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are
then of course using the underlying SSL library multi-threaded and those libs
might have their own requirements on this issue. Basically, you need to
provide one or two functions to allow it to function properly. For all
details, see this:
OpenSSL
http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION
GnuTLS
http://gnutls.org/manual/html_node/Thread-safety.html
NSS
is claimed to be thread-safe already without anything required.
PolarSSL
Required actions unknown.
yassl
Required actions unknown.
axTLS
Required actions unknown.
Secure Transport
The engine is fully thread-safe, and no additional steps are required.
When using multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP
option to 1 for all handles. Everything will or might work fine except that
timeouts are not honored during the DNS lookup - which you can work around by
building libcurl with c-ares support. c-ares is a library that provides
asynchronous name resolves. On some platforms, libcurl simply will not
function properly multi-threaded unless this option is set.
Also, note that \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP is not thread-safe.
libcurl is thread safe but there are a few exceptions. Refer to
\fIlibcurl-thread(3)\fP for more information.
.SH "When It Doesn't Work"
There will always be times when the transfer fails for some reason. You might