*
* 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
#include "tempfile.h"
struct lock_file {
- struct tempfile tempfile;
+ 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
*/
static inline int is_lock_file_locked(struct lock_file *lk)
{
- return is_tempfile_active(&lk->tempfile);
+ return is_tempfile_active(lk->tempfile);
}
/*
*/
static inline FILE *fdopen_lock_file(struct lock_file *lk, const char *mode)
{
- return fdopen_tempfile(&lk->tempfile, mode);
+ return fdopen_tempfile(lk->tempfile, mode);
}
/*
*/
static inline const char *get_lock_file_path(struct lock_file *lk)
{
- return get_tempfile_path(&lk->tempfile);
+ return get_tempfile_path(lk->tempfile);
}
static inline int get_lock_file_fd(struct lock_file *lk)
{
- return get_tempfile_fd(&lk->tempfile);
+ return get_tempfile_fd(lk->tempfile);
}
static inline FILE *get_lock_file_fp(struct lock_file *lk)
{
- return get_tempfile_fp(&lk->tempfile);
+ return get_tempfile_fp(lk->tempfile);
}
/*
*/
static inline int close_lock_file_gently(struct lock_file *lk)
{
- return close_tempfile_gently(&lk->tempfile);
+ return close_tempfile_gently(lk->tempfile);
}
/*
*/
static inline int reopen_lock_file(struct lock_file *lk)
{
- return reopen_tempfile(&lk->tempfile);
+ return reopen_tempfile(lk->tempfile);
}
/*