Re: [PATCH v5 20/35] api-lockfile: document edge cases
On 09/17/2014 12:23 AM, Jonathan Nieder wrote: Michael Haggerty wrote: * Document the behavior of commit_lock_file() when it fails, namely that it rolls back the lock_file object and sets errno appropriately. * Document the behavior of rollback_lock_file() when called for a lock_file object that has already been committed or rolled back, namely that it is a NOOP. I think this would be easier to read in a separate error handling section. That way, when writing new code using the lockfile API, I can quickly find what functions to use and quickly find out what the error handling conventions are --- each use of the documentation wouldn't interfere with the other. I added a little blurb in the error handling section explaining how commit_lock_file() and close_lock_file() behave on failure, but I left the detailed information in the sections on those functions because I couldn't find a graceful way to put all of the information in the error handling sections. If you have a concrete suggestion, as they say, patches are welcome :-) Michael -- Michael Haggerty mhag...@alum.mit.edu -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v5 20/35] api-lockfile: document edge cases
* Document the behavior of commit_lock_file() when it fails, namely that it rolls back the lock_file object and sets errno appropriately. * Document the behavior of rollback_lock_file() when called for a lock_file object that has already been committed or rolled back, namely that it is a NOOP. Signed-off-by: Michael Haggerty mhag...@alum.mit.edu --- Documentation/technical/api-lockfile.txt | 17 ++--- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt index 9a94ead..2514559 100644 --- a/Documentation/technical/api-lockfile.txt +++ b/Documentation/technical/api-lockfile.txt @@ -64,19 +64,22 @@ unable_to_lock_die:: commit_lock_file:: - Take a pointer to the `struct lock_file` initialized - with an earlier call to `hold_lock_file_for_update()`, - close the file descriptor and rename the lockfile to its - final destination. Returns 0 upon success, a negative - value on failure to close(2) or rename(2). It is a bug to - call `commit_lock_file()` for a `lock_file` object that is not + Take a pointer to the `struct lock_file` initialized with an + earlier call to `hold_lock_file_for_update()`, close the file + descriptor and rename the lockfile to its final destination. + Return 0 upon success. On failure, rollback the lock file and + return -1, with `errno` set to the value from the failing call + to `close(2)` or `rename(2)`. It is a bug to call + `commit_lock_file()` for a `lock_file` object that is not currently locked. rollback_lock_file:: Take a pointer to the `struct lock_file` initialized with an earlier call to `hold_lock_file_for_update()`, - close the file descriptor and remove the lockfile. + close the file descriptor and remove the lockfile. It is a + NOOP to call `rollback_lock_file()` for a `lock_file` object + that has already been committed or rolled back. close_lock_file:: Take a pointer to the `struct lock_file` initialized -- 2.1.0 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v5 20/35] api-lockfile: document edge cases
Michael Haggerty wrote: * Document the behavior of commit_lock_file() when it fails, namely that it rolls back the lock_file object and sets errno appropriately. * Document the behavior of rollback_lock_file() when called for a lock_file object that has already been committed or rolled back, namely that it is a NOOP. I think this would be easier to read in a separate error handling section. That way, when writing new code using the lockfile API, I can quickly find what functions to use and quickly find out what the error handling conventions are --- each use of the documentation wouldn't interfere with the other. Jonathan -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
