development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-10-01 06:05:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

refs: document the lifetime of the args passed to each_ref_fn

Browse source 
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>
This commit is contained in:
Michael Haggerty 2013-05-25 11:08:24 +02:00 committed by Junio C Hamano
parent bf42772e38
commit 4f78c24c63
1 changed files with 16 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
refs.h
View file

@ -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 *);