lockfile: update lifetime requirements in documentation
Now that the tempfile system we rely on has loosened the lifetime requirements for storage, we can adjust our documentation to match. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
Sep 5, 2017 at 08:15 UTC
5e7f01c93e510c9c8d775665324abba15f05c3ff
1 file changed
+10
-10
lockfile.h
+10
-10
@@ -37,12 +37,12 @@
37
*
38
* The caller:
39
*
40
- * * Allocates a `struct lock_file` either as a static variable or on
41
- * the heap, initialized to zeros. Once you use the structure to
42
- * call the `hold_lock_file_for_*()` family of functions, it belongs
43
- * to the lockfile subsystem and its storage must remain valid
44
- * throughout the life of the program (i.e. you cannot use an
45
- * on-stack variable to hold this structure).
40
+ * * Allocates a `struct lock_file` with whatever storage duration you
41
+ * desire. The struct does not have to be initialized before being
42
+ * used, but it is good practice to do so using by setting it to
43
+ * all-zeros (or using the LOCK_INIT macro). This puts the object in a
44
+ * consistent state that allows you to call rollback_lock_file() even
45
+ * if the lock was never taken (in which case it is a noop).
46
*
47
* * Attempts to create a lockfile by calling `hold_lock_file_for_update()`.
48
*
@@ -73,10 +73,8 @@
73
* `commit_lock_file()`, `commit_lock_file_to()`,
74
* `rollback_lock_file()`, or `reopen_lock_file()`.
75
*
76
- * Even after the lockfile is committed or rolled back, the
77
- * `lock_file` object must not be freed or altered by the caller.
78
- * However, it may be reused; just pass it to another call of
79
- * `hold_lock_file_for_update()`.
76
+ * After the lockfile is committed or rolled back, the `lock_file`
77
+ * object can be discarded or reused.
78
*
79
* If the program exits before `commit_lock_file()`,
80
* `commit_lock_file_to()`, or `rollback_lock_file()` is called, the
@@ -114,6 +112,8 @@ struct lock_file {
112
struct tempfile *tempfile;
113
};
114
115
+#define LOCK_INIT { NULL }
116
+
117
/* String appended to a filename to derive the lockfile name: */
118
#define LOCK_SUFFIX ".lock"
119
#define LOCK_SUFFIX_LEN 5