Make the OpenSSL locking function warnings more severe

Our git_openssl_set_locking() would ideally not exist. Make it clearer
that we provide it as a last resort and you should prefer anything else.

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"