1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: libcurl-thread 5Section: 3 6Source: libcurl 7See-also: 8 - libcurl-security (3) 9Protocol: 10 - All 11Added-in: n/a 12--- 13 14# NAME 15 16libcurl-thread - libcurl thread safety 17 18# Multi-threading with libcurl 19 20libcurl is thread safe but has no internal thread synchronization. You may have 21to provide your own locking should you meet any of the thread safety exceptions 22below. 23 24# Handles 25 26You must **never** share the same handle in multiple threads. You can pass the 27handles around among threads, but you must never use a single handle from more 28than one thread at any given time. 29 30# Shared objects 31 32You can share certain data between multiple handles by using the share 33interface but you must provide your own locking and set 34curl_share_setopt(3) CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC. 35 36Note that some items are specifically documented as not thread-safe in the 37share API (the connection pool and HSTS cache for example). 38 39# TLS 40 41All current TLS libraries libcurl supports are thread-safe. 42 43## OpenSSL 44 45OpenSSL 1.1.0+ can be safely used in multi-threaded applications provided that 46support for the underlying OS threading API is built-in. For older versions of 47OpenSSL, the user must set mutex callbacks. 48 49libcurl may not be able to fully clean up after multi-threaded OpenSSL 50depending on how OpenSSL was built and loaded as a library. It is possible in 51some rare circumstances a memory leak could occur unless you implement your own 52OpenSSL thread cleanup. 53 54For example, on Windows if both libcurl and OpenSSL are linked statically to a 55DLL or application then OpenSSL may leak memory unless the DLL or application 56calls OPENSSL_thread_stop() before each thread terminates. If OpenSSL is built 57as a DLL then it does this cleanup automatically and there is no leak. If 58libcurl is built as a DLL and OpenSSL is linked statically to it then libcurl 59does this cleanup automatically and there is no leak (added in libcurl 8.8.0). 60 61Please review the OpenSSL documentation for a full list of circumstances: 62https://docs.openssl.org/3.0/man3/OPENSSL_init_crypto/#notes 63 64# Signals 65 66Signals are used for timing out name resolves (during DNS lookup) - when built 67without using either the c-ares or threaded resolver backends. On systems that 68have a signal concept. 69 70When using multiple threads you should set the CURLOPT_NOSIGNAL(3) 71option to 1L for all handles. Everything works fine except that timeouts 72cannot be honored during DNS lookups - which you can work around by building 73libcurl with c-ares or threaded-resolver support. c-ares is a library that 74provides asynchronous name resolves. On some platforms, libcurl simply cannot 75function properly multi-threaded unless the CURLOPT_NOSIGNAL(3) option 76is set. 77 78When CURLOPT_NOSIGNAL(3) is set to 1L, your application needs to deal 79with the risk of a SIGPIPE (that at least the OpenSSL backend can 80trigger). Note that setting CURLOPT_NOSIGNAL(3) to 0L does not work in a 81threaded situation as there is a race condition where libcurl risks restoring 82the former signal handler while another thread should still ignore it. 83 84# Name resolving 85 86The **gethostbyname** or **getaddrinfo** and other name resolving system 87calls used by libcurl are provided by your operating system and must be thread 88safe. It is important that libcurl can find and use thread safe versions of 89these and other system calls, as otherwise it cannot function fully thread 90safe. Some operating systems are known to have faulty thread 91implementations. We have previously received problem reports on *BSD (at least 92in the past, they may be working fine these days). Some operating systems that 93are known to have solid and working thread support are Linux, Solaris and 94Windows. 95 96# curl_global_* functions 97 98These functions are thread-safe since libcurl 7.84.0 if 99curl_version_info(3) has the **CURL_VERSION_THREADSAFE** feature bit 100set (most platforms). 101 102If these functions are not thread-safe and you are using libcurl with multiple 103threads it is especially important that before use you call 104curl_global_init(3) or curl_global_init_mem(3) to explicitly 105initialize the library and its dependents, rather than rely on the "lazy" 106fail-safe initialization that takes place the first time 107curl_easy_init(3) is called. For an in-depth explanation refer to 108libcurl(3) section **GLOBAL CONSTANTS**. 109 110# Memory functions 111 112These functions, provided either by your operating system or your own 113replacements, must be thread safe. You can use curl_global_init_mem(3) 114to set your own replacement memory functions. 115 116# Non-safe functions 117 118CURLOPT_DNS_USE_GLOBAL_CACHE(3) is not thread-safe. 119 120curl_version_info(3) is not thread-safe before libcurl initialization. 121
