125 lines
5.9 KiB
Groff
125 lines
5.9 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * 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 "August 22, 2023" "libcurl 8.3.0" "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. On systems that
|
|
have a signal concept.
|
|
|
|
When using multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP
|
|
option to 1L for all handles. Everything works fine except that timeouts
|
|
cannot be honored during DNS lookups - 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 cannot
|
|
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 does not work in a
|
|
threaded situation as there is a race condition 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.
|