util.h

Show log
Commit

Hash : fa59f18d
Author :
Date : 2011-05-09T20:54:04

Change error handling mechanism once again

Ok, this is the real deal. Hopefully. Here's how it's going to work:

- One main method, called `git__throw`, that sets the error
	code and error message when an error happens.

	This method must be called in every single place where an error
	code was being returned previously, setting an error message
	instead.

	Example, instead of:

		return GIT_EOBJCORRUPTED;

	Use:

		return git__throw(GIT_EOBJCORRUPTED,
			"The object is missing a finalizing line feed");

	And instead of:

		[...] {
			error = GIT_EOBJCORRUPTED;
			goto cleanup;
		}

	Use:

		[...] {
			error = git__throw(GIT_EOBJCORRUPTED, "What an error!");
			goto cleanup;
		}

	The **only** exception to this are the allocation methods, which
	return NULL on failure but already set the message manually.

		/* only place where an error code can be returned directly,
		   because the error message has already been set by the wrapper */
		if (foo == NULL)
			return GIT_ENOMEM;

- One secondary method, called `git__rethrow`, which can be used to
fine-grain an error message and build an error stack.

	Example, instead of:

		if ((error = foobar(baz)) < GIT_SUCCESS)
			return error;

	You can now do:

		if ((error = foobar(baz)) < GIT_SUCCESS)
			return git__rethrow(error, "Failed to do a major operation");

	The return of the `git_lasterror` method will be a string in the
	shape of:

		"Failed to do a major operation. (Failed to do an internal
		operation)"

	E.g.

		"Failed to open the index. (Not enough permissions to access
		'/path/to/index')."

	NOTE: do not abuse this method. Try to write all `git__throw`
	messages in a descriptive manner, to avoid having to rethrow them to
	clarify their meaning.

	This method should only be used in the places where the original
	error message set by a subroutine is not specific enough.

	It is encouraged to continue using this style as much possible to
	enforce error propagation:

		if ((error = foobar(baz)) < GIT_SUCCESS)
			return error; /* `foobar` has set an error message, and
							 we are just propagating it */

The error handling revamp will take place in two phases:

	- Phase 1: Replace all pieces of code that return direct error codes
	with calls to `git__throw`. This can be done semi-automatically
	using `ack` to locate all the error codes that must be replaced.

	- Phase 2: Add some `git__rethrow` calls in those cases where the
	original error messages are not specific enough.

Phase 1 is the main goal. A minor libgit2 release will be shipped once
Phase 1 is ready, and the work will start on gradually improving the
error handling mechanism by refining specific error messages.

OTHER NOTES:

	- When writing error messages, please refrain from using weasel
	words. They add verbosity to the message without giving any real
	information. (<3 Emeric)

	E.g.

		"The reference file appears to be missing a carriage return"
			Nope.

		"The reference file is missing a carriage return"
			Yes.

	- When calling `git__throw`, please try to use more generic error
	codes so we can eventually reduce the list of error codes to
	something more reasonable. Feel free to add new, more generic error
	codes if these are going to replace several of the old ones.

	E.g.

		return GIT_EREFCORRUPTED;

	Can be turned into:

		return git__throw(GIT_EOBJCORRUPTED,
			"The reference is corrupted");

Download

src/util.h

#ifndef INCLUDE_util_h__
#define INCLUDE_util_h__

#define ARRAY_SIZE(x) (sizeof(x)/sizeof(x[0]))
#define bitsizeof(x)  (CHAR_BIT * sizeof(x))
#define MSB(x, bits) ((x) & (~0ULL << (bitsizeof(x) - (bits))))

/* 
 * Custom memory allocation wrappers
 * that set error code and error message
 * on allocation failure
 */
GIT_INLINE(void *) git__malloc(size_t len)
{
	void *ptr = malloc(len);
	if (!ptr)
		git__throw(GIT_ENOMEM, "Out of memory. Failed to allocate %d bytes.", (int)len);
	return ptr;
}

GIT_INLINE(void *) git__calloc(size_t nelem, size_t elsize)
{
	void *ptr = calloc(nelem, elsize);
	if (!ptr)
		git__throw(GIT_ENOMEM, "Out of memory. Failed to allocate %d bytes.", (int)elsize);
	return ptr;
}

GIT_INLINE(char *) git__strdup(const char *str)
{
	char *ptr = strdup(str);
	if (!ptr)
		git__throw(GIT_ENOMEM, "Out of memory. Failed to duplicate string");
	return ptr;
}

