docs/threading.md

   1 Threading in libgit2
   2 ==================
   3
   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
   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
  24 The `git_odb` object uses locking internally, and is thread-safe to use from
  25 multiple threads simultaneously.
  26
  27 Error messages
  28 --------------
  29
  30 The error message is thread-local. The `git_error_last()` call must
  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
  33 something like the [GCD](http://en.wikipedia.org/wiki/Grand_Central_Dispatch)
  34 on macOS (where code is executed on an arbitrary thread), the code
  35 must make sure to retrieve the error code on the thread where the error
  36 happened.
  37
  38 Threading and cryptographic libraries
  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
  49 libssh2 uses OpenSSL or libgcrypt, then the general case affects
  50 you.
  51
  52 On macOS
  53 -----------
  54
  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.
  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
  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.
  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
  76 libssh2 depending on the configuration. If OpenSSL is used by
  77 more than one library, you only need to set up threading for OpenSSL once.
  78
  79 If libgit2 is linked against OpenSSL < 1.1.0, it provides a last-resort convenience function
  80 `git_openssl_set_locking()` (available in `sys/openssl.h`) to use the
  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
  84 safe to use OpenSSL multi-threaded after libgit2's shutdown function
  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
  87 of libssh2 as described above, `git_openssl_set_locking()` is a no-op.
  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
  91 locking, as they provide a level of coordination which is impossible
  92 when using this function.
  93
  94 See the
  95 [OpenSSL documentation](https://www.openssl.org/docs/crypto/threads.html)
  96 on threading for more details, and http://trac.libssh2.org/wiki/MultiThreading
  97 for a specific example of providing the threading callbacks.
  98
  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
 101 set up its locking before using it multi-threaded. libgit2 has no
 102 direct connection to libgcrypt and thus has no convenience functions for
 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.