Provided by: aegis_4.24.3-1_i386 bug

NAME

       aegis locks - how locking works, and which commands use them

DESCRIPTION

       Aegis maintains a database of information about the projects in its
       care, and the various changes, both completed and in progress.  In
       order to ensure the integrity of this database, and also your project
       repository, it uses locks.

       From time to time, these locks are visible to the users, because they
       will be told that a command is waiting for a particular lock.  For some
       transactions, this can be a long wait.

   Dining Philosophers
       While UNIX supplies locks in various flavors, if you need an entire set
       of locks simultaneously, there is no elegant “all or nothing ”
       interface available.  This is unsurprising, as this is one of the
       classic computer science problems, known as the Dining Philosophers
       problem.

       The master lock is used to solve the Dining Philosophers problem, and
       is meant to be very transient.  It is only held while the other locks
       which are required (frequently two or more, hence the problem) are
       requested - non-blocking.  Once they are all obtained (or not, and any
       partials given back) the master lock is released.  It is usually held
       for much less than a second.  If you notice the master lock being held,
       it is almost always a symptom of the NFS lock daemon misbehaving.

       If the lock(s) could not be obtained, the blocking lock is waited on
       (without the master).  This is when the "waiting for" message is
       issued.  When obtained, it is released and the whole cycle starts
       again.  This is why you occasionally see a series of "waiting for"
       messages.  (This could maybe be optimized some, but it is still
       possible to block on yet another lock, and they you have to release all
       and wait again.  As yet, I’m not convinced the extra code complexity is
       required.)

   Listing Locks
       There is a command available to list the current Aegis locks.
              aegis -list locks
       Note that the project names are change numbers are guesses as the locks
       are hashed over a 16-bit range, and range overlaps are possible.
       Collisions are also possible, but fortunately rarer.

   Known Problems
       There is a known problem with the HP/UX NFS clients.  If you see
       persistent "no locks available" error messages when  is NFS mounted,
       try making the /lockfile file world writable.  chmod 666 /lockfile
       There is the possibility of a denial of service attack (which is why
       the default is 0600) but since you are presently denied service anyway,
       it’s academic.

COMMANDS

       The following table shows the locks taken by the various commands.
       Note that theoretically some of the commands take too few locks, but
       this has yet to prove to be a problem in practice.  Also, "project
       state file" and "change state file" are the same thing for branches, it
       just depends which way you are looking at them at the time.

       Command      Global      Project    Project     Ancestor     Change       User
                    State       State      Baseline    Baselines    State        State
                    File        File                                File         File
       ----------------------------------------------------------------------------------
       aeb (dev)       .           .        shared      shared     exclusive       .
       aeb (int)       .           .           .        shared     exclusive       .
       aeca            .           .           .           .       exclusive       .
       aechown         .           .           .           .       exclusive   exclusive
       aeclean         .           .           .           .       exclusive       .
       aeclone         .       exclusive       .           .       exclusive   exclusive
       aecp            .           ,           ,           ,       exclusive       .
       aecpu           .           .           .           .       exclusive       .
       aed             .           ,           ,           ,       exclusive       .
       aedb            .           .           .           .       exclusive   exclusive
       aedbu           .           .           .           .       exclusive   exclusive
       aede            .           ,           .           .       exclusive   exclusive
       aedeu           .           .           .           .       exclusive   exclusive
       aedn            .       exclusive       .           .           .           .
       aeib            .       exclusive       .           .       exclusive   exclusive
       aeibu           .       exclusive       .           .       exclusive   exclusive
       aeifail         .       exclusive       .           .       exclusive   exclusive
       aeipass         .       exclusive   exclusive       .       exclusive   exclusive
       aemv            .           ,           ,           ,       exclusive       .
       aena            .       exclusive       .           .           .           .
       aenbr           .       exclusive       .           .           .           .
       aenbru      exclusive   exclusive       .           .           .           .
       aenc            .       exclusive       .           .           .           .
       aencu           .       exclusive       .           .           .           .
       aend            .       exclusive       .           .           .           .
       aenf            .           .           .           .       exclusive       .
       aenfu           .           .           .           .       exclusive       .
       aeni            .       exclusive       .           .           .           .
       aenpa       exclusive       .           .           .           .           .
       aenpr       exclusive       .           .           .           .           .
       aenrv           .       exclusive       .           .           .           .
       aent            .       exclusive       .           .       exclusive       .
       aentu           .           .           .           .       exclusive       .
       aepa            .       exclusive       .           .           .           .
       aera            .       exclusive       .           .           .           .
       aerd            .       exclusive       .           .           .           .
       aerfail         .           .           .           .       exclusive   exclusive
       aeri            .       exclusive       .           .           .           .
       aerm            .           ,           .           .       exclusive       .
       aermu           .           .           .           .       exclusive       .
       aermpr      exclusive       .           .           .           .           .
       aerpa       exclusive       .           .           .           .           .
       aerpass         .           .           .           .       exclusive       .
       aerpu           .           .           .           .       exclusive       .
       aerrv           .       exclusive       .           .           .           .
       aet             .           .           ,           ,       exclusive       .

SEE ALSO

       You may wish to see the manual pages of all of the above commands.
       Many have descriptions of the locking interactions.

COPYRIGHT

       aegis version 4.24.3.D001
       Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
       2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Peter
       Miller

       The aegis program comes with ABSOLUTELY NO WARRANTY; for details use
       the ’aegis -VERSion License’ command.  This is free software and you
       are welcome to redistribute it under certain conditions; for details
       use the ’aegis -VERSion License’ command.

AUTHOR

       Peter Miller   E-Mail:   millerp@canb.auug.org.au
       /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/