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
parent
1b1648f46b
commit
d75145acf6
|
@ -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.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue