lockfile.c: document the various states of lock_file objects
Document the valid states of lock_file objects, how they get into each state, and how the state is encoded in the object's fields. Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Reviewed-by: Ronnie Sahlberg <sahlberg@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael Haggerty committed
Oct 1, 2014 at 12:28 UTC
0a06f148373285822baf5f3e83696732a556a2d1
1 file changed
+42
lockfile.c
+42
@@ -4,6 +4,48 @@
4
#include "cache.h"
5
#include "sigchain.h"
6
7
+/*
8
+ * File write-locks as used by Git.
9
+ *
10
+ * For an overview of how to use the lockfile API, please see
11
+ *
12
+ * Documentation/technical/api-lockfile.txt
13
+ *
14
+ * This module keeps track of all locked files in lock_file_list for
15
+ * use at cleanup. This list and the lock_file objects that comprise
16
+ * it must be kept in self-consistent states at all time, because the
17
+ * program can be interrupted any time by a signal, in which case the
18
+ * signal handler will walk through the list attempting to clean up
19
+ * any open lock files.
20
+ *
21
+ * A lockfile is owned by the process that created it. The lock_file
22
+ * object has an "owner" field that records its owner. This field is
23
+ * used to prevent a forked process from closing a lockfile created by
24
+ * its parent.
25
+ *
26
+ * A lock_file object can be in several states:
27
+ *
28
+ * - Uninitialized. In this state the object's on_list field must be
29
+ * zero but the rest of its contents need not be initialized. As
30
+ * soon as the object is used in any way, it is irrevocably
31
+ * registered in the lock_file_list, and on_list is set.
32
+ *
33
+ * - Locked, lockfile open (after hold_lock_file_for_update(),
34
+ * hold_lock_file_for_append(), or reopen_lock_file()). In this
35
+ * state, the lockfile exists, filename holds the filename of the
36
+ * lockfile, fd holds a file descriptor open for writing to the
37
+ * lockfile, and owner holds the PID of the process that locked the
38
+ * file.
39
+ *
40
+ * - Locked, lockfile closed (after close_lock_file()). Same as the
41
+ * previous state, except that the lockfile is closed and fd is -1.
42
+ *
43
+ * - Unlocked (after commit_lock_file(), rollback_lock_file(), or a
44
+ * failed attempt to lock). In this state, filename[0] == '\0' and
45
+ * fd is -1. The object is left registered in the lock_file_list,
46
+ * and on_list is set.
47
+ */
48
+
49
static struct lock_file *lock_file_list;
50
51
static void remove_lock_file(void)