*
* The caller:
*
- * * Allocates a `struct lock_file` either as a static variable or on
- * the heap, initialized to zeros. Once you use the structure to
- * call the `hold_lock_file_for_*()` family of functions, it belongs
- * to the lockfile subsystem and its storage must remain valid
- * throughout the life of the program (i.e. you cannot use an
- * on-stack variable to hold this structure).
+ * * 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()`.
*
* `commit_lock_file()`, `commit_lock_file_to()`,
* `rollback_lock_file()`, or `reopen_lock_file()`.
*
- * Even after the lockfile is committed or rolled back, the
- * `lock_file` object must not be freed or altered by the caller.
- * However, it may be reused; just pass it to another call of
- * `hold_lock_file_for_update()`.
+ * 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
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
* timeout_ms is -1, retry indefinitely. The flags argument and error
* handling are described above.
*/
-extern int hold_lock_file_for_update_timeout(
+int hold_lock_file_for_update_timeout(
struct lock_file *lk, const char *path,
int flags, long timeout_ms);
* of `hold_lock_file_for_update()` to lock `path`. `err` should be the
* `errno` set by the failing call.
*/
-extern void unable_to_lock_message(const char *path, int err,
- struct strbuf *buf);
+void unable_to_lock_message(const char *path, int err,
+ struct strbuf *buf);
/*
* Emit an appropriate error message and `die()` following the failure
* `errno` set by the failing
* call.
*/
-extern NORETURN void unable_to_lock_die(const char *path, int err);
+NORETURN void unable_to_lock_die(const char *path, int err);
/*
* Associate a stdio stream with the lockfile (which must still be
* Return the path of the file that is locked by the specified
* lock_file object. The caller must free the memory.
*/
-extern char *get_locked_file_path(struct lock_file *lk);
+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 and roll back the
- * lock file. Usually `commit_lock_file()`, `commit_lock_file_to()`,
+ * 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)
* nobody else) to inspect the contents you wrote, while still
* holding the lock yourself.
*
- * * `reopen_lock_file()` to reopen the lockfile. Make further updates
- * to the contents.
+ * * `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.
*/
* call `commit_lock_file()` for a `lock_file` object that is not
* currently locked.
*/
-extern int commit_lock_file(struct lock_file *lk);
+int commit_lock_file(struct lock_file *lk);
/*
* Like `commit_lock_file()`, but rename the lockfile to the provided