From 299b74fcfc5eed751da1174c06d17f5b57b61e5f Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Sat, 18 Jul 2015 03:09:16 -0400 Subject: libcurl-thread.3: Revert to stricter handle wording .. also update formatting and add WinSSL and wolfSSL to the SSL/TLS handlers list. --- docs/libcurl/libcurl-thread.3 | 75 ++++++++++++++++++++++++------------------- 1 file changed, 42 insertions(+), 33 deletions(-) diff --git a/docs/libcurl/libcurl-thread.3 b/docs/libcurl/libcurl-thread.3 index 155e4e34c..070b47a2b 100644 --- a/docs/libcurl/libcurl-thread.3 +++ b/docs/libcurl/libcurl-thread.3 @@ -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. - -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 +\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. + +\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. + +\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. -- cgit v1.2.3