proxmox-mirrors/libgit2
1
0
Fork 0
mirror of https://git.proxmox.com/git/libgit2 synced 2025-05-05 10:05:03 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #3985 from libgit2/cmn/threading-update

Browse Source 
Update THREADING for OpenSSL 1.1
This commit is contained in:
Carlos Martín Nieto 2016-11-14 10:19:30 +01:00 committed by GitHub
commit eb71490ac2
1 changed files with 21 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
THREADING.md
View File

@ -62,29 +62,34 @@ general case still affects you if you use ssh.
General Case
------------
By default we use libcurl, which has its own ![recommendations for
thread safety](http://curl.haxx.se/libcurl/c/libcurl-tutorial.html#Multi-threading).
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 libcurl was not found or was disabled, libgit2 uses OpenSSL to be
able to use HTTPS as a transport. This library is made to be
thread-implementation agnostic, and the users of the library must set
which locking function it should use. This means that libgit2 cannot
know what to set as the user of libgit2 may use OpenSSL independently
and the locking settings must survive libgit2 shutting down.
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.
Even if libgit2 doesn't use OpenSSL directly, OpenSSL can still be used
by libssh2 depending on the configuration. If OpenSSL is used both by
libgit2 and libssh2, you only need to set up threading for OpenSSL once.
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.
libgit2 does provide a last-resort convenience function
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
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
`git_openssl_set_locking()` (available in `sys/openssl.h`) to use the
platform-native mutex mechanisms to perform the locking, which you may
rely on 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 not
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 as described above, `git_openssl_set_locking()` is a no-op.
of libssh2 or libcurl 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
@ -96,9 +101,6 @@ See the
on threading for more details, and http://trac.libssh2.org/wiki/MultiThreading
for a specific example of providing the threading callbacks.
Be also aware that libgit2 does not always link against OpenSSL
if there are alternatives provided by the system.
libssh2 may be linked against OpenSSL or libgcrypt. If it uses OpenSSL,
see the above paragraphs. If it uses libgcrypt, then you need to
set up its locking before using it multi-threaded. libgit2 has no