package locklib;
   
   
   import java.util.concurrent.ExecutionException;
   import java.util.concurrent.Future;
   import java.util.concurrent.TimeUnit;
   import java.util.concurrent.TimeoutException;
   
   import ensure.Ensure;
  
  /**
   * <p>Future representing a request for a lock grant. This future object is
   * created when requesting a lock on a target. A {@link LockGrantFuture} is
   * an asynchronous request for a lock grant. A synchronous wait can be done
   * invoking the {@link #get()} or the {@link #get(long, TimeUnit)} methods.</p>
   * 
   * <p>Lock grant futures can be cancelled. Cancelling a lock grant future
   * will release any partial locks already acquired. It will not release the
   * lock if it has already been acquired.</p>
   * 
   * <p>Synchronization locks on <code>LockGrantFuture</code> should never be
   * made outside <em>locklib</em></p>.
   * 
   * @param <LockType> the type of lock
   */
  /*
   * Implementation notes:
   * 
   * LockGrantFutures are chained just like the LockGrant.
   * 
   * The LockGrantFutures only acquire locks on themselves, their own LockGrants
   * and other LockGrantFutures in the lock chain. LockGrantFutures are always
   * locked *before* their predecessors.
   */
  public class LockGrantFuture<LockType> implements Future<LockGrant<LockType>> {
  	/**
  	 * The lock requested.
  	 */
  	private LockRequest<LockType> m_request;
  	
  	/**
  	 * The target of the lock.
  	 */
  	private Target<LockType> m_target;
  	
  	/**
  	 * The lock grant, <code>null</code> if the lock has not yet been granted
  	 * or if the future has been canceled.
  	 */
  	private LockGrant<LockType> m_grant;
  	
  	/**
  	 * Future granting the predecessor lock, if any.
  	 */
  	private LockGrantFuture<LockType> m_predecessor_future;
  	
  	/**
  	 * Future granting the successor lock, if any.
  	 */
  	private LockGrantFuture<LockType> m_successor_future;
  	
  	/**
  	 * Has the lock been cancelled?
  	 */
  	private boolean m_cancelled;
  	
  	/**
  	 * Creates a future for a lock that will eventually be granted (or not!)
  	 * @param request the lock type requested
  	 * @param target the target where the lock was requested
  	 * @param predecessor_future an optional future representing the
  	 * acquisition of the predecessor lock
  	 */
  	LockGrantFuture(LockRequest<LockType> request, Target<LockType> target,
  			LockGrantFuture<LockType> predecessor_future) {
  		Ensure.not_null(request, "request == null");
  		Ensure.not_null(target, "target == null");
  		
  		m_request = request;
  		m_target = target;
  		m_grant = null;
  		m_predecessor_future = predecessor_future;
  		m_successor_future = null;
  		if (predecessor_future != null) {
  			synchronized (predecessor_future) {
  				Ensure.is_null(predecessor_future.m_successor_future,
  						"predecessor_future.m_successor_future != null");
  				Ensure.is_false(predecessor_future.m_cancelled,
  						"predecessor_future.m_cancelled");
  				predecessor_future.m_successor_future = this;
  			}
  		}
  	}
  
  	@Override
  	public boolean cancel(boolean mayInterruptIfRunning) {
  		boolean c = m_target.cancel(this);
  		synchronized (this) {
  			if (c) {
 				Ensure.is_true(m_cancelled, "!m_cancelled");
 				Ensure.is_null(m_grant, "m_grant != null");
 			} else {
 				Ensure.is_false(m_cancelled, "m_cancelled");
 				Ensure.not_null(m_grant, "m_grant == null");
 			}
 		}
 		
 		return c;
 	}
 
 	@Override
 	public synchronized boolean isCancelled() {
 		return m_cancelled;
 	}
 
 	@Override
 	public synchronized boolean isDone() {
 		return (m_grant != null) || m_cancelled;
 	}
 
 	@Override
 	public LockGrant<LockType> get() throws InterruptedException,
 			ExecutionException {
 		try {
 			return get(0, TimeUnit.MILLISECONDS);
 		} catch (TimeoutException e) {
 			Ensure.never_thrown(e);
 			return null;
 		}
 	}
 
 	@Override
 	public LockGrant<LockType> get(long timeout, TimeUnit unit)
 			throws InterruptedException, ExecutionException, TimeoutException {
 		Ensure.greater_equal(timeout, 0, "timeout < 0");
 		Ensure.not_null(unit, "unit == null");
 		
 		long limit = System.currentTimeMillis() + unit.toMillis(timeout);
 		if (timeout == 0) {
 			limit = Long.MAX_VALUE;
 		}
 		
 		long now;
 		LockGrantFuture<LockType> pf;
 		synchronized (this) {
 			pf = m_predecessor_future;
 		}
 		
 		/*
 		 * First we must wait for the predecessor lock to be acquired.
 		 */
 		if (pf != null) {
 			pf.get(timeout, unit);
 		}
 		
 		/*
 		 * Then we must wait for the lock to be granted.
 		 */
 		synchronized (this) {
 			while (m_grant == null
 					&& (now = System.currentTimeMillis()) < limit) {
 				if (m_cancelled) {
 					throw new LockCancelledException("Locked has been "
 							+ "cancelled.");
 				}
 				
 				wait(limit - now);
 			}
 			
 			if (m_grant == null) {
 				throw new TimeoutException();
 			}
 			
 			return m_grant;
 		}
 	}
 	
 	/**
 	 * Obtains the grant. This method can only be invoked if we know that the
 	 * grant has been acquired.
 	 * @return the grant
 	 */
 	synchronized LockGrant<LockType> get_now() {
 		Ensure.not_null(m_grant, "m_grant == null");
 		return m_grant;
 	}
 	
 	/**
 	 * Marks the future as complete.
 	 * @param grant the lock acquired
 	 */
 	synchronized void acquired(LockGrant<LockType> grant) {
 		Ensure.not_null(grant, "grant == null");
 		Ensure.is_null(m_grant, "m_grant != null");
 		Ensure.is_false(m_cancelled, "m_cancelled");
 		
 		/*
 		 * For safety, we want to ensure that if we have a predecessor lock,
 		 * it has been acquired already. Note that we must have our
 		 * synchronized lock acquired before the predecessor's synchronization
 		 * lock is acquired.
 		 */
 		if (m_predecessor_future != null) {
 			synchronized (m_predecessor_future) {
 				Ensure.not_null(m_predecessor_future.m_grant,
 						"m_predecessor_future.m_grant == null");
 				Ensure.is_false(m_predecessor_future.m_cancelled,
 						"m_predecessor_future.m_cancelled");
 			}
 		}
 		
 		m_grant = grant;
 		notifyAll();
 	}
 	
 	/**
 	 * Marks the future as canceled.
 	 */
 	void cancelled() {
 		/*
 		 * For safety, we want to ensure that if we have a successor lock,
 		 * it has been cancelled already. Note that we must have the
 		 * successor's synchronization lock acquired before our own.
 		 */
 		LockGrantFuture<LockType> suc = null;
 		synchronized (this) {
 			suc = m_successor_future;
 		}
 		
 		if (suc != null) {
 			synchronized (suc) {
 				Ensure.is_null(suc.m_grant, "suc.m_grant != null");
 				Ensure.is_true(suc.m_cancelled, "!suc.m_cancelled");
 				synchronized (this) {
 					Ensure.is_null(m_grant, "m_grant != null");
 					Ensure.is_false(m_cancelled, "m_cancelled");
 					
 					m_cancelled = true;
 					notifyAll();
 				}
 			}
 		} else {
 			synchronized (this) {
 				Ensure.is_null(m_grant, "m_grant != null");
 				Ensure.is_false(m_cancelled, "m_cancelled");
 				
 				m_cancelled = true;
 				notifyAll();
 			}
 		}
 	}
 	
 	/**
 	 * Obtains the target of the lock.
 	 * @return the target
 	 */
 	public synchronized Target<LockType> target() {
 		return m_target;
 	}
 	
 	/**
 	 * Obtains the lock request.
 	 * @return the lock request
 	 */
 	public synchronized LockRequest<LockType> request() {
 		return m_request;
 	}
 	
 	/**
 	 * Obtains the successor future that should be acquired after this one.
 	 * @return the successor future or <code>null</code> if none
 	 */
 	synchronized LockGrantFuture<LockType> successor_future() {
 		return m_successor_future;
 	}
 	
 	/**
 	 * Obtains the predecessor future that should be acquired before this one.
 	 * @return the predecessor future or <code>null</code> if none
 	 */
 	LockGrantFuture<LockType> predecessor_future() {
 		return m_predecessor_future;
 	}
 	
 	@Override
 	public synchronized String toString() {
 		return "LockGrantFuture[request=" + m_request + ", granted?" +
 				(m_grant == null? "false" : "true") + ", predecessor="
 				+ m_predecessor_future + ", cancelled=" + m_cancelled + "]";
 	}
 }