]>
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 | ||
ede517bc CMN |
65 | By default we use libcurl, which has its own ![recommendations for |
66 | thread safety](http://curl.haxx.se/libcurl/c/libcurl-tutorial.html#Multi-threading). | |
67 | ||
68 | If libcurl was not found or was disabled, libgit2 uses OpenSSL to be | |
69 | able to use HTTPS as a transport. This library is made to be | |
70 | thread-implementation agnostic, and the users of the library must set | |
71 | which locking function it should use. This means that libgit2 cannot | |
72 | know what to set as the user of libgit2 may use OpenSSL independently | |
73 | and the locking settings must survive libgit2 shutting down. | |
15bea02c | 74 | |
263b1d6e CMN |
75 | libgit2 does provide a last-resort convenience function |
76 | `git_openssl_set_locking()` (available in `sys/openssl.h`) to use the | |
77 | platform-native mutex mechanisms to perform the locking, which you may | |
78 | rely on if you do not want to use OpenSSL outside of libgit2, or you | |
79 | know that libgit2 will outlive the rest of the operations. It is not | |
80 | safe to use OpenSSL multi-threaded after libgit2's shutdown function | |
81 | has been called. | |
82 | ||
83 | If your programming language offers a package/bindings for OpenSSL, | |
84 | you should very strongly prefer to use that in order to set up | |
85 | locking, as they provide a level of coördination which is impossible | |
86 | when using this function. | |
15bea02c CMN |
87 | |
88 | See the | |
89 | [OpenSSL documentation](https://www.openssl.org/docs/crypto/threads.html) | |
90 | on threading for more details. | |
91 | ||
85247df0 CMN |
92 | Be also aware that libgit2 does not always link against OpenSSL |
93 | if there are alternatives provided by the system. | |
263b1d6e | 94 | |
15bea02c CMN |
95 | libssh2 may be linked against OpenSSL or libgcrypt. If it uses |
96 | OpenSSL, you only need to set up threading for OpenSSL once and the | |
97 | above paragraphs are enough. If it uses libgcrypt, then you need to | |
98 | set up its locking before using it multi-threaded. libgit2 has no | |
99 | direct connection to libgcrypt and thus has not convenience functions for | |
100 | it (but libgcrypt has macros). Read libgcrypt's | |
101 | [threading documentation for more information](http://www.gnupg.org/documentation/manuals/gcrypt/Multi_002dThreading.html) | |
102 | ||
103 | It is your responsibility as an application author or packager to know | |
104 | what your dependencies are linked against and to take the appropriate | |
105 | steps to ensure the cryptographic libraries are thread-safe. We agree | |
106 | that this situation is far from ideal but at this time it is something | |
107 | the application authors need to deal with. |