[Emacs-diffs] Changes to emacs/lisp/vc.el,v

[Eric S. Raymond]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Eric S. Raymond <esr>   08/05/16 08:53:53

Index: vc.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/vc.el,v
retrieving revision 1.667
retrieving revision 1.668
diff -u -b -r1.667 -r1.668
--- vc.el       15 May 2008 17:38:50 -0000      1.667
+++ vc.el       16 May 2008 08:53:51 -0000      1.668
@@ -3251,351 +3251,5 @@
 
 (provide 'vc)
 
-;; DEVELOPER'S NOTES ON CONCURRENCY PROBLEMS IN THIS CODE
-;;
-;; These may be useful to anyone who has to debug or extend the package.
-;; (Note that this information corresponds to versions 5.x. Some of it
-;; might have been invalidated by the additions to support branching
-;; and RCS keyword lookup. AS, 1995/03/24)
-;;
-;; A fundamental problem in VC is that there are time windows between
-;; vc-next-action's computations of the file's version-control state and
-;; the actions that change it.  This is a window open to lossage in a
-;; multi-user environment; someone else could nip in and change the state
-;; of the master during it.
-;;
-;; The performance problem is that rlog/prs calls are very expensive; we want
-;; to avoid them as much as possible.
-;;
-;; ANALYSIS:
-;;
-;; The performance problem, it turns out, simplifies in practice to the
-;; problem of making vc-state fast.  The two other functions that call
-;; prs/rlog will not be so commonly used that the slowdown is a problem; one
-;; makes tags, the other deletes the calling user's last change in the
-;; master.
-;;
-;; The race condition implies that we have to either (a) lock the master
-;; during the entire execution of vc-next-action, or (b) detect and
-;; recover from errors resulting from dispatch on an out-of-date state.
-;;
-;; Alternative (a) appears to be infeasible.  The problem is that we can't
-;; guarantee that the lock will ever be removed.  Suppose a user starts a
-;; checkin, the change message buffer pops up, and the user, having wandered
-;; off to do something else, simply forgets about it?
-;;
-;; Alternative (b), on the other hand, works well with a cheap way to speed up
-;; vc-state.  Usually, if a file is registered, we can read its locked/
-;; unlocked state and its current owner from its permissions.
-;;
-;; This shortcut will fail if someone has manually changed the workfile's
-;; permissions; also if developers are munging the workfile in several
-;; directories, with symlinks to a master (in this latter case, the
-;; permissions shortcut will fail to detect a lock asserted from another
-;; directory).
-;;
-;; Note that these cases correspond exactly to the errors which could happen
-;; because of a competing checkin/checkout race in between two instances of
-;; vc-next-action.
-;;
-;; For VC's purposes, a workfile/master pair may have the following states:
-;;
-;; A. Unregistered.  There is a workfile, there is no master.
-;;
-;; B. Registered and not locked by anyone.
-;;
-;; C. Locked by calling user and unchanged.
-;;
-;; D. Locked by the calling user and changed.
-;;
-;; E. Locked by someone other than the calling user.
-;;
-;; This makes for 25 states and 20 error conditions.  Here's the matrix:
-;;
-;; VC's idea of state
-;;  |
-;;  V  Actual state   RCS action              SCCS action          Effect
-;;    A  B  C  D  E
-;;  A .  1  2  3  4   ci -u -t-          admin -fb -i<file>      initial admin
-;;  B 5  .  6  7  8   co -l              get -e                  checkout
-;;  C 9  10 .  11 12  co -u              unget; get              revert
-;;  D 13 14 15 .  16  ci -u -m<comment>  delta -y<comment>; get  checkin
-;;  E 17 18 19 20 .   rcs -u -M -l       unget -n ; get -g       steal lock
-;;
-;; All commands take the master file name as a last argument (not shown).
-;;
-;; In the discussion below, a "self-race" is a pathological situation in
-;; which VC operations are being attempted simultaneously by two or more
-;; Emacsen running under the same username.
-;;
-;; The vc-next-action code has the following windows:
-;;
-;; Window P:
-;;    Between the check for existence of a master file and the call to
-;; admin/checkin in vc-buffer-admin (apparent state A).  This window may
-;; never close if the initial-comment feature is on.
-;;
-;; Window Q:
-;;    Between the call to vc-workfile-unchanged-p in and the immediately
-;; following revert (apparent state C).
-;;
-;; Window R:
-;;    Between the call to vc-workfile-unchanged-p in and the following
-;; checkin (apparent state D).  This window may never close.
-;;
-;; Window S:
-;;    Between the unlock and the immediately following checkout during a
-;; revert operation (apparent state C).  Included in window Q.
-;;
-;; Window T:
-;;    Between vc-state and the following checkout (apparent state B).
-;;
-;; Window U:
-;;    Between vc-state and the following revert (apparent state C).
-;; Includes windows Q and S.
-;;
-;; Window V:
-;;    Between vc-state and the following checkin (apparent state
-;; D).  This window may never be closed if the user fails to complete the
-;; checkin message.  Includes window R.
-;;
-;; Window W:
-;;    Between vc-state and the following steal-lock (apparent
-;; state E).  This window may never close if the user fails to complete
-;; the steal-lock message.  Includes window X.
-;;
-;; Window X:
-;;    Between the unlock and the immediately following re-lock during a
-;; steal-lock operation (apparent state E).  This window may never close
-;; if the user fails to complete the steal-lock message.
-;;
-;; Errors:
-;;
-;; Apparent state A ---
-;;
-;; 1. File looked unregistered but is actually registered and not locked.
-;;
-;;    Potential cause: someone else's admin during window P, with
-;; caller's admin happening before their checkout.
-;;
-;;    RCS: Prior to version 5.6.4, ci fails with message
-;;         "no lock set by <user>".  From 5.6.4 onwards, VC uses the new
-;;         ci -i option and the message is "<file>,v: already exists".
-;;    SCCS: admin will fail with error (ad19).
-;;
-;;    We can let these errors be passed up to the user.
-;;
-;; 2. File looked unregistered but is actually locked by caller, unchanged.
-;;
-;;    Potential cause: self-race during window P.
-;;
-;;    RCS: Prior to version 5.6.4, reverts the file to the last saved
-;;         version and unlocks it.  From 5.6.4 onwards, VC uses the new
-;;         ci -i option, failing with message "<file>,v: already exists".
-;;    SCCS: will fail with error (ad19).
-;;
-;;    Either of these consequences is acceptable.
-;;
-;; 3. File looked unregistered but is actually locked by caller, changed.
-;;
-;;    Potential cause: self-race during window P.
-;;
-;;    RCS: Prior to version 5.6.4, VC registers the caller's workfile as
-;;         a delta with a null change comment (the -t- switch will be
-;;         ignored). From 5.6.4 onwards, VC uses the new ci -i option,
-;;         failing with message "<file>,v: already exists".
-;;    SCCS: will fail with error (ad19).
-;;
-;; 4. File looked unregistered but is locked by someone else.
-;;;
-;;    Potential cause: someone else's admin during window P, with
-;; caller's admin happening *after* their checkout.
-;;
-;;    RCS: Prior to version 5.6.4, ci fails with a
-;;         "no lock set by <user>" message.  From 5.6.4 onwards,
-;;         VC uses the new ci -i option, failing with message
-;;         "<file>,v: already exists".
-;;    SCCS: will fail with error (ad19).
-;;
-;;    We can let these errors be passed up to the user.
-;;
-;; Apparent state B ---
-;;
-;; 5. File looked registered and not locked, but is actually unregistered.
-;;
-;;    Potential cause: master file got nuked during window P.
-;;
-;;    RCS: will fail with "RCS/<file>: No such file or directory"
-;;    SCCS: will fail with error ut4.
-;;
-;;    We can let these errors be passed up to the user.
-;;
-;; 6. File looked registered and not locked, but is actually locked by the
-;; calling user and unchanged.
-;;
-;;    Potential cause: self-race during window T.
-;;
-;;    RCS: in the same directory as the previous workfile, co -l will fail
-;; with "co error: writable foo exists; checkout aborted".  In any other
-;; directory, checkout will succeed.
-;;    SCCS: will fail with ge17.
-;;
-;;    Either of these consequences is acceptable.
-;;
-;; 7. File looked registered and not locked, but is actually locked by the
-;; calling user and changed.
-;;
-;;    As case 6.
-;;
-;; 8. File looked registered and not locked, but is actually locked by another
-;; user.
-;;
-;;    Potential cause: someone else checks it out during window T.
-;;
-;;    RCS: co error: revision 1.3 already locked by <user>
-;;    SCCS: fails with ge4 (in directory) or ut7 (outside it).
-;;
-;;    We can let these errors be passed up to the user.
-;;
-;; Apparent state C ---
-;;
-;; 9. File looks locked by calling user and unchanged, but is unregistered.
-;;
-;;    As case 5.
-;;
-;; 10. File looks locked by calling user and unchanged, but is actually not
-;; locked.
-;;
-;;    Potential cause: a self-race in window U, or by the revert's
-;; landing during window X of some other user's steal-lock or window S
-;; of another user's revert.
-;;
-;;    RCS: succeeds, refreshing the file from the identical version in
-;; the master.
-;;    SCCS: fails with error ut4 (p file nonexistent).
-;;
-;;    Either of these consequences is acceptable.
-;;
-;; 11. File is locked by calling user.  It looks unchanged, but is actually
-;; changed.
-;;
-;;    Potential cause: the file would have to be touched by a self-race
-;; during window Q.
-;;
-;;    The revert will succeed, removing whatever changes came with
-;; the touch.  It is theoretically possible that work could be lost.
-;;
-;; 12. File looks like it's locked by the calling user and unchanged, but
-;; it's actually locked by someone else.
-;;
-;;    Potential cause: a steal-lock in window V.
-;;
-;;    RCS: co error: revision <rev> locked by <user>; use co -r or rcs -u
-;;    SCCS: fails with error un2
-;;
-;;    We can pass these errors up to the user.
-;;
-;; Apparent state D ---
-;;
-;; 13. File looks like it's locked by the calling user and changed, but it's
-;; actually unregistered.
-;;
-;;    Potential cause: master file got nuked during window P.
-;;
-;;    RCS: Prior to version 5.6.4, checks in the user's version as an
-;;         initial delta.  From 5.6.4 onwards, VC uses the new ci -j
-;;         option, failing with message "no such file or directory".
-;;    SCCS: will fail with error ut4.
-;;
-;;    This case is kind of nasty.  Under RCS prior to version 5.6.4,
-;; VC may fail to detect the loss of previous version information.
-;;
-;; 14. File looks like it's locked by the calling user and changed, but it's
-;; actually unlocked.
-;;
-;;    Potential cause: self-race in window V, or the checkin happening
-;; during the window X of someone else's steal-lock or window S of
-;; someone else's revert.
-;;
-;;    RCS: ci will fail with "no lock set by <user>".
-;;    SCCS: delta will fail with error ut4.
-;;
-;; 15. File looks like it's locked by the calling user and changed, but it's
-;; actually locked by the calling user and unchanged.
-;;
-;;    Potential cause: another self-race --- a whole checkin/checkout
-;; sequence by the calling user would have to land in window R.
-;;
-;;    SCCS: checks in a redundant delta and leaves the file unlocked as usual.
-;;    RCS: reverts to the file state as of the second user's checkin, leaving
-;; the file unlocked.
-;;
-;;    It is theoretically possible that work could be lost under RCS.
-;;
-;; 16. File looks like it's locked by the calling user and changed, but it's
-;; actually locked by a different user.
-;;
-;;    RCS: ci error: no lock set by <user>
-;;    SCCS: unget will fail with error un2
-;;
-;;    We can pass these errors up to the user.
-;;
-;; Apparent state E ---
-;;
-;; 17. File looks like it's locked by some other user, but it's actually
-;; unregistered.
-;;
-;;    As case 13.
-;;
-;; 18. File looks like it's locked by some other user, but it's actually
-;; unlocked.
-;;
-;;    Potential cause: someone released a lock during window W.
-;;
-;;    RCS: The calling user will get the lock on the file.
-;;    SCCS: unget -n will fail with cm4.
-;;
-;;    Either of these consequences will be OK.
-;;
-;; 19. File looks like it's locked by some other user, but it's actually
-;; locked by the calling user and unchanged.
-;;
-;;    Potential cause: the other user relinquishing a lock followed by
-;; a self-race, both in window W.
-;;
-;;     Under both RCS and SCCS, both unlock and lock will succeed, making
-;; the sequence a no-op.
-;;
-;; 20. File looks like it's locked by some other user, but it's actually
-;; locked by the calling user and changed.
-;;
-;;     As case 19.
-;;
-;; PROBLEM CASES:
-;;
-;;    In order of decreasing severity:
-;;
-;;    Cases 11 and 15 are the only ones that potentially lose work.
-;; They would require a self-race for this to happen.
-;;
-;;    Case 13 in RCS loses information about previous deltas, retaining
-;; only the information in the current workfile.  This can only happen
-;; if the master file gets nuked in window P.
-;;
-;;    Case 3 in RCS and case 15 under SCCS insert a redundant delta with
-;; no change comment in the master.  This would require a self-race in
-;; window P or R respectively.
-;;
-;;    Cases 2, 10, 19 and 20 do extra work, but make no changes.
-;;
-;;    Unfortunately, it appears to me that no recovery is possible in these
-;; cases.  They don't yield error messages, so there's no way to tell that
-;; a race condition has occurred.
-;;
-;;    All other cases don't change either the workfile or the master, and
-;; trigger command errors which the user will see.
-;;
-;;    Thus, there is no explicit recovery code.
-
 ;; arch-tag: ca82c1de-3091-4e26-af92-460abc6213a6
 ;;; vc.el ends here