mirror of
https://github.com/git/git
synced 2024-08-25 02:35:46 +00:00
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>
This commit is contained in:
parent
04e57d4d32
commit
0a06f14837
42
lockfile.c
42
lockfile.c
|
@ -4,6 +4,48 @@
|
||||||
#include "cache.h"
|
#include "cache.h"
|
||||||
#include "sigchain.h"
|
#include "sigchain.h"
|
||||||
|
|
||||||
|
/*
|
||||||
|
* File write-locks as used by Git.
|
||||||
|
*
|
||||||
|
* For an overview of how to use the lockfile API, please see
|
||||||
|
*
|
||||||
|
* Documentation/technical/api-lockfile.txt
|
||||||
|
*
|
||||||
|
* This module keeps track of all locked files in lock_file_list for
|
||||||
|
* use at cleanup. This list and the lock_file objects that comprise
|
||||||
|
* it must be kept in self-consistent states at all time, because the
|
||||||
|
* program can be interrupted any time by a signal, in which case the
|
||||||
|
* signal handler will walk through the list attempting to clean up
|
||||||
|
* any open lock files.
|
||||||
|
*
|
||||||
|
* A lockfile is owned by the process that created it. The lock_file
|
||||||
|
* object has an "owner" field that records its owner. This field is
|
||||||
|
* used to prevent a forked process from closing a lockfile created by
|
||||||
|
* its parent.
|
||||||
|
*
|
||||||
|
* A lock_file object can be in several states:
|
||||||
|
*
|
||||||
|
* - Uninitialized. In this state the object's on_list field must be
|
||||||
|
* zero but the rest of its contents need not be initialized. As
|
||||||
|
* soon as the object is used in any way, it is irrevocably
|
||||||
|
* registered in the lock_file_list, and on_list is set.
|
||||||
|
*
|
||||||
|
* - Locked, lockfile open (after hold_lock_file_for_update(),
|
||||||
|
* hold_lock_file_for_append(), or reopen_lock_file()). In this
|
||||||
|
* state, the lockfile exists, filename holds the filename of the
|
||||||
|
* lockfile, fd holds a file descriptor open for writing to the
|
||||||
|
* lockfile, and owner holds the PID of the process that locked the
|
||||||
|
* file.
|
||||||
|
*
|
||||||
|
* - Locked, lockfile closed (after close_lock_file()). Same as the
|
||||||
|
* previous state, except that the lockfile is closed and fd is -1.
|
||||||
|
*
|
||||||
|
* - Unlocked (after commit_lock_file(), rollback_lock_file(), or a
|
||||||
|
* failed attempt to lock). In this state, filename[0] == '\0' and
|
||||||
|
* fd is -1. The object is left registered in the lock_file_list,
|
||||||
|
* and on_list is set.
|
||||||
|
*/
|
||||||
|
|
||||||
static struct lock_file *lock_file_list;
|
static struct lock_file *lock_file_list;
|
||||||
|
|
||||||
static void remove_lock_file(void)
|
static void remove_lock_file(void)
|
||||||
|
|
Loading…
Reference in a new issue