

aegis locking(1)				 aegis locking(1)


NNAAMMEE
       aegis locks - how locking works,	and which command use
       them

DDEESSCCRRIIPPTTIIOONN
       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.

   DDiinniinngg PPhhiilloossoopphheerrss
       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	_m_u_c_h 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 _r_e_l_e_a_s_e_d 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.)

   LLiissttiinngg LLoocckkss
       There is	a command available to list the	current	Aegis
       locks.
	      aegis -list locks
       Note that the project names are change numbers are _g_u_e_s_s_e_s
       as the locks are	hashed over a 16-bit range, and	range
       overlaps	are possible.  Collisions are also possible, but
       fortunately rarer.

CCOOMMMMAANNDDSS
       The following table shows the locks taken by the	various
       commands.  Note that theoretically some of the commands
       take too	_f_e_w 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   .

SSEEEE AALLSSOO
       You may wish to see the manual pages of all of the above
       commands.  Many have descriptions of the	locking
       interactions.


CCOOPPYYRRIIGGHHTT
       aegis version .C001
       Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997,
       1998, 1999, 2000, 2001 Peter Miller; All	rights reserved.

       The aegis program comes with ABSOLUTELY NO WARRANTY; for
       details use the '_a_e_g_i_s _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e'	command.  This is
       free software and you are welcome to redistribute it under
       certain conditions; for details use the '_a_e_g_i_s _-_V_E_R_S_i_o_n
       _L_i_c_e_n_s_e'	command.

AAUUTTHHOORR
       Peter Miller   E-Mail:	millerp@canb.auug.org.au
       /\/\*		 WWW:	http://www.canb.auug.org.au/~millerp/


Reference Manual	      Aegis				1