From 2db69de81deea4682579d0b9e6da40b4e9558c05 Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Mon, 10 Aug 2015 11:47:36 +0200 Subject: lockfile: move documentation to lockfile.h and lockfile.c Rearrange/rewrite it somewhat to fit its new environment. Signed-off-by: Michael Haggerty Signed-off-by: Junio C Hamano --- lockfile.c | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) (limited to 'lockfile.c') diff --git a/lockfile.c b/lockfile.c index 5a93bc7bc2..2369eff541 100644 --- a/lockfile.c +++ b/lockfile.c @@ -1,6 +1,59 @@ /* * Copyright (c) 2005, Junio C Hamano */ + +/* + * State diagram and cleanup + * ------------------------- + * + * 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. + * + * The possible states of a `lock_file` object are as follows: + * + * - 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 `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 + * - `active` is set + * - `filename` holds the filename of the lockfile + * - `fd` holds a file descriptor open for writing to the lockfile + * - `fp` holds a pointer to an open `FILE` object if and only if + * `fdopen_lock_file()` has been called on the object + * - `owner` holds the PID of the process that locked the file + * + * - Locked, lockfile closed (after successful `close_lock_file()`). + * Same as the previous state, except that the lockfile is closed + * and `fd` is -1. + * + * - Unlocked (after `commit_lock_file()`, `commit_lock_file_to()`, + * `rollback_lock_file()`, a failed attempt to lock, or a failed + * `close_lock_file()`). In this state: + * + * - `active` is unset + * - `filename` is empty (usually, though there are transitory + * states in which this condition doesn't hold). Client code should + * *not* rely on the filename being empty in this state. + * - `fd` is -1 + * - the object is left registered in the `lock_file_list`, and + * `on_list` is set. + * + * A lockfile is owned by the process that created it. The `lock_file` + * has an `owner` field that records the owner's PID. This field is + * used to prevent a forked process from closing a lockfile created by + * its parent. + */ + #include "cache.h" #include "lockfile.h" #include "sigchain.h" -- cgit v1.2.3