]>
Commit | Line | Data |
---|---|---|
15bea02c CMN |
1 | Threads in libgit2 |
2 | ================== | |
3 | ||
4 | You may safely use any libgit2 object from any thread, though there | |
5 | may be issues depending on the cryptographic libraries libgit2 or its | |
6 | dependencies link to (more on this later). For libgit2 itself, | |
7 | provided you take the following into consideration you won't run into | |
8 | issues: | |
9 | ||
10 | Sharing objects | |
11 | --------------- | |
12 | ||
13 | Use an object from a single thread at a time. Most data structures do | |
14 | not guard against concurrent access themselves. This is because they | |
15 | are rarely used in isolation and it makes more sense to synchronize | |
16 | access via a larger lock or similar mechanism. | |
17 | ||
18 | There are some objects which are read-only/immutable and are thus safe | |
19 | to share across threads, such as references and configuration | |
20 | snapshots. | |
21 | ||
22 | Error messages | |
23 | -------------- | |
24 | ||
25 | The error message is thread-local. The `giterr_last()` call must | |
26 | happen on the same thread as the error in order to get the | |
27 | message. Often this will be the case regardless, but if you use | |
d698712b BC |
28 | something like the [GCD](http://en.wikipedia.org/wiki/Grand_Central_Dispatch) |
29 | on Mac OS X (where code is executed on an arbitrary thread), the code | |
30 | must make sure to retrieve the error code on the thread where the error | |
31 | happened. | |
15bea02c CMN |
32 | |
33 | Threads and cryptographic libraries | |
34 | ======================================= | |
35 | ||
36 | On Windows | |
37 | ---------- | |
38 | ||
39 | When built as a native Windows DLL, libgit2 uses WinCNG and WinHTTP, | |
40 | both of which are thread-safe. You do not need to do anything special. | |
41 | ||
42 | When using libssh2 which itself uses WinCNG, there are no special | |
43 | steps necessary. If you are using a MinGW or similar environment where | |
85247df0 | 44 | libssh2 uses OpenSSL or libgcrypt, then the general case affects |
15bea02c CMN |
45 | you. |
46 | ||
85247df0 | 47 | On Mac OS X |
15bea02c CMN |
48 | ----------- |
49 | ||
ede517bc CMN |
50 | By default we use libcurl to perform the encryption. The |
51 | system-provided libcurl uses SecureTransport, so no special steps are | |
52 | necessary. If you link against another libcurl (e.g. from homebrew) | |
53 | refer to the general case. | |
54 | ||
55 | If the option to use libcurl was deactivated, the library makes use of | |
56 | CommonCrypto and SecureTransport for cryptographic support. These are | |
57 | thread-safe and you do not need to do anything special. | |
85247df0 CMN |
58 | |
59 | Note that libssh2 may still use OpenSSL itself. In that case, the | |
60 | general case still affects you if you use ssh. | |
61 | ||
62 | General Case | |
63 | ------------ | |
64 | ||
f7d316ed CMN |
65 | If it's available, by default we use libcurl to provide HTTP tunneling support, |
66 | which may be linked against a number of cryptographic libraries and has its | |
67 | own | |
68 | [recommendations for thread safety](https://curl.haxx.se/libcurl/c/threadsafe.html). | |
69 | ||
70 | If there are no alternative TLS implementations (currently only | |
71 | SecureTransport), libgit2 uses OpenSSL in order to use HTTPS as a transport. | |
72 | OpenSSL is thread-safe starting at version 1.1.0. If your copy of libgit2 is | |
73 | linked against that version, you do not need to take any further steps. | |
74 | ||
75 | Older versions of OpenSSL are made to be thread-implementation agnostic, and the | |
76 | users of the library must set which locking function it should use. libgit2 | |
77 | cannot know what to set as the user of libgit2 may also be using OpenSSL independently and | |
78 | the locking settings must then live outside the lifetime of libgit2. | |
79 | ||
80 | Even if libgit2 doesn't use OpenSSL directly, OpenSSL can still be used by | |
81 | libssh2 or libcurl depending on the configuration. If OpenSSL is used by | |
82 | more than one library, you only need to set up threading for OpenSSL once. | |
83 | ||
84 | If libgit2 is linked against OpenSSL, it provides a last-resort convenience function | |
263b1d6e | 85 | `git_openssl_set_locking()` (available in `sys/openssl.h`) to use the |
f7d316ed CMN |
86 | platform-native mutex mechanisms to perform the locking, which you can use |
87 | if you do not want to use OpenSSL outside of libgit2, or you | |
88 | know that libgit2 will outlive the rest of the operations. It is then not | |
263b1d6e | 89 | safe to use OpenSSL multi-threaded after libgit2's shutdown function |
09db7fd8 SR |
90 | has been called. Note `git_openssl_set_locking()` only works if |
91 | libgit2 uses OpenSSL directly - if OpenSSL is only used as a dependency | |
f7d316ed | 92 | of libssh2 or libcurl as described above, `git_openssl_set_locking()` is a no-op. |
263b1d6e CMN |
93 | |
94 | If your programming language offers a package/bindings for OpenSSL, | |
95 | you should very strongly prefer to use that in order to set up | |
ea9ea6ac | 96 | locking, as they provide a level of coordination which is impossible |
263b1d6e | 97 | when using this function. |
15bea02c CMN |
98 | |
99 | See the | |
100 | [OpenSSL documentation](https://www.openssl.org/docs/crypto/threads.html) | |
09db7fd8 SR |
101 | on threading for more details, and http://trac.libssh2.org/wiki/MultiThreading |
102 | for a specific example of providing the threading callbacks. | |
15bea02c | 103 | |
09db7fd8 SR |
104 | libssh2 may be linked against OpenSSL or libgcrypt. If it uses OpenSSL, |
105 | see the above paragraphs. If it uses libgcrypt, then you need to | |
15bea02c | 106 | set up its locking before using it multi-threaded. libgit2 has no |
ea9ea6ac | 107 | direct connection to libgcrypt and thus has no convenience functions for |
15bea02c CMN |
108 | it (but libgcrypt has macros). Read libgcrypt's |
109 | [threading documentation for more information](http://www.gnupg.org/documentation/manuals/gcrypt/Multi_002dThreading.html) | |
110 | ||
111 | It is your responsibility as an application author or packager to know | |
112 | what your dependencies are linked against and to take the appropriate | |
113 | steps to ensure the cryptographic libraries are thread-safe. We agree | |
114 | that this situation is far from ideal but at this time it is something | |
115 | the application authors need to deal with. |