From 1b593e1ea4d2af0f6444d9a7788d5d99abd6fde5 Mon Sep 17 00:00:00 2001 From: Vincent Ambo Date: Sat, 11 Jan 2020 23:36:56 +0000 Subject: Squashed 'third_party/git/' content from commit cb71568594 git-subtree-dir: third_party/git git-subtree-split: cb715685942260375e1eb8153b0768a376e4ece7 --- lockfile.h | 307 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 307 insertions(+) create mode 100644 lockfile.h (limited to 'lockfile.h') diff --git a/lockfile.h b/lockfile.h new file mode 100644 index 000000000000..9843053ce894 --- /dev/null +++ b/lockfile.h @@ -0,0 +1,307 @@ +#ifndef LOCKFILE_H +#define LOCKFILE_H + +/* + * File write-locks as used by Git. + * + * The lockfile API serves two purposes: + * + * * Mutual exclusion and atomic file updates. When we want to change + * a file, we create a lockfile `.lock`, write the new + * file contents into it, and then rename the lockfile to its final + * destination ``. We create the `.lock` file + * with `O_CREAT|O_EXCL` so that we can notice and fail if somebody + * else has already locked the file, then atomically rename the + * lockfile to its final destination to commit the changes and + * unlock the file. + * + * * Automatic cruft removal. If the program exits after we lock a + * file but before the changes have been committed, we want to make + * sure that we remove the lockfile. This is done by remembering the + * lockfiles we have created in a linked list and setting up an + * `atexit(3)` handler and a signal handler that clean up the + * lockfiles. This mechanism ensures that outstanding lockfiles are + * cleaned up if the program exits (including when `die()` is + * called) or if the program is terminated by a signal. + * + * Please note that lockfiles only block other writers. Readers do not + * block, but they are guaranteed to see either the old contents of + * the file or the new contents of the file (assuming that the + * filesystem implements `rename(2)` atomically). + * + * Most of the heavy lifting is done by the tempfile module (see + * "tempfile.h"). + * + * Calling sequence + * ---------------- + * + * The caller: + * + * * Allocates a `struct lock_file` with whatever storage duration you + * desire. The struct does not have to be initialized before being + * used, but it is good practice to do so using by setting it to + * all-zeros (or using the LOCK_INIT macro). This puts the object in a + * consistent state that allows you to call rollback_lock_file() even + * if the lock was never taken (in which case it is a noop). + * + * * Attempts to create a lockfile by calling `hold_lock_file_for_update()`. + * + * * Writes new content for the destination file by either: + * + * * writing to the file descriptor returned by the + * `hold_lock_file_for_*()` functions (also available via + * `lock->fd`). + * + * * calling `fdopen_lock_file()` to get a `FILE` pointer for the + * open file and writing to the file using stdio. + * + * Note that the file descriptor returned by hold_lock_file_for_update() + * is marked O_CLOEXEC, so the new contents must be written by the + * current process, not a spawned one. + * + * When finished writing, the caller can: + * + * * Close the file descriptor and rename the lockfile to its final + * destination by calling `commit_lock_file()` or + * `commit_lock_file_to()`. + * + * * Close the file descriptor and remove the lockfile by calling + * `rollback_lock_file()`. + * + * * Close the file descriptor without removing or renaming the + * lockfile by calling `close_lock_file_gently()`, and later call + * `commit_lock_file()`, `commit_lock_file_to()`, + * `rollback_lock_file()`, or `reopen_lock_file()`. + * + * After the lockfile is committed or rolled back, the `lock_file` + * object can be discarded or reused. + * + * If the program exits before `commit_lock_file()`, + * `commit_lock_file_to()`, or `rollback_lock_file()` is called, the + * tempfile module will close and remove the lockfile, thereby rolling + * back any uncommitted changes. + * + * If you need to close the file descriptor you obtained from a + * `hold_lock_file_for_*()` function yourself, do so by calling + * `close_lock_file_gently()`. See "tempfile.h" for more information. + * + * + * Under the covers, a lockfile is just a tempfile with a few helper + * functions. In particular, the state diagram and the cleanup + * machinery are all implemented in the tempfile module. + * + * + * Error handling + * -------------- + * + * The `hold_lock_file_for_*()` functions return a file descriptor on + * success or -1 on failure (unless `LOCK_DIE_ON_ERROR` is used; see + * "flags" below). On errors, `errno` describes the reason for + * failure. Errors can be reported by passing `errno` to + * `unable_to_lock_message()` or `unable_to_lock_die()`. + * + * Similarly, `commit_lock_file`, `commit_lock_file_to`, and + * `close_lock_file` return 0 on success. On failure they set `errno` + * appropriately and return -1. The `commit` variants (but not `close`) + * do their best to delete the temporary file before returning. + */ + +#include "tempfile.h" + +struct lock_file { + struct tempfile *tempfile; +}; + +#define LOCK_INIT { NULL } + +/* String appended to a filename to derive the lockfile name: */ +#define LOCK_SUFFIX ".lock" +#define LOCK_SUFFIX_LEN 5 + + +/* + * Flags + * ----- + * + * The following flags can be passed to `hold_lock_file_for_update()`. + */ + +/* + * If a lock is already taken for the file, `die()` with an error + * message. If this flag is not specified, trying to lock a file that + * is already locked silently returns -1 to the caller, or ... + */ +#define LOCK_DIE_ON_ERROR 1 + +/* + * ... this flag can be passed instead to return -1 and give the usual + * error message upon an error. + */ +#define LOCK_REPORT_ON_ERROR 4 + +/* + * Usually symbolic links in the destination path are resolved. This + * means that (1) the lockfile is created by adding ".lock" to the + * resolved path, and (2) upon commit, the resolved path is + * overwritten. However, if `LOCK_NO_DEREF` is set, then the lockfile + * is created by adding ".lock" to the path argument itself. This + * option is used, for example, when detaching a symbolic reference, + * which for backwards-compatibility reasons, can be a symbolic link + * containing the name of the referred-to-reference. + */ +#define LOCK_NO_DEREF 2 + +/* + * Attempt to create a lockfile for the file at `path` and return a + * file descriptor for writing to it, or -1 on error. If the file is + * currently locked, retry with quadratic backoff for at least + * timeout_ms milliseconds. If timeout_ms is 0, try exactly once; if + * timeout_ms is -1, retry indefinitely. The flags argument and error + * handling are described above. + */ +int hold_lock_file_for_update_timeout( + struct lock_file *lk, const char *path, + int flags, long timeout_ms); + +/* + * Attempt to create a lockfile for the file at `path` and return a + * file descriptor for writing to it, or -1 on error. The flags + * argument and error handling are described above. + */ +static inline int hold_lock_file_for_update( + struct lock_file *lk, const char *path, + int flags) +{ + return hold_lock_file_for_update_timeout(lk, path, flags, 0); +} + +/* + * Return a nonzero value iff `lk` is currently locked. + */ +static inline int is_lock_file_locked(struct lock_file *lk) +{ + return is_tempfile_active(lk->tempfile); +} + +/* + * Append an appropriate error message to `buf` following the failure + * of `hold_lock_file_for_update()` to lock `path`. `err` should be the + * `errno` set by the failing call. + */ +void unable_to_lock_message(const char *path, int err, + struct strbuf *buf); + +/* + * Emit an appropriate error message and `die()` following the failure + * of `hold_lock_file_for_update()` to lock `path`. `err` should be the + * `errno` set by the failing + * call. + */ +NORETURN void unable_to_lock_die(const char *path, int err); + +/* + * Associate a stdio stream with the lockfile (which must still be + * open). Return `NULL` (*without* rolling back the lockfile) on + * error. The stream is closed automatically when + * `close_lock_file_gently()` is called or when the file is committed or + * rolled back. + */ +static inline FILE *fdopen_lock_file(struct lock_file *lk, const char *mode) +{ + return fdopen_tempfile(lk->tempfile, mode); +} + +/* + * Return the path of the lockfile. The return value is a pointer to a + * field within the lock_file object and should not be freed. + */ +static inline const char *get_lock_file_path(struct lock_file *lk) +{ + return get_tempfile_path(lk->tempfile); +} + +static inline int get_lock_file_fd(struct lock_file *lk) +{ + return get_tempfile_fd(lk->tempfile); +} + +static inline FILE *get_lock_file_fp(struct lock_file *lk) +{ + return get_tempfile_fp(lk->tempfile); +} + +/* + * Return the path of the file that is locked by the specified + * lock_file object. The caller must free the memory. + */ +char *get_locked_file_path(struct lock_file *lk); + +/* + * If the lockfile is still open, close it (and the file pointer if it + * has been opened using `fdopen_lock_file()`) without renaming the + * lockfile over the file being locked. Return 0 upon success. On + * failure to `close(2)`, return a negative value (the lockfile is not + * rolled back). Usually `commit_lock_file()`, `commit_lock_file_to()`, + * or `rollback_lock_file()` should eventually be called. + */ +static inline int close_lock_file_gently(struct lock_file *lk) +{ + return close_tempfile_gently(lk->tempfile); +} + +/* + * Re-open a lockfile that has been closed using `close_lock_file_gently()` + * but not yet committed or rolled back. This can be used to implement + * a sequence of operations like the following: + * + * * Lock file. + * + * * Write new contents to lockfile, then `close_lock_file_gently()` to + * cause the contents to be written to disk. + * + * * Pass the name of the lockfile to another program to allow it (and + * nobody else) to inspect the contents you wrote, while still + * holding the lock yourself. + * + * * `reopen_lock_file()` to reopen the lockfile, truncating the existing + * contents. Write out the new contents. + * + * * `commit_lock_file()` to make the final version permanent. + */ +static inline int reopen_lock_file(struct lock_file *lk) +{ + return reopen_tempfile(lk->tempfile); +} + +/* + * Commit the change represented by `lk`: close the file descriptor + * and/or file pointer if they are still open and rename the lockfile + * to its final destination. Return 0 upon 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. + */ +int commit_lock_file(struct lock_file *lk); + +/* + * Like `commit_lock_file()`, but rename the lockfile to the provided + * `path`. `path` must be on the same filesystem as the lock file. + */ +static inline int commit_lock_file_to(struct lock_file *lk, const char *path) +{ + return rename_tempfile(&lk->tempfile, path); +} + +/* + * Roll back `lk`: close the file descriptor and/or file pointer and + * 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. + */ +static inline void rollback_lock_file(struct lock_file *lk) +{ + delete_tempfile(&lk->tempfile); +} + +#endif /* LOCKFILE_H */ -- cgit 1.4.1