001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package com.sun.midp.util;
028:
029: /**
030: * A concurrency control mechanism, a virtual baton that can be passed between
031: * two threads to control the order of execution. The main operation is
032: * pass(), which unblocks the other thread and then blocks this thread until
033: * the other thread passes the baton back.
034: *
035: * A typical use case is as follows:
036: *
037: * 1. Thread A creates the baton and passes it to thread B.
038: * 2. Thread A calls start() to wait for thread B to get to a known state.
039: * 3. Thread B calls pass() to pass the baton to A, and then B blocks.
040: * 4. Thread A unblocks does stuff, then calls pass() to pass the baton
041: * to B, and then A blocks.
042: * 4. Threads A and B alternately call pass() so that they execute in
043: * lock step.
044: * 5. One of the threads calls finish() to let the other thread continue
045: * indefinitely, ending the use of the baton.
046: *
047: * The baton can be passed between threads up to Integer.MAX_VALUE - 1 times
048: * before it ceases to function.
049: */
050: public class Baton {
051: int count;
052:
053: /**
054: * Creates a new baton.
055: */
056: public Baton() {
057: count = 0;
058: }
059:
060: /**
061: * Starts the protocol by waiting for the first pass from the other
062: * thread.
063: *
064: * @throws IllegalStateException if called after the protocol has been
065: * started
066: */
067: public synchronized void start() {
068: if (count > 1) {
069: throw new IllegalStateException();
070: }
071: await(1);
072: }
073:
074: /**
075: * Passes the baton to the other thread, unblocking it, and blocks until
076: * the baton is passed back. After finish() is called, simply returns
077: * without doing anything.
078: */
079: public synchronized void pass() {
080: if (count < Integer.MAX_VALUE) {
081: count++;
082: notifyAll();
083: await(count + 1);
084: }
085: }
086:
087: /**
088: * Tells the other thread continue, and then returns. After a call to
089: * finish(), the baton becomes inoperative, and calls to pass() simply
090: * return.
091: */
092: public synchronized void finish() {
093: count = Integer.MAX_VALUE;
094: notifyAll();
095: }
096:
097: private void await(int seq) {
098: while (count < seq) {
099: try {
100: wait();
101: } catch (InterruptedException ignore) {
102: }
103: }
104: }
105: }
|