From a46ec45746f965f2895098e058979225d92d66e5 Mon Sep 17 00:00:00 2001 From: schu Date: Wed, 10 Aug 2011 16:19:42 +0200 Subject: refs: split internal and external references Currently libgit2 shares pointers to its internal reference cache with the user. This leads to several problems like invalidation of reference pointers when reordering the cache or manipulation of the cache from user side. Give each user its own git_reference instead of leaking the internal representation (struct reference). Add the following new API functions: * git_reference_free * git_reference_is_packed Signed-off-by: schu --- include/git2/refs.h | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) (limited to 'include/git2/refs.h') diff --git a/include/git2/refs.h b/include/git2/refs.h index c319bfb3d..773ae445c 100644 --- a/include/git2/refs.h +++ b/include/git2/refs.h @@ -23,8 +23,7 @@ GIT_BEGIN_DECL /** * Lookup a reference by its name in a repository. * - * The generated reference is owned by the repository and - * should not be freed by the user. + * The generated reference must be freed by the user. * * @param reference_out pointer to the looked-up reference * @param repo the repository to look up the reference @@ -39,8 +38,7 @@ GIT_EXTERN(int) git_reference_lookup(git_reference **reference_out, git_reposito * The reference will be created in the repository and written * to the disk. * - * This reference is owned by the repository and shall not - * be free'd by the user. + * The generated reference must be freed by the user. * * If `force` is true and there already exists a reference * with the same name, it will be overwritten. @@ -60,8 +58,7 @@ GIT_EXTERN(int) git_reference_create_symbolic(git_reference **ref_out, git_repos * The reference will be created in the repository and written * to the disk. * - * This reference is owned by the repository and shall not - * be free'd by the user. + * The generated reference must be freed by the user. * * If `force` is true and there already exists a reference * with the same name, it will be overwritten. @@ -173,7 +170,9 @@ GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id); * The new name will be checked for validity and may be * modified into a normalized form. * - * The refernece will be immediately renamed in-memory + * The given git_reference will be updated. + * + * The reference will be immediately renamed in-memory * and on disk. * */ @@ -200,9 +199,6 @@ GIT_EXTERN(int) git_reference_delete(git_reference *ref); * Once the `packed-refs` file has been written properly, * the loose references will be removed from disk. * - * WARNING: calling this method may invalidate any existing - * references previously loaded on the cache. - * * @param repo Repository where the loose refs will be packed * @return GIT_SUCCESS or an error code */ @@ -253,6 +249,21 @@ GIT_EXTERN(int) git_reference_listall(git_strarray *array, git_repository *repo, */ GIT_EXTERN(int) git_reference_foreach(git_repository *repo, unsigned int list_flags, int (*callback)(const char *, void *), void *payload); +/** + * Check if a reference is packed + * + * @param ref git_reference + * @return 0 in case it's not packed; 1 otherwise + */ +GIT_EXTERN(int) git_reference_is_packed(git_reference *ref); + +/** + * Free the given reference + * + * @param ref git_reference + */ +GIT_EXTERN(void) git_reference_free(git_reference *ref); + /** @} */ GIT_END_DECL #endif -- cgit v1.2.1 From d4a0b124d00c70933d7c6ac9065c401cc2d70b2e Mon Sep 17 00:00:00 2001 From: Vicent Marti Date: Sun, 30 Oct 2011 21:58:33 -0700 Subject: refs: Partial rewrite for read-only refs This new version of the references code is significantly faster and hopefully easier to read. External API stays the same. A new method `git_reference_reload()` has been added to force updating a memory reference from disk. In-memory references are no longer updated automagically -- this was killing us. If a reference is deleted externally and the user doesn't reload the memory object, nothing critical happens: any functions using that reference should fail gracefully (e.g. deletion, renaming, and so on). All generated references from the API are read only and must be free'd by the user. There is no reference counting and no traces of generated references are kept in the library. There is no longer an internal representation for references. There is only one reference struct `git_reference`, and symbolic/oid targets are stored inside an union. Packfile references are stored using an optimized struct with flex array for reference names. This should significantly reduce the memory cost of loading the packfile from disk. --- include/git2/refs.h | 43 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 4 deletions(-) (limited to 'include/git2/refs.h') diff --git a/include/git2/refs.h b/include/git2/refs.h index 773ae445c..82c5d8881 100644 --- a/include/git2/refs.h +++ b/include/git2/refs.h @@ -116,8 +116,13 @@ GIT_EXTERN(const char *) git_reference_name(git_reference *ref); * Thie method iteratively peels a symbolic reference * until it resolves to a direct reference to an OID. * + * The peeled reference is returned in the `resolved_ref` + * argument, and must be freed manually once it's no longer + * needed. + * * If a direct reference is passed as an argument, - * that reference is returned immediately + * a copy of that reference is returned. This copy must + * be manually freed too. * * @param resolved_ref Pointer to the peeled reference * @param ref The reference @@ -170,11 +175,19 @@ GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id); * The new name will be checked for validity and may be * modified into a normalized form. * - * The given git_reference will be updated. + * The given git_reference will be updated in place. * * The reference will be immediately renamed in-memory * and on disk. * + * If the `force` flag is not enabled, and there's already + * a reference with the given name, the renaming will fail. + * + * @param ref The reference to rename + * @param new_name The new name for the reference + * @param force Overwrite an existing reference + * @return GIT_SUCCESS or an error code + * */ GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name, int force); @@ -186,6 +199,8 @@ GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name, i * The reference will be immediately removed on disk and from * memory. The given reference pointer will no longer be valid. * + * @param ref The reference to remove + * @return GIT_SUCCESS or an error code */ GIT_EXTERN(int) git_reference_delete(git_reference *ref); @@ -250,13 +265,33 @@ GIT_EXTERN(int) git_reference_listall(git_strarray *array, git_repository *repo, GIT_EXTERN(int) git_reference_foreach(git_repository *repo, unsigned int list_flags, int (*callback)(const char *, void *), void *payload); /** - * Check if a reference is packed + * Check if a reference has been loaded from a packfile * - * @param ref git_reference + * @param ref A git reference * @return 0 in case it's not packed; 1 otherwise */ GIT_EXTERN(int) git_reference_is_packed(git_reference *ref); +/** + * Reload a reference from disk + * + * Reference pointers may become outdated if the Git + * repository is accessed simultaneously by other clients + * whilt the library is open. + * + * This method forces a reload of the reference from disk, + * to ensure that the provided information is still + * reliable. + * + * If the reload fails (e.g. the reference no longer exists + * on disk, or has become corrupted), an error code will be + * returned and the reference pointer will be invalidated. + * + * @param ref The reference to reload + * @return GIT_SUCCESS on success, or an error code + */ +GIT_EXTERN(int) git_reference_reload(git_reference *ref); + /** * Free the given reference * -- cgit v1.2.1