git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v7 20/38] api-lockfile: document edge cases

From
Michael Haggerty <mhagger@alum.mit.edu>
Date
Oct 1, 2014, 10:28 UTC
Message-ID
<1412159322-2622-21-git-send-email-mhagger@alum.mit.edu>
In-Reply-To
<1412159322-2622-1-git-send-email-mhagger@alum.mit.edu>
* 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>
---
 Documentation/technical/api-lockfile.txt | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)
diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt
index d3bf940..9805da0 100644
--- a/Documentation/technical/api-lockfile.txt
+++ b/Documentation/technical/api-lockfile.txt
@@ -100,6 +100,10 @@ unable_to_lock_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
 -----
@@ -144,18 +148,22 @@ commit_lock_file::
 
 	Take a pointer to the `struct lock_file` initialized with an
 	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
-	success or 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 currently locked.
+	success. On failure, roll back 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` or
 	`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::
 
@@ -163,7 +171,7 @@ close_lock_file::
 	earlier call to `hold_lock_file_for_update` or
 	`hold_lock_file_for_append`, and close the file descriptor.
 	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
 	be called if `close_lock_file` succeeds.
 

-- 
2.1.0
Previous: Michael HaggertyNext: Michael Haggerty
Message 24 of 43 in “Lockfile correctness and refactoring”
  1. 00/38 Lockfile correctness and refactoringMichael Haggerty, Oct 1, 2014
  2. 01/38 unable_to_lock_die(): rename function from unable_to_lock_index_die()Michael Haggerty, Oct 1, 2014
  3. 02/38 api-lockfile: revise and expand the documentationMichael Haggerty, Oct 1, 2014
  4. 03/38 close_lock_file(): exit (successfully) if file is already closedMichael Haggerty, Oct 1, 2014
  5. 04/38 rollback_lock_file(): do not clear filename redundantlyMichael Haggerty, Oct 1, 2014
  6. 05/38 rollback_lock_file(): exit early if lock is not activeMichael Haggerty, Oct 1, 2014
  7. 06/38 rollback_lock_file(): set fd to -1Michael Haggerty, Oct 1, 2014
  8. 07/38 lockfile: unlock file if lockfile permissions cannot be adjustedMichael Haggerty, Oct 1, 2014
  9. 08/38 hold_lock_file_for_append(): release lock on errorsMichael Haggerty, Oct 1, 2014
  10. 09/38 lock_file(): always initialize and register lock_file objectMichael Haggerty, Oct 1, 2014
  11. René ScharfeOct 1, 2014
  12. Michael HaggertyOct 1, 2014
  13. Junio C HamanoOct 1, 2014
  14. 10/38 lockfile.c: document the various states of lock_file objectsMichael Haggerty, Oct 1, 2014
  15. 11/38 cache.h: define constants LOCK_SUFFIX and LOCK_SUFFIX_LENMichael Haggerty, Oct 1, 2014
  16. 12/38 delete_ref_loose(): don't muck around in the lock_file's filenameMichael Haggerty, Oct 1, 2014
  17. 13/38 prepare_index(): declare return value to be (const char *)Michael Haggerty, Oct 1, 2014
  18. 14/38 lock_file(): exit early if lockfile cannot be openedMichael Haggerty, Oct 1, 2014
  19. 15/38 remove_lock_file(): call rollback_lock_file()Michael Haggerty, Oct 1, 2014
  20. 16/38 commit_lock_file(): inline temporary variableMichael Haggerty, Oct 1, 2014
  21. 17/38 commit_lock_file(): die() if called for unlocked lockfile objectMichael Haggerty, Oct 1, 2014
  22. 18/38 close_lock_file(): if close fails, roll backMichael Haggerty, Oct 1, 2014
  23. 19/38 commit_lock_file(): rollback lock file on failure to renameMichael Haggerty, Oct 1, 2014
  24. 20/38 api-lockfile: document edge casesMichael Haggerty, Oct 1, 2014
  25. 21/38 dump_marks(): remove a redundant call to rollback_lock_file()Michael Haggerty, Oct 1, 2014
  26. 22/38 git_config_set_multivar_in_file(): avoid call to rollback_lock_file()Michael Haggerty, Oct 1, 2014
  27. 23/38 lockfile: avoid transitory invalid statesMichael Haggerty, Oct 1, 2014
  28. 24/38 struct lock_file: declare some fields volatileMichael Haggerty, Oct 1, 2014
  29. 25/38 try_merge_strategy(): remove redundant lock_file allocationMichael Haggerty, Oct 1, 2014
  30. 26/38 try_merge_strategy(): use a statically-allocated lock_file objectMichael Haggerty, Oct 1, 2014
  31. 27/38 commit_lock_file(): use a strbuf to manage temporary spaceMichael Haggerty, Oct 1, 2014
  32. 28/38 Change lock_file::filename into a strbufMichael Haggerty, Oct 1, 2014
  33. 29/38 resolve_symlink(): use a strbuf for internal scratch spaceMichael Haggerty, Oct 1, 2014
  34. 30/38 resolve_symlink(): take a strbuf parameterMichael Haggerty, Oct 1, 2014
  35. 31/38 trim_last_path_component(): replace last_path_elm()Michael Haggerty, Oct 1, 2014
  36. 32/38 Extract a function commit_lock_file_to()Michael Haggerty, Oct 1, 2014
  37. 33/38 Rename LOCK_NODEREF to LOCK_NO_DEREFMichael Haggerty, Oct 1, 2014
  38. 34/38 lockfile.c: rename static functionsMichael Haggerty, Oct 1, 2014
  39. 35/38 get_locked_file_path(): new functionMichael Haggerty, Oct 1, 2014
  40. 36/38 hold_lock_file_for_append(): restore errno before returningMichael Haggerty, Oct 1, 2014
  41. 37/38 Move read_index() definition to read-cache.cMichael Haggerty, Oct 1, 2014
  42. 38/38 lockfile.h: extract new header file for the functions in lockfile.cMichael Haggerty, Oct 1, 2014
  43. Junio C HamanoOct 1, 2014

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.