diff options
Diffstat (limited to 'docs/libcurl/libcurl-thread.3')
| -rw-r--r-- | docs/libcurl/libcurl-thread.3 | 100 |
1 files changed, 100 insertions, 0 deletions
diff --git a/docs/libcurl/libcurl-thread.3 b/docs/libcurl/libcurl-thread.3 new file mode 100644 index 000000000..155e4e34c --- /dev/null +++ b/docs/libcurl/libcurl-thread.3 @@ -0,0 +1,100 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 2015, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH libcurl-thread 3 "13 Jul 2015" "libcurl" "libcurl thread safety" +.SH NAME +libcurl-thread \- libcurl thread safety +.SH "Multi-threading Issues" +libcurl is thread safe with the following exceptions: + +Do \fBNOT\fP use library functions to access or modify the same handle +concurrently from multiple threads. If concurrent access to the same handle +from multiple threads could be an issue then you must implement your own +locking to ensure it won't happen. + +Shared objects. You can share certain data between multiple handles by using +the share interface but you must implement your own locking and set +\fIcurl_share_setopt(3)\fP CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC. + +SSL/TLS handlers. 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. You may need to +provide one or two functions to allow it to function properly: + +.RS +.IP OpenSSL + + http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION + + http://curl.haxx.se/libcurl/c/opensslthreadlock.html + +.IP GnuTLS + + http://gnutls.org/manual/html_node/Thread-safety.html + +.IP NSS + + is claimed to be thread-safe already without anything required. + +.IP PolarSSL + + Required actions unknown. + +.IP yassl + + Required actions unknown. + +.IP axTLS + + Required actions unknown. + +.IP Secure-Transport + + The engine is fully thread-safe, and no additional steps are required. +.RE + +Signals. Signals are used for timing out name resolves (during DNS lookup) - +when built without using either the c-ares or threaded resolver backends. 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. + +gethostby* functions and other system calls. These functions, provided by your +operating system, must be thread safe. It is very important that libcurl can +find and use thread safe versions of these and other system calls, as otherwise +it can't 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 not thread safe. If you are using +libcurl with multiple threads it is especially important that before use you +call \fIcurl_global_init(3)\fP to explicitly initialize the library and its +dependents, rather than rely on the "lazy" fail-safe initialization that takes +place the first time \fIcurl_easy_init(3)\fP is called. For an in-depth +explanation refer to \fIlibcurl(3)\fP section \fBGLOBAL CONSTANTS\fP. + +\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP is not thread-safe. |