THIS IS A TEST INSTANCE ONLY! REPOSITORIES CAN BE DELETED AT ANY TIME!

Git Source Code Mirror - This is a publish-only repository and all pull requests are ignored. Please follow Documentation/SubmittingPatches procedure for any of your improvements.
git
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

308 lines
10KB

  1. #ifndef LOCKFILE_H
  2. #define LOCKFILE_H
  3. /*
  4. * File write-locks as used by Git.
  5. *
  6. * The lockfile API serves two purposes:
  7. *
  8. * * Mutual exclusion and atomic file updates. When we want to change
  9. * a file, we create a lockfile `<filename>.lock`, write the new
  10. * file contents into it, and then rename the lockfile to its final
  11. * destination `<filename>`. We create the `<filename>.lock` file
  12. * with `O_CREAT|O_EXCL` so that we can notice and fail if somebody
  13. * else has already locked the file, then atomically rename the
  14. * lockfile to its final destination to commit the changes and
  15. * unlock the file.
  16. *
  17. * * Automatic cruft removal. If the program exits after we lock a
  18. * file but before the changes have been committed, we want to make
  19. * sure that we remove the lockfile. This is done by remembering the
  20. * lockfiles we have created in a linked list and setting up an
  21. * `atexit(3)` handler and a signal handler that clean up the
  22. * lockfiles. This mechanism ensures that outstanding lockfiles are
  23. * cleaned up if the program exits (including when `die()` is
  24. * called) or if the program is terminated by a signal.
  25. *
  26. * Please note that lockfiles only block other writers. Readers do not
  27. * block, but they are guaranteed to see either the old contents of
  28. * the file or the new contents of the file (assuming that the
  29. * filesystem implements `rename(2)` atomically).
  30. *
  31. * Most of the heavy lifting is done by the tempfile module (see
  32. * "tempfile.h").
  33. *
  34. * Calling sequence
  35. * ----------------
  36. *
  37. * The caller:
  38. *
  39. * * Allocates a `struct lock_file` with whatever storage duration you
  40. * desire. The struct does not have to be initialized before being
  41. * used, but it is good practice to do so using by setting it to
  42. * all-zeros (or using the LOCK_INIT macro). This puts the object in a
  43. * consistent state that allows you to call rollback_lock_file() even
  44. * if the lock was never taken (in which case it is a noop).
  45. *
  46. * * Attempts to create a lockfile by calling `hold_lock_file_for_update()`.
  47. *
  48. * * Writes new content for the destination file by either:
  49. *
  50. * * writing to the file descriptor returned by the
  51. * `hold_lock_file_for_*()` functions (also available via
  52. * `lock->fd`).
  53. *
  54. * * calling `fdopen_lock_file()` to get a `FILE` pointer for the
  55. * open file and writing to the file using stdio.
  56. *
  57. * Note that the file descriptor returned by hold_lock_file_for_update()
  58. * is marked O_CLOEXEC, so the new contents must be written by the
  59. * current process, not a spawned one.
  60. *
  61. * When finished writing, the caller can:
  62. *
  63. * * Close the file descriptor and rename the lockfile to its final
  64. * destination by calling `commit_lock_file()` or
  65. * `commit_lock_file_to()`.
  66. *
  67. * * Close the file descriptor and remove the lockfile by calling
  68. * `rollback_lock_file()`.
  69. *
  70. * * Close the file descriptor without removing or renaming the
  71. * lockfile by calling `close_lock_file_gently()`, and later call
  72. * `commit_lock_file()`, `commit_lock_file_to()`,
  73. * `rollback_lock_file()`, or `reopen_lock_file()`.
  74. *
  75. * After the lockfile is committed or rolled back, the `lock_file`
  76. * object can be discarded or reused.
  77. *
  78. * If the program exits before `commit_lock_file()`,
  79. * `commit_lock_file_to()`, or `rollback_lock_file()` is called, the
  80. * tempfile module will close and remove the lockfile, thereby rolling
  81. * back any uncommitted changes.
  82. *
  83. * If you need to close the file descriptor you obtained from a
  84. * `hold_lock_file_for_*()` function yourself, do so by calling
  85. * `close_lock_file_gently()`. See "tempfile.h" for more information.
  86. *
  87. *
  88. * Under the covers, a lockfile is just a tempfile with a few helper
  89. * functions. In particular, the state diagram and the cleanup
  90. * machinery are all implemented in the tempfile module.
  91. *
  92. *
  93. * Error handling
  94. * --------------
  95. *
  96. * The `hold_lock_file_for_*()` functions return a file descriptor on
  97. * success or -1 on failure (unless `LOCK_DIE_ON_ERROR` is used; see
  98. * "flags" below). On errors, `errno` describes the reason for
  99. * failure. Errors can be reported by passing `errno` to
  100. * `unable_to_lock_message()` or `unable_to_lock_die()`.
  101. *
  102. * Similarly, `commit_lock_file`, `commit_lock_file_to`, and
  103. * `close_lock_file` return 0 on success. On failure they set `errno`
  104. * appropriately and return -1. The `commit` variants (but not `close`)
  105. * do their best to delete the temporary file before returning.
  106. */
  107. #include "tempfile.h"
  108. struct lock_file {
  109. struct tempfile *tempfile;
  110. };
  111. #define LOCK_INIT { NULL }
  112. /* String appended to a filename to derive the lockfile name: */
  113. #define LOCK_SUFFIX ".lock"
  114. #define LOCK_SUFFIX_LEN 5
  115. /*
  116. * Flags
  117. * -----
  118. *
  119. * The following flags can be passed to `hold_lock_file_for_update()`.
  120. */
  121. /*
  122. * If a lock is already taken for the file, `die()` with an error
  123. * message. If this flag is not specified, trying to lock a file that
  124. * is already locked silently returns -1 to the caller, or ...
  125. */
  126. #define LOCK_DIE_ON_ERROR 1
  127. /*
  128. * ... this flag can be passed instead to return -1 and give the usual
  129. * error message upon an error.
  130. */
  131. #define LOCK_REPORT_ON_ERROR 4
  132. /*
  133. * Usually symbolic links in the destination path are resolved. This
  134. * means that (1) the lockfile is created by adding ".lock" to the
  135. * resolved path, and (2) upon commit, the resolved path is
  136. * overwritten. However, if `LOCK_NO_DEREF` is set, then the lockfile
  137. * is created by adding ".lock" to the path argument itself. This
  138. * option is used, for example, when detaching a symbolic reference,
  139. * which for backwards-compatibility reasons, can be a symbolic link
  140. * containing the name of the referred-to-reference.
  141. */
  142. #define LOCK_NO_DEREF 2
  143. /*
  144. * Attempt to create a lockfile for the file at `path` and return a
  145. * file descriptor for writing to it, or -1 on error. If the file is
  146. * currently locked, retry with quadratic backoff for at least
  147. * timeout_ms milliseconds. If timeout_ms is 0, try exactly once; if
  148. * timeout_ms is -1, retry indefinitely. The flags argument and error
  149. * handling are described above.
  150. */
  151. int hold_lock_file_for_update_timeout(
  152. struct lock_file *lk, const char *path,
  153. int flags, long timeout_ms);
  154. /*
  155. * Attempt to create a lockfile for the file at `path` and return a
  156. * file descriptor for writing to it, or -1 on error. The flags
  157. * argument and error handling are described above.
  158. */
  159. static inline int hold_lock_file_for_update(
  160. struct lock_file *lk, const char *path,
  161. int flags)
  162. {
  163. return hold_lock_file_for_update_timeout(lk, path, flags, 0);
  164. }
  165. /*
  166. * Return a nonzero value iff `lk` is currently locked.
  167. */
  168. static inline int is_lock_file_locked(struct lock_file *lk)
  169. {
  170. return is_tempfile_active(lk->tempfile);
  171. }
  172. /*
  173. * Append an appropriate error message to `buf` following the failure
  174. * of `hold_lock_file_for_update()` to lock `path`. `err` should be the
  175. * `errno` set by the failing call.
  176. */
  177. void unable_to_lock_message(const char *path, int err,
  178. struct strbuf *buf);
  179. /*
  180. * Emit an appropriate error message and `die()` following the failure
  181. * of `hold_lock_file_for_update()` to lock `path`. `err` should be the
  182. * `errno` set by the failing
  183. * call.
  184. */
  185. NORETURN void unable_to_lock_die(const char *path, int err);
  186. /*
  187. * Associate a stdio stream with the lockfile (which must still be
  188. * open). Return `NULL` (*without* rolling back the lockfile) on
  189. * error. The stream is closed automatically when
  190. * `close_lock_file_gently()` is called or when the file is committed or
  191. * rolled back.
  192. */
  193. static inline FILE *fdopen_lock_file(struct lock_file *lk, const char *mode)
  194. {
  195. return fdopen_tempfile(lk->tempfile, mode);
  196. }
  197. /*
  198. * Return the path of the lockfile. The return value is a pointer to a
  199. * field within the lock_file object and should not be freed.
  200. */
  201. static inline const char *get_lock_file_path(struct lock_file *lk)
  202. {
  203. return get_tempfile_path(lk->tempfile);
  204. }
  205. static inline int get_lock_file_fd(struct lock_file *lk)
  206. {
  207. return get_tempfile_fd(lk->tempfile);
  208. }
  209. static inline FILE *get_lock_file_fp(struct lock_file *lk)
  210. {
  211. return get_tempfile_fp(lk->tempfile);
  212. }
  213. /*
  214. * Return the path of the file that is locked by the specified
  215. * lock_file object. The caller must free the memory.
  216. */
  217. char *get_locked_file_path(struct lock_file *lk);
  218. /*
  219. * If the lockfile is still open, close it (and the file pointer if it
  220. * has been opened using `fdopen_lock_file()`) without renaming the
  221. * lockfile over the file being locked. Return 0 upon success. On
  222. * failure to `close(2)`, return a negative value (the lockfile is not
  223. * rolled back). Usually `commit_lock_file()`, `commit_lock_file_to()`,
  224. * or `rollback_lock_file()` should eventually be called.
  225. */
  226. static inline int close_lock_file_gently(struct lock_file *lk)
  227. {
  228. return close_tempfile_gently(lk->tempfile);
  229. }
  230. /*
  231. * Re-open a lockfile that has been closed using `close_lock_file_gently()`
  232. * but not yet committed or rolled back. This can be used to implement
  233. * a sequence of operations like the following:
  234. *
  235. * * Lock file.
  236. *
  237. * * Write new contents to lockfile, then `close_lock_file_gently()` to
  238. * cause the contents to be written to disk.
  239. *
  240. * * Pass the name of the lockfile to another program to allow it (and
  241. * nobody else) to inspect the contents you wrote, while still
  242. * holding the lock yourself.
  243. *
  244. * * `reopen_lock_file()` to reopen the lockfile, truncating the existing
  245. * contents. Write out the new contents.
  246. *
  247. * * `commit_lock_file()` to make the final version permanent.
  248. */
  249. static inline int reopen_lock_file(struct lock_file *lk)
  250. {
  251. return reopen_tempfile(lk->tempfile);
  252. }
  253. /*
  254. * Commit the change represented by `lk`: close the file descriptor
  255. * and/or file pointer if they are still open and rename the lockfile
  256. * to its final destination. Return 0 upon success. On failure, roll
  257. * back the lock file and return -1, with `errno` set to the value
  258. * from the failing call to `close(2)` or `rename(2)`. It is a bug to
  259. * call `commit_lock_file()` for a `lock_file` object that is not
  260. * currently locked.
  261. */
  262. int commit_lock_file(struct lock_file *lk);
  263. /*
  264. * Like `commit_lock_file()`, but rename the lockfile to the provided
  265. * `path`. `path` must be on the same filesystem as the lock file.
  266. */
  267. static inline int commit_lock_file_to(struct lock_file *lk, const char *path)
  268. {
  269. return rename_tempfile(&lk->tempfile, path);
  270. }
  271. /*
  272. * Roll back `lk`: close the file descriptor and/or file pointer and
  273. * remove the lockfile. It is a NOOP to call `rollback_lock_file()`
  274. * for a `lock_file` object that has already been committed or rolled
  275. * back.
  276. */
  277. static inline void rollback_lock_file(struct lock_file *lk)
  278. {
  279. delete_tempfile(&lk->tempfile);
  280. }
  281. #endif /* LOCKFILE_H */