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.

5 files changed, 127 insertions, 79 deletions

diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am
index 39272ac4f..5456ee418 100644
--- a/docs/libcurl/Makefile.am
+++ b/docs/libcurl/Makefile.am
@@ -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,27 +61,28 @@ 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		 \
  curl_easy_duphandle.pdf curl_formadd.pdf curl_formfree.pdf		 \
- curl_getdate.pdf curl_getenv.pdf curl_slist_append.pdf			 \
- curl_slist_free_all.pdf curl_version.pdf curl_version_info.pdf		 \
+ curl_getdate.pdf curl_getenv.pdf curl_slist_append.pdf 		 \
+ curl_slist_free_all.pdf curl_version.pdf curl_version_info.pdf 	 \
  curl_escape.pdf curl_unescape.pdf curl_free.pdf curl_strequal.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
diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html
index ca773135b..f46cc85f7 100644
--- a/docs/libcurl/index.html
+++ b/docs/libcurl/index.html
@@ -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>
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.
diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3
index 11b019011..2563a881f 100644
--- a/docs/libcurl/libcurl-tutorial.3
+++ b/docs/libcurl/libcurl-tutorial.3
@@ -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
diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3
index 39bcccd43..dbd91bc33 100644
--- a/docs/libcurl/libcurl.3
+++ b/docs/libcurl/libcurl.3
@@ -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