Commit 279965c9 authored by Jay Satiro's avatar Jay Satiro Committed by Daniel Stenberg
Browse files

libcurl-thread.3: Consolidate thread safety info 

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.
parent 7db03e5c

docs/libcurl/Makefile.am

+22 −20
Original line number Diff line number Diff line
@@ -29,18 +29,19 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ 
 curl_formadd.3 curl_formfree.3 curl_getdate.3 curl_getenv.3		 \

 curl_slist_append.3 curl_slist_free_all.3 curl_version.3		 \

 curl_version_info.3 curl_escape.3 curl_unescape.3 curl_free.3		 \

 curl_strequal.3 curl_mprintf.3 curl_global_init.3 curl_global_cleanup.3 \

 curl_multi_add_handle.3 curl_multi_cleanup.3 curl_multi_fdset.3	 \

 curl_multi_info_read.3 curl_multi_init.3 curl_multi_perform.3		 \

 curl_multi_remove_handle.3 curl_share_cleanup.3 curl_share_init.3	 \

 curl_share_setopt.3 libcurl.3 libcurl-easy.3 libcurl-multi.3		 \

 libcurl-share.3 libcurl-errors.3 curl_easy_strerror.3			 \

 curl_strequal.3 curl_mprintf.3 curl_global_init.3			 \

 curl_global_cleanup.3 curl_multi_add_handle.3 curl_multi_cleanup.3	 \

 curl_multi_fdset.3 curl_multi_info_read.3 curl_multi_init.3		 \

 curl_multi_perform.3 curl_multi_remove_handle.3 curl_share_cleanup.3	 \

 curl_share_init.3 curl_share_setopt.3 libcurl.3 libcurl-easy.3 	 \

 libcurl-multi.3 libcurl-share.3 libcurl-errors.3 curl_easy_strerror.3	 \

 curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3	 \

 libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3		 \

 curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3		 \

 curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3		 \

 curl_easy_pause.3 curl_easy_recv.3 curl_easy_send.3			 \

 curl_multi_socket_action.3 curl_multi_wait.3 libcurl-symbols.3

 curl_multi_socket_action.3 curl_multi_wait.3 libcurl-symbols.3 	 \

 libcurl-thread.3



HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html		\

 curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html	\
@@ -60,7 +61,8 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ 
 curl_easy_unescape.html curl_multi_setopt.html curl_multi_socket.html	\

 curl_multi_timeout.html curl_formget.html curl_multi_assign.html	\

 curl_easy_pause.html curl_easy_recv.html curl_easy_send.html		\

 curl_multi_socket_action.html curl_multi_wait.html libcurl-symbols.html

 curl_multi_socket_action.html curl_multi_wait.html			\

 libcurl-symbols.html libcurl-thread.html



PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf			 \

 curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf		 \
@@ -71,16 +73,16 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ 
 curl_mprintf.pdf curl_global_init.pdf curl_global_cleanup.pdf		 \

 curl_multi_add_handle.pdf curl_multi_cleanup.pdf curl_multi_fdset.pdf	 \

 curl_multi_info_read.pdf curl_multi_init.pdf curl_multi_perform.pdf	 \

 curl_multi_remove_handle.pdf curl_share_cleanup.pdf curl_share_init.pdf \

 curl_share_setopt.pdf libcurl.pdf libcurl-multi.pdf libcurl-easy.pdf	 \

 libcurl-share.pdf libcurl-errors.pdf curl_easy_strerror.pdf		 \

 curl_multi_strerror.pdf curl_share_strerror.pdf			 \

 curl_global_init_mem.pdf libcurl-tutorial.pdf curl_easy_reset.pdf	 \

 curl_easy_escape.pdf curl_easy_unescape.pdf curl_multi_setopt.pdf	 \

 curl_multi_socket.pdf curl_multi_timeout.pdf curl_formget.pdf		 \

 curl_multi_assign.pdf curl_easy_pause.pdf curl_easy_recv.pdf		 \

 curl_easy_send.pdf curl_multi_socket_action.pdf curl_multi_wait.pdf     \

 libcurl-symbols.pdf

 curl_multi_remove_handle.pdf curl_share_cleanup.pdf			 \

 curl_share_init.pdf curl_share_setopt.pdf libcurl.pdf			 \

 libcurl-multi.pdf libcurl-easy.pdf libcurl-share.pdf			 \

 libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf	 \

 curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf	 \

 curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf	 \

 curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf	 \

 curl_formget.pdf curl_multi_assign.pdf curl_easy_pause.pdf		 \

 curl_easy_recv.pdf curl_easy_send.pdf curl_multi_socket_action.pdf 	 \

 curl_multi_wait.pdf libcurl-symbols.pdf libcurl-thread.pdf



m4macrodir = $(datadir)/aclocal

dist_m4macro_DATA = libcurl.m4

docs/libcurl/index.html

+1 −0
Original line number Diff line number Diff line
@@ -17,6 +17,7 @@ 
<br><a href="libcurl-share.html">libcurl-share</a>

<br><a href="libcurl-errors.html">libcurl-errors</a>

<br><a href="libcurl-tutorial.html">libcurl-tutorial</a>

<br><a href="libcurl-thread.html">libcurl-thread</a>



<H2>Library Functions (A-Z)</H2>

<a href="curl_easy_cleanup.html">curl_easy_cleanup</A>

docs/libcurl/libcurl-thread.3

0 → 100644
+100 −0
Original line number Diff line number Diff line 
.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  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.

docs/libcurl/libcurl-tutorial.3

+2 −52
Original line number Diff line number Diff line
@@ -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

docs/libcurl/libcurl.3

+2 −7
Original line number Diff line number Diff line
@@ -111,13 +111,8 @@ libcurl works 
.B exactly

the same, on any of the platforms it compiles and builds on.

.SH "THREADS"

Never ever call curl-functions simultaneously using the same handle from

several threads. libcurl is thread-safe and can be used in any number of

threads, but you must use separate curl handles if you want to use libcurl in

more than one thread simultaneously.



The global environment functions are not thread-safe.  See \fBGLOBAL

CONSTANTS\fP below for details.

libcurl is thread safe but there are a few exceptions. Refer to

\fIlibcurl-thread(3)\fP for more information.



.SH "PERSISTENT CONNECTIONS"

Persistent connections means that libcurl can re-use the same connection for