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