/*
 * cs101 producer/consumer (single integer) buffer
 * $Id: IntBuffer.java,v 1.9 2003/09/23 15:37:30 gus Exp $
 *
 * Developed for "Rethinking CS101", a project of Lynn Andrea Stein's AP Group.
 * For more information, see <a href="http://www.ai.mit.edu/projects/cs101/">the
 * CS101 homepage</a> or email <las@ai.mit.edu>.
 *
 * Please do not redistribute without obtaining permission.
 */

package cs101.util.semaphore;

/**
 * Implements a producer/consumer synchronized buffer. <br>
 * Interface is IntBuffer.putButton( int ), IntBuffer.getButton(). This class
 * does guarantee that no value written to it will be overwritten before it
 * has been read and also guarantees that once a value has been read it will
 * not be re-read on subsequent attempts. <p>
 *
 * <em>This class only behaves well when a single thread is reading the buffer
 * and a single thread is writing to the buffer, or the order in which events
 * are processed is unimportant. This class doesn't guarantee
 * that competing threads will get to write in a sensible order, and does
 * not guarantee that competing threads will get to read from the buffer
 * in a sensible order</em>
 *
 * @see    cs101.util.semaphore.BS
 *
 * @author  Lynn Andrea Stein, las@ai.mit.edu
 * @author  Patrick G. Heck, gus.heck@olin.edu
 * @version $Id: IntBuffer.java,v 1.9 2003/09/23 15:37:30 gus Exp $
 *
 */
public final class IntBuffer {
    private int button;
    private BS buttonRead = new BS(true);
    private BS buttonWrite = new BS(false);
    
    //putButton( int )
    /**
     * An alternate (calculator oriented) name for {@link #putInt(int)}.
     *
     * @param    newButton    the button to be inserted.
     *
     * @see #getButton
     * @see cs101.util.semaphore.BS
     */
    public void putButton( int newButton ) {
        this.putInt(newButton);
    }
    
    // getButton()
    /**
     * An alternate (caluculator oriented) name for {@link #getInt}.
     *
     * @return    the next button.
     *
     * @see #putButton
     * @see cs101.util.semaphore.BS
     */
    public int getButton() {
        return this.getInt();
    }
    
    //putButton( int )
    /**
     * (Safely) Puts an int into the IntBuffer.
     *
     * @param    newButton    the value to be inserted.
     *
     * @see #getButton
     * @see cs101.util.semaphore.BS
     */
    public void putInt( int newButton ) {
        this.buttonWrite.request();
        this.button = newButton;
        this.buttonRead.release();
    }
    
    // getButton()
    /**
     * (Safely) Consumes the int held in the IntBuffer.
     *
     * @return    the integer value.
     *
     * @see #putButton
     * @see cs101.util.semaphore.BS
     */
    public int getInt() {
        this.buttonRead.request();
        int b = this.button;
        this.buttonWrite.release();
        return b;
    }
}

/* Comments:
 *
 * History:
 *     $Log: IntBuffer.java,v $
 *     Revision 1.9  2003/09/23 15:37:30  gus
 *     javadoc fix
 *
 *     Revision 1.8  2003/09/23 14:42:16  gus
 *     javadoc change
 *
 *     Revision 1.7  2003/02/27 15:53:39  gus
 *     make me an author
 *
 *     Revision 1.6  2003/02/27 15:49:55  gus
 *     provided a more generic interface while maintianing the button oriented interface
 *     used by the calculator problem set
 *
 *     Revision 1.5  2003/02/27 15:38:31  gus
 *     Javadoc tweaks
 *
 *     Revision 1.4  2003/02/26 19:37:15  gus
 *     expanded class doc comment.
 *
 *     Revision 1.3  2002/11/25 15:36:22  gus
 *     fix typo in last vix.
 *
 *     Revision 1.2  2002/11/25 15:24:20  gus
 *     fix javadoc errors
 *
 *     Revision 1.1.1.1  2002/06/05 21:56:32  root
 *     CS101 comes to Olin finally.
 *
 *     Revision 1.1  2000/04/24 22:17:22  nathanw
 *     Bulk reorganization
 *
 *     Revision 1.2  1998/07/24 17:19:28  tparnell
 *     Placate new javadoc behavior
 *
 *     Revision 1.1  1998/03/13 22:18:15  tparnell
 *     Import from server crash.  I think the src and class files match up.
 *
 *     Revision 1.3  1996/08/01 18:26:28  reuben
 *     More javadoc tweaking (hopefully the final pass)
 *
 *     Revision 1.2  1996/07/30 17:26:00  reuben
 *     Added/corrected javadoc comments.
 *
 *     Revision 1.1.1.1  1996/07/18 17:38:24  sit
 *     Import from /mit/6.096/share/classes after 6.80s session
 *
 *     Revision 1.1  1996/06/25 22:23:36  las
 *     Initial revision
 *
 *     6-25-96  Created by las@ai.mit.edu from PNCBuffer.java
 *
 *     Revision 1.4  1996/06/19 23:03:02  las
 *     Oops.  Renamed BS's methods to correspond with reality.
 *
 *     6-19-96  Documentation cleaned up by las@ai.mit.edu
 *     6-18-96  Created by las@ai.mit.edu
 *
 */