kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

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 <mhagger@alum.mit.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
maint
Michael Haggerty 2014-10-01 12:28:24 +02:00 committed by Junio C Hamano
parent 1b1648f46b
commit d75145acf6
1 changed files with 14 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
Documentation/technical/api-lockfile.txt
View File

@ -100,6 +100,10 @@ unable_to_lock_die::


Emit an appropriate error message and `die()`. Emit an appropriate error message and `die()`.


Similarly, `commit_lock_file` and `close_lock_file` return 0 on
success. On failure they set `errno` appropriately, do their best to
roll back the lockfile, and return -1.



Flags Flags
----- -----
@ -144,18 +148,22 @@ commit_lock_file::


Take a pointer to the `struct lock_file` initialized with an Take a pointer to the `struct lock_file` initialized with an
earlier call to `hold_lock_file_for_update` or earlier call to `hold_lock_file_for_update` or
`hold_lock_file_for_append`, close the file descriptor and `hold_lock_file_for_append`, close the file descriptor, and
rename the lockfile to its final destination. Return 0 upon rename the lockfile to its final destination. Return 0 upon
success or a negative value on failure to `close(2)` or success. On failure, roll back the lock file and return -1,
`rename(2)`. It is a bug to call `commit_lock_file()` for a with `errno` set to the value from the failing call to
`lock_file` object that is not currently locked. `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:: rollback_lock_file::


Take a pointer to the `struct lock_file` initialized with an Take a pointer to the `struct lock_file` initialized with an
earlier call to `hold_lock_file_for_update` or earlier call to `hold_lock_file_for_update` or
`hold_lock_file_for_append`, close the file descriptor and `hold_lock_file_for_append`, close the file descriptor and
remove the lockfile. 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:: close_lock_file::


@ -163,7 +171,7 @@ close_lock_file::
earlier call to `hold_lock_file_for_update` or earlier call to `hold_lock_file_for_update` or
`hold_lock_file_for_append`, and close the file descriptor. `hold_lock_file_for_append`, and close the file descriptor.
Return 0 upon success. On failure to `close(2)`, return a Return 0 upon success. On failure to `close(2)`, return a
negative value and rollback the lock file. Usually negative value and roll back the lock file. Usually
`commit_lock_file` or `rollback_lock_file` should eventually `commit_lock_file` or `rollback_lock_file` should eventually
be called if `close_lock_file` succeeds. be called if `close_lock_file` succeeds.