Rename git_threads_ to git_libgit2_cmn/global-init

This describes their purpose better, as we now initialize ssl and some
other global stuff in there. Calling the init function is not something
which has been optional for a while now.

21 files changed, 86 insertions, 40 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 786668c4a..f168c4d74 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -112,3 +112,7 @@ v0.21 + 1
   now uint32_t instead of uint16_t. This allows to set them to UINT_MAX,
   in effect asking for "infinite" context e.g. to iterate over all the
   unmodified lines of a diff.
+
+* git_threads_init() and git_threads_shutdown() have been renamed to
+  git_libgit2_init() and git_libgit2_shutdown() to better explain what
+  their purpose is, as it's grown to be more than just about threads.
diff --git a/examples/add.c b/examples/add.c
index 0c6076e81..0101ab9ae 100644
--- a/examples/add.c
+++ b/examples/add.c
@@ -40,7 +40,7 @@ int main (int argc, char** argv)
 	int options = 0, count = 0;
 	struct print_payload payload = {0};
 
-	git_threads_init();
+	git_libgit2_init();
 
 	parse_opts(&options, &count, argc, argv);
 
@@ -66,7 +66,7 @@ int main (int argc, char** argv)
 	git_index_free(index);
 	git_repository_free(repo);
 
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 
 	return 0;
 }
diff --git a/examples/blame.c b/examples/blame.c
index fda605bce..9d38f25a4 100644
--- a/examples/blame.c
+++ b/examples/blame.c
@@ -48,7 +48,7 @@ int main(int argc, char *argv[])
 	git_blob *blob;
 	git_object *obj;
 
-	git_threads_init();
+	git_libgit2_init();
 
 	parse_opts(&o, argc, argv);
 	if (o.M) blameopts.flags |= GIT_BLAME_TRACK_COPIES_SAME_COMMIT_MOVES;
@@ -131,7 +131,7 @@ int main(int argc, char *argv[])
 	git_blame_free(blame);
 	git_repository_free(repo);
 
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 
 	return 0;
 }
diff --git a/examples/cat-file.c b/examples/cat-file.c
index 52399fa8a..f948740a1 100644
--- a/examples/cat-file.c
+++ b/examples/cat-file.c
@@ -127,7 +127,7 @@ int main(int argc, char *argv[])
 	git_object *obj = NULL;
 	char oidstr[GIT_OID_HEXSZ + 1];
 
-	git_threads_init();
+	git_libgit2_init();
 
 	parse_opts(&o, argc, argv);
 
@@ -190,7 +190,7 @@ int main(int argc, char *argv[])
 	git_object_free(obj);
 	git_repository_free(repo);
 
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 
 	return 0;
 }
diff --git a/examples/describe.c b/examples/describe.c
index cbf73b012..09a4fd008 100644
--- a/examples/describe.c
+++ b/examples/describe.c
@@ -145,7 +145,7 @@ int main(int argc, char **argv)
 	git_repository *repo;
 	describe_options opts;
 
-	git_threads_init();
+	git_libgit2_init();
 
 	check_lg2(git_repository_open_ext(&repo, ".", 0, NULL),
 			"Could not open repository", NULL);
@@ -156,7 +156,7 @@ int main(int argc, char **argv)
 	do_describe(repo, &opts);
 
 	git_repository_free(repo);
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 
 	return 0;
 }
diff --git a/examples/diff.c b/examples/diff.c
index 76ac2f311..b69cb2218 100644
--- a/examples/diff.c
+++ b/examples/diff.c
@@ -77,7 +77,7 @@ int main(int argc, char *argv[])
 		-1, 0, 0, GIT_DIFF_FORMAT_PATCH, NULL, NULL, "."
 	};
 
-	git_threads_init();
+	git_libgit2_init();
 
 	parse_opts(&o, argc, argv);
 
@@ -163,7 +163,7 @@ int main(int argc, char *argv[])
 	git_tree_free(t2);
 	git_repository_free(repo);
 
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 
 	return 0;
 }
