mirror of https://github.com/moparisthebest/curl
101 lines
4.1 KiB
Groff
101 lines
4.1 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * 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.
|