GIT_INLINE(void *) git__realloc(void *ptr, size_t size)
{
	void *new_ptr = realloc(ptr, size);
	if (!new_ptr)
		git__throw(GIT_ENOMEM, "Out of memory. Failed to allocate %d bytes.", (int)size);
	return new_ptr;
}

extern int git__fmt(char *, size_t, const char *, ...)
	GIT_FORMAT_PRINTF(3, 4);
extern int git__prefixcmp(const char *str, const char *prefix);
extern int git__suffixcmp(const char *str, const char *suffix);

extern int git__strtol32(long *n, const char *buff, const char **end_buf, int base);

/*
 * The dirname() function shall take a pointer to a character string
 * that contains a pathname, and return a pointer to a string that is a
 * pathname of the parent directory of that file. Trailing '/' characters
 * in the path are not counted as part of the path.
 *
 * If path does not contain a '/', then dirname() shall return a pointer to
 * the string ".". If path is a null pointer or points to an empty string,
 * dirname() shall return a pointer to the string "." .
 *
 * The `git__dirname` implementation is thread safe. The returned 
 * string must be manually free'd.
 *
 * The `git__dirname_r` implementation expects a string allocated
 * by the user with big enough size.
 */
extern char *git__dirname(const char *path);
extern int git__dirname_r(char *buffer, size_t bufflen, const char *path);

/*
 * This function returns the basename of the file, which is the last
 * part of its full name given by fname, with the drive letter and
 * leading directories stripped off. For example, the basename of
 * c:/foo/bar/file.ext is file.ext, and the basename of a:foo is foo.
 *
 * Trailing slashes and backslashes are significant: the basename of
 * c:/foo/bar/ is an empty string after the rightmost slash.
 *
 * The `git__basename` implementation is thread safe. The returned 
 * string must be manually free'd.
 *
 * The `git__basename_r` implementation expects a string allocated
 * by the user with big enough size.
 */
extern char *git__basename(const char *path);
extern int git__basename_r(char *buffer, size_t bufflen, const char *path);

extern const char *git__topdir(const char *path);

/**
 * Join two paths together. Takes care of properly fixing the
 * middle slashes and everything
 *
 * The paths are joined together into buffer_out; this is expected
 * to be an user allocated buffer of `GIT_PATH_MAX` size 
 */
extern void git__joinpath_n(char *buffer_out, int npath, ...);

GIT_INLINE(void) git__joinpath(char *buffer_out, const char *path_a, const char *path_b)
{
	git__joinpath_n(buffer_out, 2, path_a, path_b);
}

extern void git__hexdump(const char *buffer, size_t n);
extern uint32_t git__hash(const void *key, int len, uint32_t seed);


/** @return true if p fits into the range of a size_t */
GIT_INLINE(int) git__is_sizet(git_off_t p)
{
	size_t r = (size_t)p;
	return p == (git_off_t)r;
}

/* 32-bit cross-platform rotl */
#ifdef _MSC_VER /* use built-in method in MSVC */
#	define git__rotl(v, s) (uint32_t)_rotl(v, s)
#else /* use bitops in GCC; with o2 this gets optimized to a rotl instruction */
#	define git__rotl(v, s) (uint32_t)(((uint32_t)(v) << (s)) | ((uint32_t)(v) >> (32 - (s))))
#endif

extern char *git__strtok(char *output, char *src, char *delimit);
extern char *git__strtok_keep(char *output, char *src, char *delimit);

#define STRLEN(str) (sizeof(str) - 1)

#define GIT_OID_LINE_LENGTH(header) (STRLEN(header) + 1 + GIT_OID_HEXSZ + 1)

/*
 * Realloc the buffer pointed at by variable 'x' so that it can hold
 * at least 'nr' entries; the number of entries currently allocated
 * is 'alloc', using the standard growing factor alloc_nr() macro.
 *
 * DO NOT USE any expression with side-effect for 'x' or 'alloc'.
 */
#define alloc_nr(x) (((x)+16)*3/2)
#define ALLOC_GROW(x, nr, alloc) \
	do { \
		if ((nr) > alloc) { \
			if (alloc_nr(alloc) < (nr)) \
				alloc = (nr); \
			else \
				alloc = alloc_nr(alloc); \
			x = xrealloc((x), alloc * sizeof(*(x))); \
		} \
	} while (0)

#endif /* INCLUDE_util_h__ */

Download

thodg/libgit2/src/util.h

Commit

src/util.h