diff --git a/examples/general.c b/examples/general.c
index 051d69380..8981cacab 100644
--- a/examples/general.c
+++ b/examples/general.c
@@ -59,6 +59,10 @@ static void check_error(int error_code, const char *action)
 
 int main (int argc, char** argv)
 {
+  // Initialize the library, this will set up any global state which libgit2 needs
+  // including threading and crypto
+  git_libgit2_init();
+
   // ### Opening the Repository
 
   // There are a couple of methods for opening a repository, this being the
diff --git a/examples/init.c b/examples/init.c
index 0e823ab81..fe7a67224 100644
--- a/examples/init.c
+++ b/examples/init.c
@@ -46,7 +46,7 @@ int main(int argc, char *argv[])
 	git_repository *repo = NULL;
 	struct opts o = { 1, 0, 0, 0, GIT_REPOSITORY_INIT_SHARED_UMASK, 0, 0, 0 };
 
-	git_threads_init();
+	git_libgit2_init();
 
 	parse_opts(&o, argc, argv);
 
@@ -116,7 +116,7 @@ int main(int argc, char *argv[])
 	}
 
 	git_repository_free(repo);
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 
 	return 0;
 }
diff --git a/examples/log.c b/examples/log.c
index d5f75a297..e54eed3ce 100644
--- a/examples/log.c
+++ b/examples/log.c
@@ -80,7 +80,7 @@ int main(int argc, char *argv[])
 	git_commit *commit = NULL;
 	git_pathspec *ps = NULL;
 
-	git_threads_init();
+	git_libgit2_init();
 
 	/** Parse arguments and set up revwalker. */
 
@@ -180,7 +180,7 @@ int main(int argc, char *argv[])
 	git_pathspec_free(ps);
 	git_revwalk_free(s.walker);
 	git_repository_free(s.repo);
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 
 	return 0;
 }
diff --git a/examples/network/git2.c b/examples/network/git2.c
index 5b32ac809..d44334b85 100644
--- a/examples/network/git2.c
+++ b/examples/network/git2.c
@@ -54,7 +54,7 @@ int main(int argc, char **argv)
 		exit(EXIT_FAILURE);
 	}
 
-	git_threads_init();
+	git_libgit2_init();
 
 	for (i = 0; commands[i].name != NULL; ++i) {
 		if (!strcmp(argv[1], commands[i].name))
diff --git a/examples/rev-list.c b/examples/rev-list.c
index 940a01136..ee9afc441 100644
--- a/examples/rev-list.c
+++ b/examples/rev-list.c
@@ -24,7 +24,7 @@ int main (int argc, char **argv)
 	git_oid oid;
 	char buf[GIT_OID_HEXSZ+1];
 
-	git_threads_init();
+	git_libgit2_init();
 
 	check_lg2(git_repository_open_ext(&repo, ".", 0, NULL), "opening repository", NULL);
 	check_lg2(git_revwalk_new(&walk, repo), "allocating revwalk", NULL);
@@ -36,7 +36,7 @@ int main (int argc, char **argv)
 		printf("%s\n", buf);
 	}
 
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 	return 0;
 }
 
diff --git a/examples/rev-parse.c b/examples/rev-parse.c
index a24833767..483d6e019 100644
--- a/examples/rev-parse.c
+++ b/examples/rev-parse.c
@@ -29,13 +29,13 @@ int main(int argc, char *argv[])
 {
 	struct parse_state ps = {0};
 
-	git_threads_init();
+	git_libgit2_init();
 	parse_opts(&ps, argc, argv);
 
 	check_lg2(parse_revision(&ps), "Parsing", NULL);
 
 	git_repository_free(ps.repo);
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 
 	return 0;
 }
diff --git a/examples/showindex.c b/examples/showindex.c
index 604124f12..43be5e24c 100644
--- a/examples/showindex.c
+++ b/examples/showindex.c
@@ -23,7 +23,7 @@ int main (int argc, char** argv)
 	char out[GIT_OID_HEXSZ+1];
 	out[GIT_OID_HEXSZ] = '\0';
 
