CSC254 - Project 1
Interrupted Threads

Assigned September 11th 2 p.m.
First Half Due September 20th 2 p.m.
Second Half Due September 25th 2 p.m.

Updates

The project is now extended until Sep 25th. The first half (coding of the PrizeMoney and the single-threaded CarnivalBooth classes) is still due on Sep 20th.

Overview

In this project you will be learning how to manage a multi-threaded program using the Java Thread API. You will be simulating a small betting game, where one thread responds to a clock timer to raise the stakes and another listens for user input of when to stop.

Description

Some betting opportunities are just too good to pass up. Or at least they feel that way until they make you broke, such as a Three Card Monte game on the streets of New York City. In this project you will create one such game based on the Gambler's fallacy, using multiple threads to provide real-time interaction with the user. We will be modeling the following scenario:

Bob is visiting a carnival, and one booth looks like a great opportunity to make some money. The sign over the top of the booth says "Double or Nothing," and Bob have 10 dollars in his pocket, so he gives it a chance. The attendant says, "Place your bet, and try to double your money. I'll flip a coin each second, if it's heads, your bet is doubled and I'll flip again next second. If you every want me to stop flipping, just say so and you can leave with whatever you've won. If I ever flip tails, you lose your bet and any accumulated winnings." Sounds simple to Bob, with a 50% chance of doubling your money each flip, so he bets 5 dollars. The attendant flips, and its heads, Bob just won 5 dollars already; the attendant flips again, it's heads, and Bob wins another 10 dollars, this is great; the attendant flips again, and it's tails, so Bob loses everything. Left with 5 dollars now, Bob sees it's not so easy, and goes off in search of the Tilt-A-Whirl.

Will you be as lucky as Bob and escape without going broke?

Coding

This project will make heavy use of three classes in the Java API:

Download the Utilities.java class, it contains methods which simplify the processes of talking to the user in Java.

You are required to write four classes for this project, each of which is described here. You can write other methods and classes if you wish, but you must have these defined.

PrizeMoney.java
This instantiable class will keep track of the prize winnings for the current bet. It will be used by both the CarnivalBooth class and CoinFlipper class to communicate across threads as a shared data structure. PrizeMoney must have the following methods:
- PrizeMoney(int money, int factor)
  The constructor for this class, which will set up the object to have an initial value of money, and a multiplying factor of factor.
- int getMoney()
  Will return the current value for the accumulated winnings.
- void increase()
  This will increase the money in this object, multiplying it by factor.
- void crash()
  This method will wipe out any accumulated winnings, such that any subsequent call of getMoney will return 0.
CoinFlipper.java
This class will implement the Runnable interface. CoinFlipper must have the following methods:
- CoinFlipper(PrizeMoney pm, double bias)
  The constructor will take a PrizeMoney object and the bias for the coin it will be flipping.
- void run()
  This method will do the work of flipping the coin in response to the clock timer in the computer. Every second it will flip a coin with a biased chance of coming up head. If the coin is heads, the prize is increased and the process is repeated, but if it is tails, the prize crashes to zero and the thread exits. If the thread is ever interrupted, it should immediately exit without flipping the coin one more time.
UserListener.java
This class will also implement the Runnable interface. UserListener will wait for the user to hit the enter key and stop the coin flipping in real-time. UserListener must have the following methods:
- UserListener(String prompt)
  The constructor will take in a String to be the prompt for listening to the user.
- void run()
  This method will listen to the user and wait until they hit the Enter key. It should wake up every tenth of a second to listen to the user, and when Enter is pressed, the prompt should be printed and the thread should exit. If the thread is ever interrupted, it should immediately exit.
CarnivalBooth.java
This will be the driver class, including only the main method for running the simulation. Call this class with three arguments, the first being the multiplication factor, an integer, the second being the bias of the coin being used, a double, and the third being the initial amount of money the user has available to bet. Your program should exit gracefully on invalid input and print a usage message. For example:
```
% java CarnivalBooth 2 0.5 10
```
is valid input and should run the program. However,
```
% java CarnivalBooth 0.5 2
```
should result in the following output:
```
Usage: java CarnivalBooth "factor" "bias" "money"
```
When invoked, the main method will print out a brief description of the game to the user, and then ask them how much they would like to wager. Upon entering the bet, the program will launch two threads, one for the CoinFlipper and one for the UserListener. As soon as one of these threads is finished, the other must be interrupted. If the CoinFlipper exited first, this means there was a Tails flipped and the user wins nothing. If the UserListener exited first this means the user wanted to stop with his/her accumulated winnings. In either case, add the prize money to the users' money.
If the user has money left, tell them how much money they have and ask if they would like to bet again. If the user is out of money, say goodbye and exit the program.

Testing

When writing this program, a good first step might be to implement a non-threaded approach, where the user is prompted before each new coin flip. This will allow you to focus on the logic of running the Carnival Booth without worrying about the Threads. Once this is complete, add in the multi-threaded behavior to your program. When testing the multi-threaded program, I recommend you raise the bias towards flipping heads. This will give you more time to test out the ability of your program to react to user input and halt the CoinFlipper thread.

Test out your program with the values of factor = 2, bias = 0.5, initial = 10, and run your code 5 times with you as the user. Report on your winnings (or losses) and how many iterations you played each game. Be sure to play at least one game until you have lost everything.

Restrictions

For this project, you are not allowed to use the stop() method to halt a running thread. You must use the interrupt() method on a thread, and that thread must handle this by checking isInterrupted() before proceeding with critical code.

What to Hand In

Log in to the cs.centenary.edu server. Create a subdirectory from your csc254 directory called project1 and make it read, write and execute privileges for only the owner (chmod 700).

You must hand in your files for:

PrizeMoney.java
CoinFlipper.java
UserListener.java
CarnivalBooth.java

along with the provided file:

Utilities.java

CSC254 - Project 1Interrupted Threads

Assigned September 11th 2 p.m. First Half Due September 20th 2 p.m. Second Half Due September 25th 2 p.m.