Merge branch 'threading-docs'

Author: ethomson

docs/threading.md

@@ -1,8 +1,10 @@
-Threads in libgit2
+Threading in libgit2
 ==================
 
-You may safely use any libgit2 object from any thread, though there
-may be issues depending on the cryptographic libraries libgit2 or its
+Unless otherwise specified, libgit2 objects cannot be safely accessed by
+multiple threads simultaneously.
+
+There are also caveats on the cryptographic libraries libgit2 or its
 dependencies link to (more on this later). For libgit2 itself,
 provided you take the following into consideration you won't run into
 issues:
@@ -26,11 +28,11 @@ The error message is thread-local. The `git_error_last()` call must
 happen on the same thread as the error in order to get the
 message. Often this will be the case regardless, but if you use
 something like the [GCD](http://en.wikipedia.org/wiki/Grand_Central_Dispatch)
-on Mac OS X (where code is executed on an arbitrary thread), the code
+on macOS (where code is executed on an arbitrary thread), the code
 must make sure to retrieve the error code on the thread where the error
 happened.
 
-Threads and cryptographic libraries
+Threading and cryptographic libraries
 =======================================
 
 On Windows
@@ -44,52 +46,42 @@ steps necessary. If you are using a MinGW or similar environment where
 libssh2 uses OpenSSL or libgcrypt, then the general case affects
 you.
 
-On Mac OS X
+On macOS
 -----------
 
-By default we use libcurl to perform the encryption. The
-system-provided libcurl uses SecureTransport, so no special steps are
-necessary. If you link against another libcurl (e.g. from homebrew)
-refer to the general case.
-
-If the option to use libcurl was deactivated, the library makes use of
-CommonCrypto and SecureTransport for cryptographic support. These are
-thread-safe and you do not need to do anything special.
+By default we make use of CommonCrypto and SecureTransport for cryptographic
+support. These are thread-safe and you do not need to do anything special.
 
 Note that libssh2 may still use OpenSSL itself. In that case, the
 general case still affects you if you use ssh.
 
 General Case
 ------------
 
-If it's available, by default we use libcurl to provide HTTP tunneling support,
-which may be linked against a number of cryptographic libraries and has its
-own
-[recommendations for thread safety](https://curl.haxx.se/libcurl/c/threadsafe.html).
-
-If there are no alternative TLS implementations (currently only
-SecureTransport), libgit2 uses OpenSSL in order to use HTTPS as a transport.
-OpenSSL is thread-safe starting at version 1.1.0. If your copy of libgit2 is
-linked against that version, you do not need to take any further steps.
+libgit2 will default to OpenSSL for HTTPS transport (except on Windows and
+macOS, as mentioned above).  On any system, mbedTLS _may_ be optionally
+enabled as the security provider.  OpenSSL is thread-safe starting at
+version 1.1.0. If your copy of libgit2 is linked against that version,
+you do not need to take any further steps.
 
 Older versions of OpenSSL are made to be thread-implementation agnostic, and the
 users of the library must set which locking function it should use. libgit2
 cannot know what to set as the user of libgit2 may also be using OpenSSL independently and
 the locking settings must then live outside the lifetime of libgit2.
 
 Even if libgit2 doesn't use OpenSSL directly, OpenSSL can still be used by
-libssh2 or libcurl depending on the configuration. If OpenSSL is used by
+libssh2 depending on the configuration. If OpenSSL is used by
 more than one library, you only need to set up threading for OpenSSL once.
 
-If libgit2 is linked against OpenSSL, it provides a last-resort convenience function
+If libgit2 is linked against OpenSSL < 1.1.0, it provides a last-resort convenience function
 `git_openssl_set_locking()` (available in `sys/openssl.h`) to use the
 platform-native mutex mechanisms to perform the locking, which you can use
 if you do not want to use OpenSSL outside of libgit2, or you
 know that libgit2 will outlive the rest of the operations. It is then not
 safe to use OpenSSL multi-threaded after libgit2's shutdown function
 has been called.  Note `git_openssl_set_locking()` only works if
 libgit2 uses OpenSSL directly - if OpenSSL is only used as a dependency
-of libssh2 or libcurl as described above, `git_openssl_set_locking()` is a no-op.
+of libssh2 as described above, `git_openssl_set_locking()` is a no-op.
 
 If your programming language offers a package/bindings for OpenSSL,
 you should very strongly prefer to use that in order to set up