-	git_threads_init();
+	git_libgit2_init();
 
 	if (argc > 2)
 		fatal("usage: showindex [<repo-dir>]", NULL);
@@ -64,7 +64,7 @@ int main (int argc, char** argv)
 	}
 
 	git_index_free(index);
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 
 	return 0;
 }
diff --git a/examples/status.c b/examples/status.c
index a59f34454..62cb5b24f 100644
--- a/examples/status.c
+++ b/examples/status.c
@@ -73,7 +73,7 @@ int main(int argc, char *argv[])
 	git_status_list *status;
 	struct opts o = { GIT_STATUS_OPTIONS_INIT, "." };
 
-	git_threads_init();
+	git_libgit2_init();
 
 	o.statusopt.show  = GIT_STATUS_SHOW_INDEX_AND_WORKDIR;
 	o.statusopt.flags = GIT_STATUS_OPT_INCLUDE_UNTRACKED |
@@ -135,7 +135,7 @@ show_status:
 	}
 
 	git_repository_free(repo);
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 
 	return 0;
 }
diff --git a/examples/tag.c b/examples/tag.c
index 1d254aee5..c6a70d90e 100644
--- a/examples/tag.c
+++ b/examples/tag.c
@@ -300,7 +300,7 @@ int main(int argc, char **argv)
 	tag_action action;
 	tag_state state;
 
-	git_threads_init();
+	git_libgit2_init();
 
 	check_lg2(git_repository_open_ext(&repo, ".", 0, NULL),
 			"Could not open repository", NULL);
@@ -313,7 +313,7 @@ int main(int argc, char **argv)
 	action(&state);
 
 	git_repository_free(repo);
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 
 	return 0;
 }
diff --git a/include/git2.h b/include/git2.h
index 41adbbad2..388cd82d0 100644
--- a/include/git2.h
+++ b/include/git2.h
@@ -56,7 +56,7 @@
 #include "git2/status.h"
 #include "git2/submodule.h"
 #include "git2/tag.h"
-#include "git2/threads.h"
+#include "git2/global.h"
 #include "git2/transport.h"
 #include "git2/tree.h"
 #include "git2/types.h"
diff --git a/include/git2/global.h b/include/git2/global.h
new file mode 100644
index 000000000..4f90c4c20
--- /dev/null
+++ b/include/git2/global.h
@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) the libgit2 contributors. All rights reserved.
+ *
+ * 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_global_h__
+#define INCLUDE_git_global_h__
+
+#include "common.h"
+
+GIT_BEGIN_DECL
+
+/**
+ * Init the global state
+ *
+ * This function must the called before any other libgit2 function in
+ * order to set up global state and threading.
+ *
+ * This function may be called multiple times.
+ *
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_libgit2_init(void);
+
+/**
+ * Shutdown the global state
+ *
+ * Clean up the global state and threading context after calling it as
+ * many times as `git_libgit2_init()` was called.
+ * 
+ */
+GIT_EXTERN(void) git_libgit2_shutdown(void);
+
+/** @} */
+GIT_END_DECL
+#endif
+
diff --git a/src/global.c b/src/global.c
index 3c91860cd..296be86c7 100644
--- a/src/global.c
+++ b/src/global.c
@@ -133,7 +133,7 @@ int git_openssl_set_locking(void)
  * Handle the global state with TLS
  *
  * If libgit2 is built with GIT_THREADS enabled,
