Provided by: aegis_4.24.3-3_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/