1.. _thread-safety:
2
3Thread Safety
4=============
5
6Per `libcurl thread safety documentation`_, libcurl is thread-safe but
7has no internal thread synchronization.
8
9For Python programs using PycURL, this means:
10
11* Accessing the same PycURL object from different threads is OK when
12  this object is not involved in active transfers, as Python internally
13  has a Global Interpreter Lock and only one operating system thread can
14  be executing Python code at a time.
15
16* Accessing a PycURL object that is involved in an active transfer from
17  Python code *inside a libcurl callback for the PycURL object in question*
18  is OK, because PycURL takes out the appropriate locks.
19
20* Accessing a PycURL object that is involved in an active transfer from
21  Python code *outside of a libcurl callback for the PycURL object in question*
22  is unsafe.
23
24PycURL handles the necessary SSL locks for OpenSSL/LibreSSL/BoringSSL,
25GnuTLS, NSS, mbedTLS and wolfSSL.
26
27A special situation exists when libcurl uses the standard C library
28name resolver (i.e., not threaded nor c-ares resolver). By default libcurl
29uses signals for timeouts with the C library resolver, and signals do not
30work properly in multi-threaded programs. When using PycURL objects from
31multiple Python threads ``NOSIGNAL`` option `must be given`_.
32
33.. _libcurl thread safety documentation: https://curl.haxx.se/libcurl/c/threadsafe.html
34.. _must be given: https://github.com/curl/curl/issues/1003
35