- * the `git_threads_init()` function must be called
+ * the `git_libgit2_init()` function must be called
  * before calling any other function of the library.
  *
  * This function allocates a TLS index (using pthreads
@@ -156,9 +156,9 @@ int git_openssl_set_locking(void)
  */
 
 /*
- * `git_threads_init()` allows subsystems to perform global setup,
+ * `git_libgit2_init()` allows subsystems to perform global setup,
  * which may take place in the global scope.  An explicit memory
- * fence exists at the exit of `git_threads_init()`.  Without this,
+ * fence exists at the exit of `git_libgit2_init()`.  Without this,
  * CPU cores are free to reorder cache invalidation of `_tls_init`
  * before cache invalidation of the subsystems' newly written global
  * state.
@@ -185,7 +185,7 @@ static int synchronized_threads_init(void)
 	return error;
 }
 
-int git_threads_init(void)
+int git_libgit2_init(void)
 {
 	int error = 0;
 
@@ -210,7 +210,7 @@ static void synchronized_threads_shutdown(void)
 	git_mutex_free(&git__mwindow_mutex);
 }
 
-void git_threads_shutdown(void)
+void git_libgit2_shutdown(void)
 {
 	/* Enter the lock */
 	while (InterlockedCompareExchange(&_mutex, 1, 0)) { Sleep(0); }
@@ -272,14 +272,14 @@ static void init_once(void)
 	GIT_MEMORY_BARRIER;
 }
 
-int git_threads_init(void)
+int git_libgit2_init(void)
 {
 	pthread_once(&_once_init, init_once);
 	git_atomic_inc(&git__n_inits);
 	return init_error;
 }
 
-void git_threads_shutdown(void)
+void git_libgit2_shutdown(void)
 {
 	void *ptr = NULL;
 	pthread_once_t new_once = PTHREAD_ONCE_INIT;
@@ -320,7 +320,7 @@ git_global_st *git__global_state(void)
 
 static git_global_st __state;
 
-int git_threads_init(void)
+int git_libgit2_init(void)
 {
 	static int ssl_inited = 0;
 
@@ -333,7 +333,7 @@ int git_threads_init(void)
 	return 0;
 }
 
-void git_threads_shutdown(void)
+void git_libgit2_shutdown(void)
 {
 	/* Shut down any subsystems that have global state */
 	if (0 == git_atomic_dec(&git__n_inits))
diff --git a/src/hash/hash_win32.c b/src/hash/hash_win32.c
index bb2231364..6bae53e55 100644
--- a/src/hash/hash_win32.c
+++ b/src/hash/hash_win32.c
@@ -236,7 +236,7 @@ int git_hash_ctx_init(git_hash_ctx *ctx)
 
 	/*
 	 * When compiled with GIT_THREADS, the global hash_prov data is
-	 * initialized with git_threads_init.  Otherwise, it must be initialized
+	 * initialized with git_libgit2_init.  Otherwise, it must be initialized
 	 * at first use.
 	 */
 	if (hash_prov.type == INVALID && (error = git_hash_global_init()) < 0)
diff --git a/tests/main.c b/tests/main.c
index 3de4f9801..a092b8ba4 100644
--- a/tests/main.c
+++ b/tests/main.c
@@ -10,7 +10,7 @@ int main(int argc, char *argv[])
 
 	clar_test_init(argc, argv);
 
-	git_threads_init();
+	git_libgit2_init();
 	cl_sandbox_set_search_path_defaults();
 
 	/* Run the test suite */
@@ -19,7 +19,7 @@ int main(int argc, char *argv[])
 	clar_test_shutdown();
 
 	giterr_clear();
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 
 	return res;
 }
diff --git a/tests/threads/basic.c b/tests/threads/basic.c
index eb15293c7..9c342bc42 100644
--- a/tests/threads/basic.c
+++ b/tests/threads/basic.c
@@ -27,11 +27,11 @@ void test_threads_basic__multiple_init(void)
 {
 	git_repository *nested_repo;
 
-	git_threads_init();
+	git_libgit2_init();
 	cl_git_pass(git_repository_open(&nested_repo, cl_fixture("testrepo.git")));
 	git_repository_free(nested_repo);
 
-	git_threads_shutdown();
+	git_libgit2_shutdown();
 	cl_git_pass(git_repository_open(&nested_repo, cl_fixture("testrepo.git")));
 	git_repository_free(nested_repo);
 }