package locklib;
   
   import ensure.Ensure;
   
   /**
    * <p>A lock grant represents the successful acquisition of a lock. Lock grants
    * can be either <em>valid</em> or <em>invalid</em>. They are created
    * valid but, once the lock is released, they become invalid (meaning the
    * lock granted has been revoked).</p>
   * 
   * <p>Lock grants are organized in chains: the previous lock in a chain is
   * called the <em>predecessor</em> lock and the next lock in the chain is
   * called the <em>successor</em> lock. The first lock in the chain has no
   * predecessor and the last has no successor. Chains are built from the
   * target hierarchy: beginning of the chain is the top element in the
   * target hierarchy and the last element in the lock chain is placed in the
   * bottom element locked in target hierarchy.</p>
   * 
   * <p>When being acquired, predecessor locks must be acquired <em>before</em>
   * and released <em>after</em>. This is handled transparently
   * by <em>locklib</em>.</p>
   * 
   * <p>Lock grants are acquired through {@link LockGrantFuture}.</p>
   * 
   * <p>Synchronization locks on <code>LockGrant</code> should never be made
   * outside <em>locklib</em></p>.
   * @param <LockType> type of lock
   */
  /*
   * Implementation notes:
   * 
   * LockGrants are self-contained from a synchronization perspective: they do
   * not invoke any object of another class with a lock held.
   * 
   * LockGrants may need to acquire several synchronization locks on lock grants.
   * The rule is that successors have to be locked before predecessors.
   * 
   * LockGrants must be acquired forward in the chain and released backwards.
   * This means that LockGrants can only be acquired once the predecessor grant
   * has been acquired and can only be released after their successor has been
   * released.
   * 
   * LockGrants do not change anything else other than their own state. They do
   * interact with other grants in the chain to ensure consistency.
   */
  public class LockGrant<LockType> {
  	/**
  	 * The lock requested.
  	 */
  	private LockRequest<LockType> m_request;
  	
  	/**
  	 * The lock target.
  	 */
  	private Target<LockType> m_target;
  	
  	/**
  	 * The predecessor lock that must be released <em>after</em> this one.
  	 */
  	private LockGrant<LockType> m_predecessor;
  	
  	/**
  	 * The successor lock that must be released <em>before</em> this one.
  	 */
  	private LockGrant<LockType> m_successor;
  	
  	/**
  	 * Is this grant still valid?
  	 */
  	private boolean m_valid;
  	
  	/**
  	 * Creates a new grant.
  	 * @param r the lock requested
  	 * @param t the target where the lock has been granted
  	 * @param predecessor an optional predecessor
  	 */
  	LockGrant(LockRequest<LockType> r, Target<LockType> t,
  			LockGrant<LockType> predecessor) {
  		Ensure.not_null(r, "r == null");
  		Ensure.not_null(t, "t == null");
  		
  		m_request = r;
  		m_target = t;
  		m_predecessor = predecessor;
  		m_valid = true;
  		m_successor = null;
  		
  		/*
  		 * Set this lock as the successor of the predecessor lock if there is
  		 * a predecessor lock.
  		 */
  		if (predecessor != null) {
  			synchronized (predecessor) {
  				Ensure.is_null(predecessor.m_successor,
  						"predecessor.m_successor != null");
  				Ensure.is_true(predecessor.m_valid, "!predecessor.m_valid");
  				predecessor.m_successor = this;
  			}
 		}
 	}
 	
 	/**
 	 * Checks whether this grant is still valid or not.
 	 * @return is the grant still valid?
 	 */
 	public synchronized boolean valid() {
 		return m_valid;
 	}
 	
 	/**
 	 * Invalidates a valid lock grant making it invalid.
 	 */
 	void invalidate() {
 		LockGrant<LockType> suc;
 		
 		/*
 		 * This is tricky but successors need to be held before predecessors.
 		 * So first we must figure out if we have a successor to lock and check
 		 * its state *before* locking and checking ourselves.
 		 */
 		synchronized (this) {
 			suc = m_successor;
 		}
 		
 		if (suc != null) {
 			synchronized (m_successor) {
 				Ensure.is_false(m_successor.m_valid, "m_successor.m_valid");
 				synchronized (this) {
 					Ensure.is_true(m_valid, "!m_valid");
 					m_valid = false;
 				}
 			}
 		} else {
 			synchronized (this) {
 				Ensure.is_true(m_valid, "!m_valid");
 				m_valid = false;
 			}
 		}
 	}
 	
 	/**
 	 * Obtains the lock request that generated this grant.
 	 * @return the request
 	 */
 	public synchronized LockRequest<LockType> request() {
 		return m_request;
 	}
 	
 	/**
 	 * Obtains the locked target.
 	 * @return the target
 	 */
 	public synchronized Target<LockType> target() {
 		return m_target;
 	}
 	
 	/**
 	 * Obtains the predecessor grant, if any.
 	 * @return the grant or <code>null</code> if there is none
 	 */
 	synchronized LockGrant<LockType> predecessor() {
 		return m_predecessor;
 	}
 	
 	/**
 	 * Obtains the successor grant, if any.
 	 * @return the grant or <code>null</code> if there is none
 	 */
 	synchronized LockGrant<LockType> successor() {
 		return m_successor;
 	}
 	
 	/**
 	 * Releases the grant. This is equivalent to invoke the
 	 * {@link Target#unlock(LockGrant)} method of this grant's target.
 	 */
 	public void release() {
 		target().unlock(this);
 	}
 	
 	@Override
 	public String toString() {
 		return "LockGrant[request=" + m_request + ", target=" + m_target
 				+ ", predecessor=" + m_predecessor + "]";
 	}
 }