Merge pull request #2759 from libgit2/cmn/openssl-sys

Make OpenSSL locking warnings more severe

CHANGELOG.md

@@ -33,6 +33,11 @@ v0.21 + 1
   tells it to include a copy of libssh2 at the given location. This is
   enabled for MSVC.
 
+* libgit2 no longer automatically sets the OpenSSL locking
+  functions. This is not something which we can know to do. A
+  last-resort convenience function is provided in sys/openssl.h,
+  git_openssl_set_locking() which can be used to set the locking.
+
 * The git_transport_register function no longer takes a priority and takes
   a URL scheme name (eg "http") instead of a prefix like "http://"
 

THREADING.md

@@ -54,17 +54,26 @@ it should use. This means that libgit2 cannot know what to set as the
 user of libgit2 may use OpenSSL independently and the locking settings
 must survive libgit2 shutting down.
 
-libgit2 does provide a convenience function
-`git_openssl_set_locking()` to use the platform-native mutex
-mechanisms to perform the locking, which you may rely on if you do not
-want to use OpenSSL outside of libgit2, or you know that libgit2 will
-outlive the rest of the operations. It is not safe to use OpenSSL
-multi-threaded after libgit2's shutdown function has been called.
+libgit2 does provide a last-resort convenience function
+`git_openssl_set_locking()` (available in `sys/openssl.h`) to use the
+platform-native mutex mechanisms to perform the locking, which you may
+rely on if you do not want to use OpenSSL outside of libgit2, or you
+know that libgit2 will outlive the rest of the operations. It is not
+safe to use OpenSSL multi-threaded after libgit2's shutdown function
+has been called.
+
+If your programming language offers a package/bindings for OpenSSL,
+you should very strongly prefer to use that in order to set up
+locking, as they provide a level of coördination which is impossible
+when using this function.
 
 See the
 [OpenSSL documentation](https://www.openssl.org/docs/crypto/threads.html)
 on threading for more details.
 
+Be also aware that libgit2 may not always link against OpenSSL in the
+future if there are alternatives provided by the system.
+
 libssh2 may be linked against OpenSSL or libgcrypt. If it uses
 OpenSSL, you only need to set up threading for OpenSSL once and the
 above paragraphs are enough. If it uses libgcrypt, then you need to

include/git2.h

@@ -57,7 +57,6 @@
 #include "git2/status.h"
 #include "git2/submodule.h"
 #include "git2/tag.h"
-#include "git2/threads.h"
 #include "git2/transport.h"
 #include "git2/tree.h"
 #include "git2/types.h"

include/git2/threads.h → include/git2/sys/openssl.h

@@ -4,37 +4,35 @@
  * This file is part of libgit2, distributed under the GNU GPL v2 with
  * a Linking Exception. For full terms see the included COPYING file.
  */
-#ifndef INCLUDE_git_threads_h__
-#define INCLUDE_git_threads_h__
+#ifndef INCLUDE_git_openssl_h__
+#define INCLUDE_git_openssl_h__
 
 #include "common.h"
 
-/**
- * @file git2/threads.h
- * @brief Library level thread functions
- * @defgroup git_thread Threading functions
- * @ingroup Git
- * @{
- */
 GIT_BEGIN_DECL
 
 /**
  * Initialize the OpenSSL locks
  *
  * OpenSSL requires the application to determine how it performs
- * locking. This is a convenience function which libgit2 provides for
+ * locking.
+ *
+ * This is a last-resort convenience function which libgit2 provides for
  * allocating and initializing the locks as well as setting the
  * locking function to use the system's native locking functions.
  *
  * The locking function will be cleared and the memory will be freed
  * when you call git_threads_sutdown().
  *
+ * If your programming language has an OpenSSL package/bindings, it
+ * likely sets up locking. You should very strongly prefer that over
+ * this function.
+ *
  * @return 0 on success, -1 if there are errors or if libgit2 was not
  * built with OpenSSL and threading support.
  */
 GIT_EXTERN(int) git_openssl_set_locking(void);
 
-/** @} */
 GIT_END_DECL
 #endif
 

src/global.c

@@ -8,7 +8,6 @@
 #include "global.h"
 #include "hash.h"
 #include "sysdir.h"
-#include "git2/threads.h"
 #include "git2/global.h"
 #include "thread-utils.h"