/**
 *******************************************************************************
 * Copyright (C) 2001-2003, International Business Machines Corporation and    *
 * others. All Rights Reserved.                                                *
 *******************************************************************************
 *
 * $Source: /xsrl/Nsvn/icu/icu4j/src/com/ibm/icu/impl/ICURWLock.java,v $
 * $Date: 2003/06/03 18:49:32 $
 * $Revision: 1.6 $
 *
 *******************************************************************************
 */
package com.ibm.icu.impl;

// See Allan Holub's 1999 column in JavaWorld, and Doug Lea's code for RWLocks with writer preference.


/**
 * <p>A simple Reader/Writer lock.  This assumes that there will
 * be little writing contention.  It also doesn't allow 
 * active readers to acquire and release a write lock, or
 * deal with priority inversion issues.</p>
 *
 * <p>Access to the lock should be enclosed in a try/finally block
 * in order to ensure that the lock is always released in case of
 * exceptions:<br><pre>
 * try {
 *     lock.acquireRead();
 *     // use service protected by the lock
 * }
 * finally {
 *     lock.releaseRead();
 * }
 * </pre></p>
 *
 * <p>The lock provides utility methods getStats and clearStats
 * to return statistics on the use of the lock.</p>
 */
public class ICURWLock {
    private Object writeLock = new Object();
    private Object readLock = new Object();
    private int wwc; // waiting writers
    private int rc; // active readers, -1 if there's an active writer
    private int wrc; // waiting readers

    private Stats stats = new Stats(); // maybe don't init to start...

    /**
     * Internal class used to gather statistics on the RWLock.
     */
    public final static class Stats {
	/**
	 * Number of times read access granted (read count).
	 */
	public int _rc;

	/**
	 * Number of times concurrent read access granted (multiple read count).
	 */
	public int _mrc;

	/**
	 * Number of times blocked for read (waiting reader count).
	 */
	public int _wrc; // wait for read

	/**
	 * Number of times write access granted (writer count).
	 */
	public int _wc;

	/**
	 * Number of times blocked for write (waiting writer count).
	 */
	public int _wwc;

	private Stats() {
	}

	private Stats(int rc, int mrc, int wrc, int wc, int wwc) {
	    this._rc = rc;
	    this._mrc = mrc;
	    this._wrc = wrc;
	    this._wc = wc;
	    this._wwc = wwc;
	}

	private Stats(Stats rhs) {
	    this(rhs._rc, rhs._mrc, rhs._wrc, rhs._wc, rhs._wwc);
	}

	/**
	 * Return a string listing all the stats.
	 */
	public String toString() {
	    return " rc: " + _rc +
		" mrc: " + _mrc + 
		" wrc: " + _wrc +
		" wc: " + _wc +
		" wwc: " + _wwc;
	}
    }

    /**
     * Reset the stats.  Returns existing stats, if any.
     */
    public synchronized Stats resetStats() {
	Stats result = stats;
	stats = new Stats();
	return result;
    }

    /**
     * Clear the stats (stop collecting stats).  Returns existing stats, if any.
     */
    public synchronized Stats clearStats() {
	Stats result = stats;
	stats = null;
	return result;
    }
    
    /**
     * Return a snapshot of the current stats.  This does not reset the stats.
     */
    public synchronized Stats getStats() {
	return stats == null ? null : new Stats(stats);
    }

    // utilities

    private synchronized boolean gotRead() {
	++rc;
	if (stats != null) {
	    ++stats._rc;
	    if (rc > 1) ++stats._mrc;
	}
	return true;
    }

    private synchronized boolean getRead() {
	if (rc >= 0 && wwc == 0) {
	    return gotRead();
	}
	++wrc;
	return false;
    }

    private synchronized boolean retryRead() {
	if (stats != null) ++stats._wrc;
	if (rc >= 0 && wwc == 0) {
	    --wrc;
	    return gotRead();
	}
	return false;
    }

    private synchronized boolean finishRead() {
	if (rc > 0) {
	    return (0 == --rc && wwc > 0);
	}
	throw new InternalError("no current reader to release");
    }
	
    private synchronized boolean gotWrite() {
	rc = -1;
	if (stats != null) {
	    ++stats._wc;
	}
	return true;
    }

    private synchronized boolean getWrite() {
	if (rc == 0) {
	    return gotWrite();
	}
	++wwc;
	return false;
    }

    private synchronized boolean retryWrite() {
	if (stats != null) ++stats._wwc;
	if (rc == 0) {
	    --wwc;
	    return gotWrite();
	}
	return false;
    }

    private static final int NOTIFY_NONE = 0;
    private static final int NOTIFY_WRITERS = 1;
    private static final int NOTIFY_READERS = 2;

    private synchronized int finishWrite() {
	if (rc < 0) {
	    rc = 0;
	    if (wwc > 0) {
		return NOTIFY_WRITERS;
	    } else if (wrc > 0) {
		return NOTIFY_READERS;
	    } else {
		return NOTIFY_NONE;
	    }
	}
	throw new InternalError("no current writer to release");
    }
	
    /**
     * <p>Acquire a read lock, blocking until a read lock is
     * available.  Multiple readers can concurrently hold the read
     * lock.</p>
     *
     * <p>If there's a writer, or a waiting writer, increment the
     * waiting reader count and block on this.  Otherwise
     * increment the active reader count and return.  Caller must call
     * releaseRead when done (for example, in a finally block).</p> 
     */
    public void acquireRead() {
	if (!getRead()) {
	    for (;;) {
		try {
		    synchronized (readLock) {
			readLock.wait();
		    }
		    if (retryRead()) {
			return;
		    }
		}
		catch (InterruptedException e) {
		}
	    }
	}
    }

    /**
     * <p>Release a read lock and return.  An error will be thrown
     * if a read lock is not currently held.</p>
     *
     * <p>If this is the last active reader, notify the oldest
     * waiting writer.  Call when finished with work
     * controlled by acquireRead.</p>
     */
    public void releaseRead() {
	if (finishRead()) {
	    synchronized (writeLock) {
		writeLock.notify();
	    }
	}
    }

    /**
     * <p>Acquire the write lock, blocking until the write lock is
     * available.  Only one writer can acquire the write lock, and
     * when held, no readers can acquire the read lock.</p>
     *
     * <p>If there are no readers and no waiting writers, mark as
     * having an active writer and return.  Otherwise, add a lock to the
     * end of the waiting writer list, and block on it.  Caller
     * must call releaseWrite when done (for example, in a finally
     * block).<p> 
     */
    public void acquireWrite() {
	if (!getWrite()) {
	    for (;;) {
		try {
		    synchronized (writeLock) {
			writeLock.wait();
		    }
		    if (retryWrite()) {
			return;
		    }
		}
		catch (InterruptedException e) {
		}
	    }
	}
    }

    /**
     * <p>Release the write lock and return.  An error will be thrown
     * if the write lock is not currently held.</p>
     *
     * <p>If there are waiting readers, make them all active and
     * notify all of them.  Otherwise, notify the oldest waiting
     * writer, if any.  Call when finished with work controlled by
     * acquireWrite.</p> 
     */
    public void releaseWrite() {
	switch (finishWrite()) {
	case NOTIFY_WRITERS:
	    synchronized (writeLock) {
		writeLock.notify();
	    }
	    break;
	case NOTIFY_READERS:
	    synchronized (readLock) {
		readLock.notifyAll();
	    }
	    break;
	case NOTIFY_NONE:
	    break;
	}
    }
}