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>
Michael Haggerty committed
Oct 1, 2014 at 12:28 UTC
d75145acf6d17eb9b0f9d7d8856e523038081311
1 file changed
+14
-6
Documentation/technical/api-lockfile.txt
+14
-6
@@ -100,6 +100,10 @@ unable_to_lock_die::
100
101
Emit an appropriate error message and `die()`.
102
103
+Similarly, `commit_lock_file` and `close_lock_file` return 0 on
104
+success. On failure they set `errno` appropriately, do their best to
105
+roll back the lockfile, and return -1.
106
+
107
108
Flags
109
-----
@@ -144,18 +148,22 @@ commit_lock_file::
148
149
Take a pointer to the `struct lock_file` initialized with an
150
earlier call to `hold_lock_file_for_update` or
147
- `hold_lock_file_for_append`, close the file descriptor and
151
+ `hold_lock_file_for_append`, close the file descriptor, and
152
rename the lockfile to its final destination. Return 0 upon
149
- success or a negative value on failure to `close(2)` or
150
- `rename(2)`. It is a bug to call `commit_lock_file()` for a
151
- `lock_file` object that is not currently locked.
153
+ success. On failure, roll back the lock file and return -1,
154
+ with `errno` set to the value from the failing call to
155
+ `close(2)` or `rename(2)`. It is a bug to call
156
+ `commit_lock_file` for a `lock_file` object that is not
157
+ currently locked.
158
159
rollback_lock_file::
160
161
Take a pointer to the `struct lock_file` initialized with an
162
earlier call to `hold_lock_file_for_update` or
163
`hold_lock_file_for_append`, close the file descriptor and
158
- remove the lockfile.
164
+ remove the lockfile. It is a NOOP to call
165
+ `rollback_lock_file()` for a `lock_file` object that has
166
+ already been committed or rolled back.
167
168
close_lock_file::
169
@@ -163,7 +171,7 @@ close_lock_file::
171
earlier call to `hold_lock_file_for_update` or
172
`hold_lock_file_for_append`, and close the file descriptor.
173
Return 0 upon success. On failure to `close(2)`, return a
166
- negative value and rollback the lock file. Usually
174
+ negative value and roll back the lock file. Usually
175
`commit_lock_file` or `rollback_lock_file` should eventually
176
be called if `close_lock_file` succeeds.
177