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
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 .SH NAME
libcurl-thread \- libcurl thread safety libcurl-thread \- libcurl thread safety
.SH "Multi-threading Issues" .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 \fBHandles.\fP You must \fBnever\fP share the same handle in multiple threads.
concurrently from multiple threads. If concurrent access to the same handle You can pass the handles around among threads, but you must never use a single
from multiple threads could be an issue then you must implement your own handle from more than one thread at any given time.
locking to ensure it won't happen.
Shared objects. You can share certain data between multiple handles by using \fBShared objects.\fP You can share certain data between multiple handles by
the share interface but you must implement your own locking and set using the share interface but you must provide your own locking and set
\fIcurl_share_setopt(3)\fP CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC. \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 \fBSSL/TLS handlers.\fP If you are accessing HTTPS or FTPS URLs in a
manner, you are then of course using the underlying SSL library multi-threaded multi-threaded manner, you are then of course using the underlying SSL library
and those libs might have their own requirements on this issue. You may need to multi-threaded and those libs might have their own requirements on this issue.
provide one or two functions to allow it to function properly: You may need to provide one or two functions to allow it to function properly:
.RS .RS
.IP OpenSSL .IP OpenSSL
@@ -69,30 +70,38 @@ provide one or two functions to allow it to function properly:
.IP Secure-Transport .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 .RE
Signals. Signals are used for timing out name resolves (during DNS lookup) - \fBSignals.\fP Signals are used for timing out name resolves (during DNS
when built without using either the c-ares or threaded resolver backends. When lookup) - when built without using either the c-ares or threaded resolver
using multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP option to 1 backends. When using multiple threads you should set the
for all handles. Everything will or might work fine except that timeouts are \fICURLOPT_NOSIGNAL(3)\fP option to 1 for all handles. Everything will or might
not honored during the DNS lookup - which you can work around by building work fine except that timeouts are not honored during the DNS lookup - which
libcurl with c-ares support. c-ares is a library that provides asynchronous you can work around by building libcurl with c-ares support. c-ares is a
name resolves. On some platforms, libcurl simply will not function properly library that provides asynchronous name resolves. On some platforms, libcurl
multi-threaded unless this option is set. simply will not function properly multi-threaded unless this option is set.
gethostby* functions and other system calls. These functions, provided by your \fBgethostby* functions and other system calls.\fP These functions, provided by
operating system, must be thread safe. It is very important that libcurl can your operating system, must be thread safe. It is very important that libcurl
find and use thread safe versions of these and other system calls, as otherwise can find and use thread safe versions of these and other system calls, as
it can't function fully thread safe. Some operating systems are known to have otherwise it can't function fully thread safe. Some operating systems are known
faulty thread implementations. We have previously received problem reports on to have faulty thread implementations. We have previously received problem
*BSD (at least in the past, they may be working fine these days). Some reports on *BSD (at least in the past, they may be working fine these days).
operating systems that are known to have solid and working thread support are Some operating systems that are known to have solid and working thread support
Linux, Solaris and Windows. are Linux, Solaris and Windows.
curl_global_* functions. These functions are not thread safe. If you are using \fBcurl_global_* functions.\fP These functions are not thread safe. If you are
libcurl with multiple threads it is especially important that before use you using libcurl with multiple threads it is especially important that before use
call \fIcurl_global_init(3)\fP to explicitly initialize the library and its 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 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 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. explanation refer to \fIlibcurl(3)\fP section \fBGLOBAL CONSTANTS\fP.