generic-library/curl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

libcurl-thread.3: Revert to stricter handle wording

Browse Source 
.. also update formatting and add WinSSL and wolfSSL to the SSL/TLS
handlers list.
This commit is contained in:
Jay Satiro 2015-07-18 03:09:16 -04:00 committed by Daniel Stenberg
parent 279965c923
commit 299b74fcfc
1 changed files with 40 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
docs/libcurl/libcurl-thread.3
View File

@ -24,21 +24,22 @@
.SH NAME
libcurl-thread \- libcurl thread safety
.SH "Multi-threading Issues"
libcurl is thread safe with the following exceptions:
libcurl is thread safe but has no internal thread synchronization. You may have
to provide your own locking should you meet any of the thread safety exceptions
below.
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.
\fBHandles.\fP You must \fBnever\fP share the same handle in multiple threads.
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.
Shared objects. You can share certain data between multiple handles by using
the share interface but you must implement your own locking and set
\fBShared objects.\fP You can share certain data between multiple handles by
using the share interface but you must provide 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:
\fBSSL/TLS handlers.\fP 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
@ -69,30 +70,38 @@ provide one or two functions to allow it to function properly:
.IP Secure-Transport
The engine is fully thread-safe, and no additional steps are required.
The engine is used by libcurl in a way that is fully thread-safe.
.IP WinSSL
The engine is used by libcurl in a way that is fully thread-safe.
.IP wolfSSL
The engine is used by libcurl in a way that is fully thread-safe.
.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.
\fBSignals.\fP 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.
\fBgethostby* functions and other system calls.\fP 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
\fBcurl_global_* functions.\fP 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.