docs/libcurl/libcurl-thread.3 - platform/external/curl - Git at Google

 .\" **************************************************************************
 .\" *                                  _   _ ____  _
 .\" *  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
 All current TLS libraries libcurl supports are thread-safe. OpenSSL 1.1.0+ can
 be safely used in multi-threaded applications provided that support for the
 underlying OS threading API is built-in. For older versions of OpenSSL, the
 user must set mutex callbacks.
 .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.
	.\" **************************************************************************
	.\" * _ _ ____ _
	.\" * 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
	All current TLS libraries libcurl supports are thread-safe. OpenSSL 1.1.0+ can
	be safely used in multi-threaded applications provided that support for the
	underlying OS threading API is built-in. For older versions of OpenSSL, the
	user must set mutex callbacks.
	.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.