[Global]: loading init

deps/curl/docs/libcurl/libcurl-thread.md

@@ -0,0 +1,99 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: libcurl-thread
+Section: 3
+Source: libcurl
+See-also:
+  - libcurl-security (3)
+---
+
+# NAME
+
+libcurl-thread - libcurl thread safety
+
+# 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.
+
+# Handles
+
+You must **never** 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 provide your own locking and set
+curl_share_setopt(3) 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).
+
+# 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.
+
+# 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 CURLOPT_NOSIGNAL(3)
+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 CURLOPT_NOSIGNAL(3) option
+is set.
+
+When CURLOPT_NOSIGNAL(3) 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 CURLOPT_NOSIGNAL(3) 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.
+
+# Name resolving
+
+The **gethostbyname** or **getaddrinfo** 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.
+
+# curl_global_* functions
+
+These functions are thread-safe since libcurl 7.84.0 if
+curl_version_info(3) has the **CURL_VERSION_THREADSAFE** 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
+curl_global_init(3) or curl_global_init_mem(3) to explicitly
+initialize the library and its dependents, rather than rely on the "lazy"
+fail-safe initialization that takes place the first time
+curl_easy_init(3) is called. For an in-depth explanation refer to
+libcurl(3) section **GLOBAL CONSTANTS**.
+
+# Memory functions
+
+These functions, provided either by your operating system or your own
+replacements, must be thread safe. You can use curl_global_init_mem(3)
+to set your own replacement memory functions.
+
+# Non-safe functions
+
+CURLOPT_DNS_USE_GLOBAL_CACHE(3) is not thread-safe.
+
+curl_version_info(3) is not thread-safe before libcurl initialization.