Java example source code file (RacingThreadsTest.java)

This example Java source code file (RacingThreadsTest.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

atomicinteger, brokenbarrierexception, cyclicbarrier, driverthread, failed, interruptedexception, n_loops, n_secs, n_threads, racingthreadstest, runtimeexception, string, test_name, threading, threads, workerthread

The RacingThreadsTest.java Java example source code

/*
 * Copyright (c) 2011, 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.
 */

import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.BrokenBarrierException;
import java.util.concurrent.CyclicBarrier;


/**
 * RacingThreadsTest is a support class for creating a test
 * where multiple threads are needed to exercise a code path.
 * The RacingThreadsTest class is typically used as follows:
 * <ul>
 * <li>
 *     Extend RacingThreadsTest class in order to provide the test
 *     specific variables and/or code, e.g., <br>
 *     public class MyRacingThreadsTest extends RacingThreadsTest
 * <li>
 *     Use
 *     "new MyRacingThreadsTest(name, n_threads, n_loops, n_secs)"
 *     to create your test with the specified name and the specified
 *     number of WorkerThreads that execute the test code in parallel
 *     up to n_loops iterations or n_secs seconds.
 * <li>
 *     Use
 *     "new DriverThread(test)"
 *     to create the test DriverThread that manages all the
 *     WorkerThreads. The DriverThread class can be extended to
 *     provide test specific code and/or variables. However, that
 *     is typically done in your test's subclass.
 * <li>
 *     Use
 *     "new WorkerThread(workerNum, test)"
 *     to create WorkerThread-workerNum that executes the test code.
 *     The WorkerThread class can be extended to provide test thread
 *     specific code and/or variables.
 * <li>
 *     Use
 *     "RacingThreadsTest.runTest(driver, workers)"
 *     to run the test. If the test fails, then a RuntimeException
 *     is thrown.
 * </ul>
 *
 * The RacingThreadsTest class provides many methods that can be
 * overridden in order to provide test specific semantics at each
 * identified test execution point. At a minimum, your test's
 * subclass needs to override the
 * "void executeRace(WorkerThread)"
 * method in order to exercise your race condition and it needs to
 * override the
 * "void checkRaceResults(DriverThread)"
 * method in order to check the results of the race. Your
 * checkRaceResults() method should call the
 * "int incAndGetFailCnt()"
 * method when it detects a failure. It can also call the
 * "void unexpectedException(Thread, Exception)"
 * method if it detects an unexpected exception; this will cause
 * an error message to be output and the failure count to be
 * incremented. When the RacingThreadsTest.runTest() method is
 * done running the races, if there is a non-zero failure count,
 * then a RuntimeException will be thrown.
 * <p>
 * The RacingThreadsTest class uses three internal barriers to
 * coordinate actions between the DriverThread and the WorkerThreads.
 * These barriers should not be managed or used by your test's
 * subclass and are only mentioned here to provide clarity about
 * interactions between the DriverThread and the WorkerThreads.
 * The following transaction diagram shows when the different
 * RacingThreadsTest methods are called relative to the different
 * barriers:
 *
 * <pre>
 * DriverThread           WorkerThread-0         WorkerThread-N-1
 * ---------------------  ---------------------  ---------------------
 * run(workers)
 * oneTimeDriverInit()
 * <start WorkerThreads>  run()                  run()
 * <top of race loop>     :                      :
 * perRaceDriverInit()    oneTimeWorkerInit()    oneTimeWorkerInit()
 * :                      <top of race loop>     <top of race loop>
 * :                      perRaceWorkerInit()    perRaceWorkerInit()
 * startBarrier           startBarrier           startBarrier
 * :                      executeRace()          executeRace()
 * finishBarrier          finishBarrier          finishBarrier
 * checkRaceResults()     :                      :
 * resetBarrier           resetBarrier           resetBarrier
 * perRaceDriverEpilog()  perRaceWorkerEpilog()  perRaceWorkerEpilog()
 * <repeat race or done>  <repeat race or done>  <repeat race or done>
 * :                      oneTimeWorkerEpilog()  oneTimeWorkerEpilog()
 * <join WorkerThreads>   <WorkerThread ends>    <WorkerThread ends>
 * oneTimeDriverEpilog()
 * <DriverThread ends>
 * </pre>
 *
 * Just to be clear about the parallel parts of this infrastructure:
 * <ul>
 * <li>
 *     After the DriverThread starts the WorkerThreads, the DriverThread
 *     and the WorkerThreads are running in parallel until the startBarrier
 *     is reached.
 * <li>
 *     After the WorkerThreads leave the startBarrier, they are running
 *     the code in executeRace() in parallel which is the whole point
 *     of this class.
 * <li>
 *     The DriverThread heads straight to the finishBarrier and waits for
 *     the WorkerThreads to get there.
 * <li>
 *     After the DriverThread leaves the finishBarrier, it checks the
 *     results of the race.
 * <li>
 *     The WorkerThreads head straight to the resetBarrier and wait for
 *     the DriverThread to get there.
 * <li>
 *     If this is not the last race, then after the DriverThread and
 *     WorkerThreads leave the resetBarrier, the DriverThread and the
 *     WorkerThreads are running in parallel until the startBarrier
 *     is reached.
 * <li>
 *     If this is the last race, then after the DriverThread and
 *     WorkerThreads leave the resetBarrier, the DriverThread and the
 *     WorkerThreads are running in parallel as each WorkerThread ends.
 * <li>
 *     The DriverThread waits for the WorkerThreads to end and
 *     then it ends
 * </ul>
 *
 * Once the DriverThread has ended, the RacingThreadsTest.runTest()
 * method checks the failure count. If there were no failures, then
 * a "Test PASSed" message is printed. Otherwise, the failure count
 * is printed, a "Test FAILed" message is printed and a RuntimeException
 * is thrown.
 */
public class RacingThreadsTest {
    /**
     * name of the test
     */
    public final String TEST_NAME;
    /**
     * maximum number of test iterations (race loops)
     */
    public final int N_LOOPS;
    /**
     * the maximum number of seconds to execute the test loop
     */
    public final int N_SECS;
    /**
     * number of WorkerThreads
     */
    public final int N_THREADS;

    /**
     * Creates a test with the specified name and the specified number
     * of WorkerThreads that execute the test code in parallel up to
     * n_loops iterations or n_secs seconds. The RacingThreadsTest
     * class is extended in order to provide the test specific variables
     * and/or code.
     * @param name the name of the test
     * @param n_threads the number of WorkerThreads
     * @param n_loops the maximum number of test iterations
     * @param n_secs the maximum number of seconds to execute the test loop
     */
    RacingThreadsTest(String name, int n_threads, int n_loops, int n_secs) {
        TEST_NAME = name;
        N_THREADS = n_threads;
        N_LOOPS = n_loops;
        N_SECS = n_secs;

        finishBarrier = new CyclicBarrier(N_THREADS + 1);
        resetBarrier = new CyclicBarrier(N_THREADS + 1);
        startBarrier = new CyclicBarrier(N_THREADS + 1);
    }


    /**
     * Entry point for exercising the RacingThreadsTest class.
     */
    public static void main(String[] args) {
        // a dummy test:
        // - 2 threads
        // - 3 loops
        // - 2 seconds
        // - standard DriverThread
        // - standard WorkerThread
        RacingThreadsTest test = new RacingThreadsTest("dummy", 2, 3, 2);
        DriverThread driver = new DriverThread(test);
        WorkerThread[] workers = new WorkerThread[2];
        for (int i = 0; i < workers.length; i++) {
            workers[i] = new WorkerThread(i, test);
        }
        test.runTest(driver, workers);
    }

    private static volatile boolean done = false;  // test done flag

    // # of fails; AtomicInteger since any WorkerThread can increment
    private static final AtomicInteger failCnt = new AtomicInteger();
    // # of loops; volatile is OK since only DriverThread increments
    // but using AtomicInteger for consistency
    private static final AtomicInteger loopCnt = new AtomicInteger();
    private static boolean verbose
        = Boolean.getBoolean("RacingThreadsTest.verbose");

    // barriers for starting, finishing and resetting the race
    private final CyclicBarrier finishBarrier;
    private final CyclicBarrier resetBarrier;
    private final CyclicBarrier startBarrier;


    /**
     * Get current done flag value.
     * @return the current done flag value
     */
    public boolean getDone() {
        return done;
    }

    /**
     * Set done flag to specified value.
     * @param v the new done flag value
     */
    public void setDone(boolean v) {
        done = v;
    }

    /**
     * Get current failure counter value.
     * @return the current failure count
     */
    public int getFailCnt() {
        return failCnt.get();
    }

    /**
     * Increment and get current failure counter value.
     * @return the current failure count after incrementing
     */
    public int incAndGetFailCnt() {
        return failCnt.incrementAndGet();
    }

    /**
     * Get current loop counter value.
     * @return the current loop count
     */
    public int getLoopCnt() {
        return loopCnt.get();
    }

    /**
     * Increment and get current loop counter value.
     * @return the current loop count after incrementing
     */
    public int incAndGetLoopCnt() {
        return loopCnt.incrementAndGet();
    }

    /**
     * Get current verbose flag value.
     * @return the current verbose flag value
     */
    public boolean getVerbose() {
        return verbose;
    }

    /**
     * Set verbose flag to specified value.
     * @param v the new verbose flag value
     */
    public void setVerbose(boolean v) {
        verbose = v;
    }

    /**
     * Run the test with the specified DriverThread and the
     * specified WorkerThreads.
     * @param driver the DriverThread for running the test
     * @param workers the WorkerThreads for executing the race
     * @exception RuntimeException the test has failed
     */
    public void runTest(DriverThread driver, WorkerThread[] workers) {
        driver.run(workers);

        try {
            driver.join();
        } catch (InterruptedException ie) {
            unexpectedException(Thread.currentThread(), ie);
            // fall through to test failed below
        }

        if (failCnt.get() == 0) {
            System.out.println(TEST_NAME + ": Test PASSed.");
        } else {
            System.out.println(TEST_NAME + ": failCnt=" + failCnt.get());
            System.out.println(TEST_NAME + ": Test FAILed.");
            throw new RuntimeException("Test Failed");
        }
    }

    /**
     * Helper method for reporting an unexpected Exception and
     * calling incAndGetFailCnt();
     * @param t the Thread that caught the exception
     * @param e the Exception that was caught
     */
    public void unexpectedException(Thread t, Exception e) {
        System.err.println(t.getName() + ": ERROR: unexpected exception: " + e);
        incAndGetFailCnt();  // ignore return
    }


    // The following methods are typically overridden by the subclass
    // of RacingThreadsTest to provide test specific semantics at each
    // identified test execution point:

    /**
     * Initialize 1-time items for the DriverThread.
     * Called by the DriverThread before WorkerThreads are started.
     * @param dt the DriverThread
     */
    public void oneTimeDriverInit(DriverThread dt) {
        if (verbose)
            System.out.println(dt.getName() + ": oneTimeDriverInit() called");
    }

    /**
     * Initialize 1-time items for a WorkerThread. Called by a
     * WorkerThread after oneTimeDriverInit() and before the
     * WorkerThread checks in with startBarrier. May execute in
     * parallel with perRaceDriverInit() or with another
     * WorkerThread's oneTimeWorkerInit() call or another
     * WorkerThread's perRaceWorkerInit() call.
     * @param wt the WorkerThread
     */
    public void oneTimeWorkerInit(WorkerThread wt) {
        if (verbose)
            System.out.println(wt.getName() + ": oneTimeWorkerInit() called");
    }

    /**
     * Initialize per-race items for the DriverThread. Called by the
     * DriverThread before it checks in with startBarrier. May execute
     * in parallel with oneTimeWorkerInit() and perRaceWorkerInit()
     * calls. After any race except for the last race, this method may
     * execute in parallel with perRaceWorkerEpilog().
     * @param dt the DriverThread
     */
    public void perRaceDriverInit(DriverThread dt) {
        if (verbose)
            System.out.println(dt.getName() + ": perRaceDriverInit() called");
    }

    /**
     * Initialize per-race items for a WorkerThread. Called by each
     * WorkerThread before it checks in with startBarrier. On the first
     * call, this method may execute in parallel with another
     * WorkerThread's oneTimeWorkerInit() call. On any call, this method
     * may execute in parallel with perRaceDriverInit() or another
     * WorkerThread's perRaceWorkerInit() call. After any race except
     * for the last race, this method may execute in parallel with
     * perRaceDriverEpilog() or another WorkerThread's
     * perRaceWorkerEpilog() call.
     * @param wt the WorkerThread
     */
    public void perRaceWorkerInit(WorkerThread wt) {
        if (verbose)
            System.out.println(wt.getName() + ": perRaceWorkerInit() called");
    }

    /**
     * Execute the race in a WorkerThread. Called by each WorkerThread
     * after it has been released from startBarrier.
     * @param wt the WorkerThread
     */
    public void executeRace(WorkerThread wt) {
        if (verbose)
            System.out.println(wt.getName() + ": executeRace() called");
    }

    /**
     * Check race results in the DriverThread. Called by the DriverThread
     * after it has been released from finishBarrier and before the
     * DriverThread checks in with resetBarrier.
     * @param dt the DriverThread
     */
    public void checkRaceResults(DriverThread dt) {
        if (verbose)
            System.out.println(dt.getName() + ": checkRaceResults() called");
    }

    /**
     * Handle end-of-race items for the DriverThread. Called by the
     * DriverThread after it has been released from resetBarrier and
     * before the DriverThread checks in again with startBarrier. Can
     * execute in parallel with perRaceWorkerEpilog(). If this is not
     * the last race, can execute in parallel with perRaceWorkerInit().
     * If this is the last race, can execute in parallel with
     * oneTimeWorkerEpilog().
     * @param dt the DriverThread
     */
    public void perRaceDriverEpilog(DriverThread dt) {
        if (verbose)
            System.out.println(dt.getName() + ": perRaceDriverEpilog() called");
    }

    /**
     * Handle end-of-race items for a WorkerThread. Called by each
     * WorkerThread after it has been released from resetBarrier and
     * before the WorkerThread checks in again with startBarrier.
     * Can execute in parallel with perRaceDriverEpilog() or another
     * WorkerThread's perRaceWorkerEpilog() call. If this is not the
     * last race, can execute in parallel with perRaceDriverInit(),
     * or another WorkerThread's perRaceWorkerInit() call. If this
     * is the last race, can execute in parallel with another
     * WorkerThread's oneTimeWorkerEpilog() call.
     * @param wt the WorkerThread
     */
    public void perRaceWorkerEpilog(WorkerThread wt) {
        if (verbose)
            System.out.println(wt.getName() + ": perRaceWorkerEpilog() called");
    }

    /**
     * Handle end-of-test items for a WorkerThread. Called by each
     * WorkerThread after it has detected that all races are done and
     * before oneTimeDriverEpilog() is called. Can execute in parallel
     * with perRaceDriverEpilog(), with another WorkerThread's
     * perRaceWorkerEpilog() call or with another WorkerThread's
     * oneTimeWorkerEpilog() call.
     * @param wt the WorkerThread
     */
    public void oneTimeWorkerEpilog(WorkerThread wt) {
        if (verbose)
            System.out.println(wt.getName() + ": oneTimeWorkerEpilog() called");
    }

    /**
     * Handle end-of-test items for the DriverThread. Called by the
     * DriverThread after all the WorkerThreads have called
     * oneTimeWorkerEpilog().
     * @param dt the DriverThread
     */
    public void oneTimeDriverEpilog(DriverThread dt) {
        if (verbose)
            System.out.println(dt.getName() + ": oneTimeDriverEpilog() called");
    }


    /**
     * DriverThread for executing the test.
     */
    public static class DriverThread extends Thread {
        private final RacingThreadsTest test;

        /**
         * Create the test DriverThread that manages all the WorkerThreads.
         * The DriverThread class can be extended to provide test specific
         * variables and/or code. However, that is typically done in the
         * subclass of RacingThreadsTest.
         * @parameter test the RacingThreadsTest being run
         */
        DriverThread(RacingThreadsTest test) {
            super("DriverThread");
            this.test = test;
        }

        private void run(WorkerThread[] workers) {
            System.out.println(getName() + ": is starting.");
            System.out.println(getName() + ": # WorkerThreads: " + test.N_THREADS);
            System.out.println(getName() + ": max # loops: " + test.N_LOOPS);
            System.out.println(getName() + ": max # secs: " + test.N_SECS);

            // initialize 1-time items for the DriverThread
            test.oneTimeDriverInit(this);

            // start all the threads
            for (int i = 0; i < workers.length; i++) {
                workers[i].start();
            }

            // All WorkerThreads call oneTimeWorkerInit() and
            // perRaceWorkerInit() on the way to startBarrier.

            long endTime = System.currentTimeMillis() + test.N_SECS * 1000;

            for (; !test.getDone() && test.getLoopCnt() < test.N_LOOPS;
                test.incAndGetLoopCnt()) {

                if (test.getVerbose() && (test.N_LOOPS < 10 ||
                    (test.getLoopCnt() % (test.N_LOOPS / 10)) == 0)) {
                    System.out.println(getName() + ": race loop #"
                        + test.getLoopCnt());
                }

                // initialize per-race items for the DriverThread
                test.perRaceDriverInit(this);

                try {
                    // we've setup the race so start it when all
                    // WorkerThreads get to the startBarrier
                    test.startBarrier.await();
                } catch (BrokenBarrierException bbe) {
                    test.unexpectedException(this, bbe);
                    return;
                } catch (InterruptedException ie) {
                    test.unexpectedException(this, ie);
                    return;
                }

                // All WorkerThreads are racing via executeRace()
                // at this point

                // wait for all threads to finish the race
                try {
                    test.finishBarrier.await();
                } catch (BrokenBarrierException bbe) {
                    test.unexpectedException(this, bbe);
                    return;
                } catch (InterruptedException ie) {
                    test.unexpectedException(this, ie);
                    return;
                }
                // All WorkerThreads are heading to resetBarrier at this
                // point so we can check the race results before we reset
                // for another race (or bail because we are done).

                test.checkRaceResults(this);

                if (test.getLoopCnt() + 1 >= test.N_LOOPS ||
                    System.currentTimeMillis() >= endTime) {
                    // This is the last loop or we're out of time.
                    // Let test threads know we are done before we release
                    // them from resetBarrier
                    test.setDone(true);
                }

                // release the WorkerThreads from resetBarrier
                try {
                    test.resetBarrier.await();
                } catch (BrokenBarrierException bbe) {
                    test.unexpectedException(this, bbe);
                    return;
                } catch (InterruptedException ie) {
                    test.unexpectedException(this, ie);
                    return;
                }

                // All WorkerThreads call perRaceWorkerEpilog(). If
                // this is not the last loop, then all WorkerThreads
                // will also call perRaceWorkerInit() on the way to
                // startBarrier. If this is the last loop, then all
                // WorkerThreads will call oneTimeWorkerEpilog() on
                // their way to ending.

                // handle end-of-race items for the DriverThread
                test.perRaceDriverEpilog(this);
            }

            System.out.println(getName() + ": completed " + test.getLoopCnt()
                + " race loops.");
            if (test.getLoopCnt() < test.N_LOOPS) {
                System.out.println(getName() + ": race stopped @ " + test.N_SECS
                    + " seconds.");
            }

            for (int i = 0; i < workers.length; i++) {
                try {
                    workers[i].join();
                } catch (InterruptedException ie) {
                    test.unexpectedException(this, ie);
                    return;
                }
            }

            // handle end-of-test items for the DriverThread
            test.oneTimeDriverEpilog(this);

            System.out.println(getName() + ": is done.");
        }
    }


    /**
     * WorkerThread for executing the race.
     */
    public static class WorkerThread extends Thread {
        private final RacingThreadsTest test;
        private final int workerNum;

        /**
         * Creates WorkerThread-N that executes the test code. The
         * WorkerThread class can be extended to provide test thread
         * specific variables and/or code.
         * @param workerNum the number for the new WorkerThread
         * @parameter test the RacingThreadsTest being run
         */
        WorkerThread(int workerNum, RacingThreadsTest test) {
            super("WorkerThread-" + workerNum);
            this.test = test;
            this.workerNum = workerNum;
        }

        /**
         * get the WorkerThread's number
         * @return the WorkerThread's number
         */
        public int getWorkerNum() {
            return workerNum;
        }

        /**
         * Run the race in a WorkerThread.
         */
        public void run() {
            System.out.println(getName() + ": is running.");

            // initialize 1-time items for the WorkerThread
            test.oneTimeWorkerInit(this);

            while (!test.getDone()) {
                // initialize per-race items for the WorkerThread
                test.perRaceWorkerInit(this);

                try {
                    test.startBarrier.await();  // wait for race to start
                } catch (BrokenBarrierException bbe) {
                    test.unexpectedException(this, bbe);
                    return;
                } catch (InterruptedException ie) {
                    test.unexpectedException(this, ie);
                    return;
                }

                // execute the race for the WorkerThread
                test.executeRace(this);

                try {
                    test.finishBarrier.await();  // this thread is done
                } catch (BrokenBarrierException bbe) {
                    test.unexpectedException(this, bbe);
                    return;
                } catch (InterruptedException ie) {
                    test.unexpectedException(this, ie);
                    return;
                }

                try {
                    test.resetBarrier.await();  // wait for race to reset
                } catch (BrokenBarrierException bbe) {
                    test.unexpectedException(this, bbe);
                    return;
                } catch (InterruptedException ie) {
                    test.unexpectedException(this, ie);
                    return;
                }

               // handle end-of-race items for the WorkerThread
                test.perRaceWorkerEpilog(this);
            }

            // handle end-of-test items for the WorkerThread
            test.oneTimeWorkerEpilog(this);

            System.out.println(getName() + ": is ending.");
        }
    }
}