THREADING.md

   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
  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.
  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
  44 libssh2 uses OpenSSL or libgcrypt, then the general case affects
  45 you.
  46
  47 On Mac OS X
  48 -----------
  49
  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.
  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
  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.
  74
  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.
  87
  88 See the
  89 [OpenSSL documentation](https://www.openssl.org/docs/crypto/threads.html)
  90 on threading for more details.
  91
  92 Be also aware that libgit2 does not always link against OpenSSL
  93 if there are alternatives provided by the system.
  94
  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.