Wicket.java

/*
 * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package nsk.share;

import java.io.PrintStream;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.locks.Condition;
import java.util.concurrent.locks.Lock;
import java.util.concurrent.locks.ReentrantLock;

/**
 * Wicket provides a means for one or more threads to suspend execution
 * (to wait) until notified by one or more other threads that some set
 * of locks is now open.
 *
 * <p>Wicket instances are intended to be used generally in the following
 * scenarios:
 *
 *   <ul><li>One thread starts one or more child threads and waits until the
 *   child threads to be started.
 *
 *   <li>One thread starts one or more child threads and waits until at least
 *   one of the child threads to be started.
 *
 *   <li>One or more child threads wait until a main thread lets them
 *   to finish.
 *
 *   <li>Disable the current thread for thread scheduling purposes, for up to
 *   the specified waiting time.</ul>
 */

public class Wicket {

    /** Number of closed locks, can be greater or equal to zero */
    private int count;

    /** Number of waiters **/
    private int waiters = 0;

    /** Enable debug output */
    private PrintStream debugOutput = null;

    /** Wicket's string identifier */
    private String name = "";

    private final Lock lock = new ReentrantLock();
    private final Condition condition = lock.newCondition();

    /**
     * Construct a Wicket with only one closed lock.
     */
    public Wicket() {
        this(1);
    }

    /**
     * Construct a Wicket with the given number of closed locks.
     *
     * @param _name Wicket's identifier
     * @param _count the initial number of closed locks
     * @param _debugOutput whether to print debug info or not
     * @throws IllegalArgumentException if count is less than 1
     */
    public Wicket(String _name, int _count, PrintStream _debugOutput) {
        this(_count);
        name = _name;
        debugOutput = _debugOutput;
    }

    /**
     * Construct a Wicket with the given number of closed locks.
     *
     * @param count the initial number of closed locks
     * @throws IllegalArgumentException if count is less than 1
     */
    public Wicket(int count) {
        if (count < 1)
            throw new IllegalArgumentException(
                "count is less than one: " + count);
        this.count = count;
    }

    /**
     * Wait for all locks of this Wicket to be open.
     *
     * <p>If all locks are already open then returns immediately.
     *
     * <p>If at least one lock is still closed then the current thread becomes
     * disabled for thread scheduling purposes and lies dormant until all
     * the locks will be open by some other threads. One lock can be open
     * by invoking the unlock method for this Wicket.
     *
     * <p>Please note, that the method would ignore Thread.interrupt() requests.
     */
    public void waitFor() {
        long id = System.currentTimeMillis();

        lock.lock();
        try {
            ++waiters;
            if (debugOutput != null) {
                debugOutput.printf("Wicket %d %s: waitFor(). There are %d waiters totally now.\n", id, name, waiters);
            }

            while (count > 0) {
                try {
                    condition.await();
                } catch (InterruptedException e) {
                }
            }
            --waiters;
        } finally {
            lock.unlock();
        }
    }

    /**
     * Wait for all locks of this Wicket to be open within the given
     * period of time.
     *
     * <p>If all locks are already open then returns immediately with zero.
     *
     * <p>If the time is equal to zero, the method will not
     * wait and returns a number of closed locks,
     * if all locks are open, the return value is zero.
     *
     * <p>If at least one lock is still closed then the current thread becomes
     * disabled for thread scheduling purposes and lies dormant until
     * of the two things happens:
     *
     *   <ul><li>Some other threads invoke the unlock method for this Wicket
     *   to open all the closed locks; or
     *
     *   <li>The specified waiting time elapses.</ul>
     *
     * <p>If all locks are open then the return value is 0.
     *
     * <p>If the specified waiting time elapses and some locks are still closed
     * then the return value is equal to number of closed locks.
     *
     * <p>Please note, that the method would ignore Thread.interrupt() requests.
     *
     * @param timeout the maximum time to wait in milliseconds
     * @return the number of closed locks
     * @throws IllegalArgumentException if timeout is less than 0
     */
    public int waitFor(long timeout) {
        if (timeout < 0)
            throw new IllegalArgumentException(
                    "timeout value is negative: " + timeout);

        long id = System.currentTimeMillis();

        lock.lock();
        try {
            ++waiters;
            if (debugOutput != null) {
                debugOutput.printf("Wicket %d %s: waitFor(). There are %d waiters totally now.\n", id, name, waiters);
            }

            long waitTime = timeout;
            long startTime = System.currentTimeMillis();

            while (count > 0  && waitTime > 0) {
                try {
                    condition.await(waitTime, TimeUnit.MILLISECONDS);
                } catch (InterruptedException e) {
                }
                waitTime = timeout - (System.currentTimeMillis() - startTime);
            }
            --waiters;
            return count;
        } finally {
            lock.unlock();
        }
    }

    /**
     * Unlock one closed lock.
     *
     * <p>Open a lock, reducing the number of closed locks by one.
     *
     * <p>If last closed lock is opened then all of the threads waiting
     * by invoking the waitFor method for this Wicket will be released
     * and re-enabled for thread scheduling purposes.
     *
     * @throws IllegalStateException if there is no one closed lock
     */
    public void unlock() {

        lock.lock();
        try {
            if (count == 0)
                throw new IllegalStateException("locks are already open");

            --count;
            if (debugOutput != null) {
                debugOutput.printf("Wicket %s: unlock() the count is now %d\n", name, count);
            }

            if (count == 0) {
                condition.signalAll();
            }
        } finally {
            lock.unlock();
        }
    }

    /**
     * Unlock all closed locks.
     *
     * <p>Open all closed locks, setting the number of closed locks to zero.
     *
     * <p>If any threads are waiting by invoking the waitFor method for
     * this Wicket then they will be released and re-enabled for thread
     * scheduling purposes.
     */
    public void unlockAll() {
        if (debugOutput != null) {
            debugOutput.printf("Wicket %s: unlockAll()\n", name);
        }

        lock.lock();
        try {
            count = 0;
            condition.signalAll();
        } finally {
            lock.unlock();
        }
    }

    /**
     * Return current number of waiters - threads that are currently
     * waiting using one of waitFor methods.
     *
     * @return number of waiters
     */
    public int getWaiters() {

        lock.lock();
        try {
            if (debugOutput != null) {
                debugOutput.printf("Wicket %s: getWaiters()\n", name);
            }
            return waiters;
        } finally {
            lock.unlock();
        }
    }
}