[PATCH v2 25/25] refs: document the lifetime of the args passed to each_ref_fn
- From
Michael Haggerty <mhagger@alum.mit.edu>
- Date
- May 25, 2013, 09:08 UTC
- Message-ID
- <1369472904-12875-26-git-send-email-mhagger@alum.mit.edu>
- In-Reply-To
- <1369472904-12875-1-git-send-email-mhagger@alum.mit.edu>
The lifetime of the memory pointed to by the refname and sha1 arguments to each_ref_fn was never documented, but some callers used to assume that it was essentially permanent. In fact the API does *not* guarantee that these objects live beyond a single callback invocation.
In the current code, the lifetimes are bound together with the lifetimes of the ref_caches. Since these are usually long, the callers usually got away with their sloppiness. But even today, if a ref_cache is invalidated the memory can be freed. And planned changes to reference caching, needed to eliminate race conditions, will probably need to shorten the lifetimes of these objects.
The commits leading up to this have (hopefully) fixed all of the callers of the for_each_ref()-like functions. This commit does the last step: documents what each_ref_fn callbacks can assume about object lifetimes.
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> --- refs.h | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-)
diff --git a/refs.h b/refs.h index a35eafc..122ec03 100644 --- a/refs.h +++ b/refs.h @@ -15,13 +15,23 @@ struct ref_lock { #define REF_ISBROKEN 0x04 /* - * Calls the specified function for each ref file until it returns - * nonzero, and returns the value. Please note that it is not safe to - * modify references while an iteration is in progress, unless the - * same callback function invocation that modifies the reference also - * returns a nonzero value to immediately stop the iteration. + * The signature for the callback function for the for_each_*() + * functions below. The memory pointed to by the refname and sha1 + * arguments is only guaranteed to be valid for the duration of a + * single callback invocation. + */ +typedef int each_ref_fn(const char *refname, + const unsigned char *sha1, int flags, void *cb_data); + +/* + * The following functions invoke the specified callback function for + * each reference indicated. If the function ever returns a nonzero + * value, stop the iteration and return that value. Please note that + * it is not safe to modify references while an iteration is in + * progress, unless the same callback function invocation that + * modifies the reference also returns a nonzero value to immediately + * stop the iteration. */ -typedef int each_ref_fn(const char *refname, const unsigned char *sha1, int flags, void *cb_data); extern int head_ref(each_ref_fn, void *); extern int for_each_ref(each_ref_fn, void *); extern int for_each_ref_in(const char *, each_ref_fn, void *);
-- 1.8.2.3