Fix the retarded object interdependency system

It's no longer retarded. All object interdependencies are stored as OIDs
instead of actual objects. This should be hundreds of times faster,
specially on big repositories. Heck, who knows, maye it doesn't even
segfault -- wouldn't that be awesome?

What has changed on the API?

	`git_commit_parent`, `git_commit_tree`, `git_tag_target` now return
	their values through a pointer-to-pointer, and have an error code.

	`git_commit_set_tree` and `git_tag_set_target` now return an error
	code and may fail.

	`git_repository_free__no_gc` has been deprecated because it's
	stupid. Since there are no longer any interdependencies between
	objects, we don't need internal reference counting, and GC
	never fails or double-free's pointers.

	`git_object_close` now does a very sane thing: marks an object
	as unused. Closed objects will be eventually free'd from the
	object cache based on LRU. Please use `git_object_close` from
	the garbage collector `destroy` method on your bindings. It's
	100% safe.

	`git_repository_gc` is a new method that forces a garbage collector
	pass through the repo, to free as many LRU objects as possible.
	This is useful if we are running out of memory.

4 files changed, 36 insertions, 15 deletions

diff --git a/include/git2/commit.h b/include/git2/commit.h
index 21836dbbd..1556e52b1 100644
--- a/include/git2/commit.h
+++ b/include/git2/commit.h
@@ -122,10 +122,11 @@ GIT_EXTERN(const git_signature *) git_commit_author(git_commit *commit);
 
 /**
  * Get the tree pointed to by a commit.
+ * @param tree_out pointer where to store the tree object
  * @param commit a previously loaded commit.
- * @return the tree of a commit
+ * @return 0 on success; error code otherwise
  */
-GIT_EXTERN(const git_tree *) git_commit_tree(git_commit *commit);
+GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, git_commit *commit);
 
 /**
  * Get the number of parents of this commit
@@ -137,11 +138,13 @@ GIT_EXTERN(unsigned int) git_commit_parentcount(git_commit *commit);
 
 /**
  * Get the specified parent of the commit.
+ *
+ * @param parent Pointer where to store the parent commit
  * @param commit a previously loaded commit.
- * @param n the position of the entry
- * @return a pointer to the commit; NULL if out of bounds
+ * @param n the position of the parent (from 0 to `parentcount`)
+ * @return 0 on success; error code otherwise
  */
-GIT_EXTERN(git_commit *) git_commit_parent(git_commit *commit, unsigned int n);
+GIT_EXTERN(int) git_commit_parent(git_commit **parent, git_commit *commit, unsigned int n);
 
 /**
  * Add a new parent commit to an existing commit
@@ -176,8 +179,9 @@ GIT_EXTERN(void) git_commit_set_author(git_commit *commit, const git_signature *
  * Set the tree which is pointed to by a commit
  * @param commit the commit object
  * @param tree the new tree
+ * @param 0 on success; error code otherwise
  */
-GIT_EXTERN(void) git_commit_set_tree(git_commit *commit, git_tree *tree);
+GIT_EXTERN(int) git_commit_set_tree(git_commit *commit, git_tree *tree);
 
 /** @} */
 GIT_END_DECL
diff --git a/include/git2/object.h b/include/git2/object.h
index af0f014e3..748386f69 100644
--- a/include/git2/object.h
+++ b/include/git2/object.h
@@ -131,10 +131,10 @@ GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj);
  * Close an open object
  *
  * This method instructs the library to close an existing
- * object; note that git_objects are owned by the repository
- * and are reference counted, so the object may or may not be
- * freed after this library call, depending on whether any other 
- * objects still depend on it.
+ * object; note that git_objects are owned and cached by the repository
+ * so the object may or may not be freed after this library call,
+ * depending on how agressive is the caching mechanism used
+ * by the repository.
  *
  * IMPORTANT:
  * It is *not* necessary to call this method when you stop using
diff --git a/include/git2/repository.h b/include/git2/repository.h
index 5327f8c58..d5f6cf501 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -154,12 +154,20 @@ GIT_EXTERN(int) git_repository_index(git_index **index, git_repository *repo);
 
 /**
  * Free a previously allocated repository
+ *
  * @param repo repository handle to close. If NULL nothing occurs.
  */
 GIT_EXTERN(void) git_repository_free(git_repository *repo);
 
-
-GIT_EXTERN(void) git_repository_free__no_gc(git_repository *repo);
+/**
+ * Force a garbage collector pass on the repository
+ *
+ * This will force-free any cached objects that have been
+ * previously marked by the user as closed (`git_object_close`).
+ *
+ * @param repo repository handle to collect. If NULL nothing occurs.
+ */
+GIT_EXTERN(void) git_repository_close(git_repository *repo);
 
 /**
  * Creates a new Git repository in the given folder.
diff --git a/include/git2/tag.h b/include/git2/tag.h
index 2ca25c8a0..f1669eb90 100644
--- a/include/git2/tag.h
+++ b/include/git2/tag.h
@@ -79,10 +79,18 @@ GIT_EXTERN(const git_oid *) git_tag_id(git_tag *tag);
 
 /**
  * Get the tagged object of a tag
+ * @param target pointer where to store the target
  * @param tag a previously loaded tag.
- * @return reference to a repository object
+ * @return 0 on success; error code otherwise
+ */
+GIT_EXTERN(int) git_tag_target(git_object **target, git_tag *t);
+
+/**
+ * Get the OID of the tagged object of a tag
+ * @param tag a previously loaded tag.
+ * @return pointer to the OID
  */
-GIT_EXTERN(const git_object *) git_tag_target(git_tag *t);
+GIT_EXTERN(const git_oid *) git_tag_target_oid(git_tag *t);
 
 /**
  * Get the type of a tag's tagged object
@@ -117,7 +125,7 @@ GIT_EXTERN(const char *) git_tag_message(git_tag *t);
  * @param tag The tag to modify
  * @param target the new tagged target
  */
-GIT_EXTERN(void) git_tag_set_target(git_tag *tag, git_object *target);
+GIT_EXTERN(int) git_tag_set_target(git_tag *tag, git_object *target);
 
 /**
  * Set the name of a tag
@@ -130,6 +138,7 @@ GIT_EXTERN(void) git_tag_set_name(git_tag *tag, const char *name);
  * Set the tagger of a tag
  * @param tag The tag to modify
  * @param tagger_sig signature of the tagging action
+ * @return 0 on success; error code otherwise
  */
 GIT_EXTERN(void) git_tag_set_tagger(git_tag *tag, const git_signature *tagger_sig);