PageRenderTime 126ms CodeModel.GetById 107ms app.highlight 16ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/error-handling.md

https://github.com/kdh8544/libgit2
Markdown | 111 lines | 73 code | 38 blank | 0 comment | 0 complexity | 53aa5f6e15505d025e688ab28877476e MD5 | raw file
  1Error reporting in libgit2
  2==========================
  3
  4Error reporting is performed on an explicit `git_error **` argument, which appears at the end of all API calls that can return an error. Yes, this does clutter the API.
  5
  6When a function fails, an error is set on the error variable **and** returns one of the generic error codes.
  7
  8~~~c
  9int git_repository_open(git_repository **repository, const char *path, git_error **error)
 10{
 11	// perform some opening
 12	if (p_exists(path) < 0) {
 13		giterr_set(error, GITERR_REPOSITORY, "The path '%s' doesn't exist", path);
 14		return GIT_ENOTFOUND;
 15	}
 16
 17	...
 18
 19	if (try_to_parse(path, error) < 0)
 20		return GIT_ERROR;
 21
 22	...
 23}
 24~~~
 25
 26The simple error API
 27--------------------
 28
 29- `void giterr_set(git_error **, int, const char *, ...)`: the main function used to set an error. It allocates a new error object and stores it in the passed error pointer. It has no return value. The arguments for `giterr_set` are as follows:
 30
 31	- `git_error **error_ptr`: the pointer where the error will be created.
 32	- `int error_class`: the class for the error. This is **not** an error code: this is an specific enum that specifies the error family. The point is to map these families 1-1 with Exception types on higher level languages (e.g. GitRepositoryException)
 33	- `const char *error_str, ...`: the error string, with optional formatting arguments
 34
 35- `void giterr_free(git_error *)`: takes an error and frees it. This function is available in the external API.
 36
 37- `void giterr_clear(git_error **)`: clears an error previously set in an error pointer, setting it to NULL and calling `giterr_free` on it.
 38
 39- `void giterr_propagate(git_error **, git_error *)`: moves an error to a given error pointer, handling the case when the error pointer is NULL (in that case the error gets freed, because it cannot be propagated).
 40
 41The new error code return values
 42--------------------------------
 43
 44We are doing this the POSIX way: one error code for each "expected failure", and a generic error code for all the critical failures.
 45
 46For instance: A reference lookup can have an expected failure (which is when the reference cannot be found), and a critical failure (which could be any of a long list of things that could go wrong, such as the refs packfile being corrupted, a loose ref being written with the wrong permissions, etc). We cannot have distinct error codes for every single error in the library, hence `git_reference_lookup` would return GIT_SUCCESS if the operation was successful, GIT_ENOTFOUND when the reference doesn't exist, and GIT_ERROR when an error happens -- **the error is then detailed in the `git_error` parameter**.
 47
 48Please be smart when returning error codes. Functions have max two "expected errors", and in most cases only one.
 49
 50Writing error messages
 51----------------------
 52
 53Here are some guidelines when writing error messages:
 54
 55- Use proper English, and an impersonal or past tenses: *The given path does not exist*, *Failed to lookup object in ODB*
 56
 57- Use short, direct and objective messages. **One line, max**. libgit2 is a low level library: think that all the messages reported will be thrown as Ruby or Python exceptions. Think how long are common exception messages in those languages.
 58
 59- **Do not add redundant information to the error message**, specially information that can be inferred from the context.
 60
 61	E.g. in `git_repository_open`, do not report a message like "Failed to open repository: path not found". Somebody is
 62	calling that function. If it fails, he already knows that the repository failed to open!
 63
 64General guidelines for error reporting
 65--------------------------------------
 66
 67- We never handle programming errors with these functions. Programming errors are `assert`ed, and when their source is internal, fixed as soon as possible. This is C, people.
 68
 69	Example of programming errors that would **not** be handled: passing NULL to a function that expects a valid pointer; passing a `git_tree` to a function that expects a `git_commit`. All these cases need to be identified with `assert` and fixed asap.
 70
 71	Example of a runtime error: failing to parse a `git_tree` because it contains invalid data. Failing to open a file because it doesn't exist on disk. These errors would be handled, and a `git_error` would be set.
 72
 73- The `git_error **` argument is always the last in the signature of all API calls. No exceptions.
 74
 75- When the programmer (or us, internally) doesn't need error handling, he can pass `NULL` to the `git_error **` param. This means that the errors won't be *reported*, but obviously they still will be handled (i.e. the failing function will interrupt and return cleanly). This is transparently handled by `giterr_set`
 76
 77- `git_error *` **must be initialized to `NULL` before passing its value to a function!!**
 78
 79	~~~c
 80	git_error *err;
 81	git_error *good_error = NULL;
 82
 83	git_foo_func(arg1, arg2, &error); // invalid: `error` is not initialized
 84	git_foo_func2(arg1, arg2, &good_error); // OK!
 85	git_foo_func3(arg1, arg2, NULL); // OK! But no error reporting!
 86	~~~
 87
 88- Piling up errors is an error! Don't do this! Errors must always be free'd when a function returns.
 89
 90	~~~c
 91	git_error *error = NULL;
 92
 93	git_foo_func1(arg1, &error);
 94	git_foo_func2(arg2, &error); // WRONG! What if func1 failed? `error` would leak!
 95	~~~
 96
 97- Likewise: do not rethrow errors internally!
 98
 99	~~~c
100	int git_commit_create(..., git_error **error)
101	{
102		if (git_reference_exists("HEAD", error) < 0) {
103			/* HEAD does not exist; create it so we can commit... */
104			if (git_reference_create("HEAD", error) < 0) {
105				/* error could be rethrown */
106			}
107		}
108
109- Remember that errors are now allocated, and hence they need to be free'd after they've been used. Failure to do so internally (e.g. in the already seen examples of error piling) will be reported by Valgrind, so we can easily find where are we rethrowing errors.
110
111- Remember that any function that fails **will set an error object**, and that object will be freed.