Docs for git_libgit2_opts and cache disable tweak

This adds docs for the cache control options to git_libgit2_opts
and also tweaks the cache code so that if the cache is disabled,
then the next time we attempt to insert something into the cache
in question, we will actually clear any old cached objects.

include/git2/common.h

@@ -125,7 +125,7 @@ typedef enum {
 GIT_EXTERN(int) git_libgit2_capabilities(void);
 
 
-enum {
+typedef enum {
 	GIT_OPT_GET_MWINDOW_SIZE,
 	GIT_OPT_SET_MWINDOW_SIZE,
 	GIT_OPT_GET_MWINDOW_MAPPED_LIMIT,
@@ -136,7 +136,7 @@ enum {
 	GIT_OPT_SET_CACHE_MAX_SIZE,
 	GIT_OPT_ENABLE_CACHING,
 	GIT_OPT_GET_CACHED_MEMORY
-};
+} git_libgit2_opt_t;
 
 /**
  * Set or query a library global option
@@ -180,6 +180,35 @@ enum {
  *		> - `level` must be GIT_CONFIG_LEVEL_SYSTEM, GIT_CONFIG_LEVEL_GLOBAL,
  *		>   or GIT_CONFIG_LEVEL_XDG.
  *
+ *	* opts(GIT_OPT_SET_CACHE_OBJECT_LIMIT, git_otype type, size_t size)
+ *
+ *		> Set the maximum data size for the given type of object to be
+ *		> considered eligible for caching in memory.  Setting to value to
+ *		> zero means that that type of object will not be cached.
+ *		> Defaults to 0 for GIT_OBJ_BLOB (i.e. won't cache blobs) and 4k
+ *		> for GIT_OBJ_COMMIT, GIT_OBJ_TREE, and GIT_OBJ_TAG.
+ *
+ *	* opts(GIT_OPT_SET_CACHE_MAX_SIZE, ssize_t max_storage_bytes)
+ *
+ *		> Set the maximum total data size that will be cached in memory
+ *		> across all repositories before libgit2 starts evicting objects
+ *		> from the cache.  This is a soft limit, in that the library might
+ *		> briefly exceed it, but will start aggressively evicting objects
+ *		> from cache when that happens.  The default cache size is 256Mb.
+ *
+ *	* opts(GIT_OPT_ENABLE_CACHING, int enabled)
+ *
+ *		> Enable or disable caching completely.
+ *		>
+ *		> Because caches are repository-specific, disabling the cache
+ *		> cannot immediately clear all cached objects, but each cache will
+ *		> be cleared on the next attempt to update anything in it.
+ *
+ *	* opts(GIT_OPT_GET_CACHED_MEMORY, ssize_t *current, ssize_t *allowed)
+ *
+ *		> Get the current bytes in cache and the maximum that would be
+ *		> allowed in the cache.
+ *
  * @param option Option key
  * @param ... value to set the option
  * @return 0 on success, <0 on failure

src/cache.c

@@ -174,6 +174,11 @@ static void *cache_store(git_cache *cache, git_cached_obj *entry)
 
 	git_cached_obj_incref(entry);
 
+	if (!git_cache__enabled && cache->used_memory > 0) {
+		git_cache_clear(cache);
+		return entry;
+	}
+
 	if (!cache_should_store(entry->type, entry->size))
 		return entry;