123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121 |
- .\" **************************************************************************
- .\" * _ _ ____ _
- .\" * Project ___| | | | _ \| |
- .\" * / __| | | | |_) | |
- .\" * | (__| |_| | _ <| |___
- .\" * \___|\___/|_| \_\_____|
- .\" *
- .\" * Copyright (C) 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 https://curl.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.
- .\" *
- .\" * SPDX-License-Identifier: curl
- .\" *
- .\" **************************************************************************
- .\"
- .TH libcurl-thread 3 "13 Jul 2015" "libcurl" "libcurl"
- .SH NAME
- libcurl-thread \- libcurl thread safety
- .SH "Multi-threading with libcurl"
- 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.
- .SH "Handles"
- 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.
- .SH "Shared objects"
- 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.
- Note that some items are specifically documented as not thread-safe in the
- share API (the connection pool and HSTS cache for example).
- .SH TLS
- 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:
- .IP OpenSSL
- OpenSSL 1.1.0+ "can be safely used in multi-threaded applications provided that
- support for the underlying OS threading API is built-in." In that case the
- engine is used by libcurl in a way that is fully thread-safe.
- https://www.openssl.org/docs/man1.1.0/man3/CRYPTO_THREAD_run_once.html#DESCRIPTION
- OpenSSL <= 1.0.2 the user must set callbacks.
- https://www.openssl.org/docs/man1.0.2/man3/CRYPTO_set_locking_callback.html#DESCRIPTION
- https://curl.se/libcurl/c/opensslthreadlock.html
- .IP GnuTLS
- https://gnutls.org/manual/html_node/Thread-safety.html
- .IP NSS
- thread-safe already without anything required.
- .IP Secure-Transport
- The engine is used by libcurl in a way that is fully thread-safe.
- .IP Schannel
- 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.
- .IP BoringSSL
- The engine is used by libcurl in a way that is fully thread-safe.
- .IP AWS-LC
- The engine is used by libcurl in a way that is fully thread-safe.
- .SH "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 1L 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 or threaded-resolver support. c-ares is a library that provides
- asynchronous name resolves. On some platforms, libcurl simply will not
- function properly multi-threaded unless the \fICURLOPT_NOSIGNAL(3)\fP option
- is set.
- When \fICURLOPT_NOSIGNAL(3)\fP is set to 1L, your application needs to deal
- with the risk of a SIGPIPE (that at least the OpenSSL backend can
- trigger). Note that setting \fICURLOPT_NOSIGNAL(3)\fP to 0L will not work in a
- threaded situation as there will be race where libcurl risks restoring the
- former signal handler while another thread should still ignore it.
- .SH "Name resolving"
- The \fBgethostbyname\fP or \fBgetaddrinfo\fP and other name resolving system
- calls used by libcurl are provided by your operating system and must be thread
- safe. It is important that libcurl can find and use thread safe versions of
- these and other system calls, as otherwise it cannot 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.
- .SH "curl_global_* functions"
- These functions are thread-safe since libcurl 7.84.0 if
- \fIcurl_version_info(3)\fP has the \fBCURL_VERSION_THREADSAFE\fP feature bit
- set (most platforms).
- If these functions are not thread-safe and you are using libcurl with multiple
- threads it is especially important that before use you call
- \fIcurl_global_init(3)\fP or \fIcurl_global_init_mem(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.
- .SH "Memory functions"
- These functions, provided either by your operating system or your own
- replacements, must be thread safe. You can use \fIcurl_global_init_mem(3)\fP
- to set your own replacement memory functions.
- .SH "Non-safe functions"
- \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP is not thread-safe.
- \fIcurl_version_info(3)\fP is not thread-safe before libcurl initialization.
|