@matheusbsbs / matheus-bagliano / commits / 4f78c24c63

refs: document the lifetime of the args passed to each_ref_fn

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> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Michael Haggerty committed May 25, 2013 at 11:08 UTC 4f78c24c63bf0b035afc02372727a3b5897d9835
1 file changed +16 -6
refs.h
+16 -6
@@ -15,13 +15,23 @@ struct ref_lock {
15 #define REF_ISBROKEN 0x04
16
17 /*
18 - * Calls the specified function for each ref file until it returns
19 - * nonzero, and returns the value. Please note that it is not safe to
20 - * modify references while an iteration is in progress, unless the
21 - * same callback function invocation that modifies the reference also
22 - * returns a nonzero value to immediately stop the iteration.
18 + * The signature for the callback function for the for_each_*()
19 + * functions below. The memory pointed to by the refname and sha1
20 + * arguments is only guaranteed to be valid for the duration of a
21 + * single callback invocation.
22 + */
23 +typedef int each_ref_fn(const char *refname,
24 + const unsigned char *sha1, int flags, void *cb_data);
25 +
26 +/*
27 + * The following functions invoke the specified callback function for
28 + * each reference indicated. If the function ever returns a nonzero
29 + * value, stop the iteration and return that value. Please note that
30 + * it is not safe to modify references while an iteration is in
31 + * progress, unless the same callback function invocation that
32 + * modifies the reference also returns a nonzero value to immediately
33 + * stop the iteration.
34 */
24 -typedef int each_ref_fn(const char *refname, const unsigned char *sha1, int flags, void *cb_data);
35 extern int head_ref(each_ref_fn, void *);
36 extern int for_each_ref(each_ref_fn, void *);
37 extern int for_each_ref_in(const char *, each_ref_fn, void *);