CMPSCI 377: Operating Systems
Lab 2: Threads and Synchronization

Due: March 24, 2003 23:30

Addenda

JToggleButton btStart = new JToggleButton("Run"); 
getContentPane().add(btStart,BorderLayout.NORTH);       // Add button
getContentPane().add(gridcanvas, BorderLayout.CENTER);  // Add panel for drawing

btStart.addActionListener(new ActionListener() {
      	
          public void actionPerformed(ActionEvent ae){
             
	      if (btStart.getText()=="Run"){
                 // DO WHATEVER TO START THE ROBOTS RUNNING

	         btStart.setEnabled(false); //disable the button
	       }             
	  }
	  });

March 2: You may now download and execute our solution: RW.jar (execute using the following: java -jar RW.jar fname

Purpose of Assignment

Grading

• Program Design and Implementation: 40%
• Correctness: 40%
• Documentation: 20%

You may work with one other person in the class. If you choose to do so, please send email to the professor and the TAs in order to indicate who your partner will be and which of the two of you will be handing in the program. Do not share/accept code with/from anyone else or from the net.

Where to do your work

~/cs377/lab2

If your files are not located in the right place or our robot cannot read your homework at the time of submission, then we will not be able to grade it. In order to make sure that our robot can pick up your program, please check things by executing the ~fagg/bin/checkhw script with the lab2 parameter.

You need only hand-in one copy of your program.

The Problem

Your program must:

1. As in lab 1, your program must parse the map file and place the information into an appropriate data structure (one is provided). Your program should detect and trap any errors that might exist in the file and display an appropriate error message. The file format is identical to that of lab 1.

2. Create a thread that will control the movements of each robot (if there are N robots, then there will be N threads). This thread must run at NORM_PRIORITY. Be careful that the individual robot threads do not make conflicting updates to the common data structures.

3. Create a thread that will update the display at regular intervals. This thread must run at NORM_PRIORITY+1 and execute at approximately 30 millisecond intervals.

4. Create a thread that will write the position of each robot to a file ("log.txt") at regular (50 ms) intervals. This thread must also run at NORM_PRIORITY+1. Be careful to ensure that only valid data is written to the file. See the example map1.log for the map1.txt file. See below for more details of the format of the log file.

5. Create one thread for each color class of robot (so a total of 3). This thread will compute the distance matrices used in making robot movement decisions.

6. In order to ensure that the different threads do not interfere with one-another, you must identify their critical sections and use the appropriate synchronization primitives in your code (see below for a few more hints on this).

The rules for the world physics are as follows:

1. Robots may only eat goals that are either black or their own color.

2. Once a goal is eaten, it is removed from the display and cannot be eaten again. This is indicated in the data structure by setting isEaten to true (see below).

3. At each step, a robot may only move one square in the up/down/left/right directions.

4. Robots may not move to a grid square that is occupied by an obstacle, by another robot, or by goals that are not black or their own color (i.e., goals of other colors are considered obstacles).

5. When a robot no longer has edible goals to consume, it dies and stops moving. This is indicated in the data structure by setting bDead to true (see below). Once a robot is dead, it can no longer move.

What we provide:

1. A predefined, public data structure that describes the grid and and the locations of the robots, obstacles and goals. This is defined in Map_Data.java.

2. A predefined, public data structure that describes a goal. This is defined in Goal.java.

3. A predefined data structure that extends the thread class and defines the Abstract_Robot class (Abstract_Robot.java). This class must be extended by you to implement the movement of the robots and to handle all of the necessary bookkeeping.

4. A predefined class Abstract_Distance (Abstract_Distance.java) that provides the functionality for calculating the distance matrix for each robot color class. In particular, this abstract class provides:
   1. A distance matrix (dist[][]) that represents the distance from any grid square to the closest, appropriate goal (black or one that matches the color of the robot). A value of MAX_VALUE indicates that an obstacle or a dead robot is located at this grid square. A value of -1 indicates that there is no goal that can be reached from this grid location.

   2. A predefined method (SetDist()) that takes information about the obstacles, goals, and robots and fills in the distance data structure with the appropriate values.

   You must extend this class by providing a run() method that selects the appropriate time at which to recalculate the distance matrix. It is important that you trigger this recalculation in as efficient manner as possible (i.e., no busy waiting). Hint: think about the tools that we have been learning about in class.

   Robots of the same color will share a single instance of distance matrix. Each time that a robot is going to take a next step, it should check the distance matrix and choose to move to the nearby grid cell that is of minimum value that is also free of obstacles, robots, and non-matching goals. If all values are -1, it means that no goals are currently reachable by the robot; in this case, the robot should not move.

5. An implementation of a semaphore object. This is defined in Semaphore.java. This is the only synchronization primitive that you should use (unless you talk to the Instructor first).

1. Your program must start by creating and painting the window. Only after a user input (e.g., by pressing of a 'Start' button or a key) should the robots start moving.

2. Robots must sleep for 200 milliseconds between steps so as to give other robots an opportunity to move.

3. Once the robots have completed their movements, the window must continue to stay visible until explicitly killed by the user.

4. The distance matrices must be explicitly updated under two conditions: when a robot eats a goal and when a robot dies.

What to Hand In

Place in your Hand-In directory the following:

• An appropriately documented set of java source files (e.g., "lab2.java")
• An executable class that you have compiled for and tested on the elnux system. We will test this executable using shell commands similar to the following: "java lab2 map1.txt"
• A "lab2.txt" file (raw ASCII format) that contains:
  • Your name(s)
  • Your UID(s)
  • The name of your top-level java class
  • The answers to the following questions:

    1. In what ways did you employ semaphores in your program?

    2. What do you expect would happen if you removed the synchronization mechanisms that you have used?

    3. Explain what happens when you execute your program with the map specified by map.strange.txt. If it fails, explain why. How might you use operating systems techniques in order to prevent this failure from happening (for this specific map, not for any map)? If it does not fail, explain how you might use operating systems techniques to make things more efficient (i.e., prevent one robot from having to back up).

    4. How much time did you spend (collectively) on this assignment?

We will test your program with a variety of maps, including:

• map1.txt
• map2.txt
• map3.txt
• map4.txt
• map5.txt
• map6.txt
• map7.txt
• map8.txt
• map9.txt
• map.strange.txt
• map.bad1.txt
• map.bad2.txt

Checking Your Results

<file> := <line>+
<line> := <N> goals left; <robot>+
<N> := [0...9]+
<robot> := <DEAD>? Robot<N> <color> At [<N>,<N>];
<DEAD> := (Dead)
<color> := Red | Green | Blue

In particular:

• There is exactly one line for each logged time step.
• Each line contains an entry for each robot

We have provided the checklog script that will scan your log.txt file and confirm that no two robots ever occupy the same grid square, and that all goals are consumed by the end of the run (this script should be in your executable path). The script terminates with an "ALL OK" if these two conditions are met. The log files generated by your program should generally check out OK; if they do not, this may be indicative of a problem in your program. Please be sure to ask if there are any questions.

We will also use this script to check your programs (but note that this will not be the only check that we do).

Here are the log files that our program generates (note that these are not unique):

• map1.log
• map2.log
• map3.log
• map4.log
• map5.log
• map6.log
• map7.log
• map8.log
• map9.log
• map.strange.log

Here are some log files that our program generates when proper thread synchronization is not used:

• map4.broken.log
• map5.broken.log
• map9.broken.log

Some Comments/Hints

• You must use the implementation of Abstract_Robot, Abstract_Distance, Goal, Map_Data, and Semaphore. Do not change their implementation, as we've made some things hard on purpose.

• Think carefully about how to use the semaphore. There are three distinct opportunities in this lab to use semaphores...

• It is not a problem that robots use out-dated distance matrix information, but it is a problem if they use invalid data. So - be a little careful here.

• Make sure that robots do not start using the distance matrix until after the first call to SetDist() has been made for all three matrices.

• There is an odd condition where one or more robots will die in such a way that the path is blocked for other robots. You can choose to handle this case or not (to do this in general is non-trivial).

• Depending upon your implementation, the behavior of your robots (and hence your log files) will be different that the ones that we give. In addition, there may be some legitimate reasons that your program does not complete with all goals eaten (we are not using the most sophisticated path planner here). We anticipate that your program should not have difficulties except where otherwise noted (since ours does not have trouble); if there are any questions about correct behavior, please send email.

• Remember that you cannot create an instance of an abstract class in Java. However, you will note that several of our classes include sub-objects that are of an abstract type. Instead of assigning a new instance of an abstract class to one of these variables, you must assign an instance of the class that extends the abstract class.

• Note that several of our datastructures involve circular references. Be sure that you create things in the right order and attach all of the appropriate links.

• To force the display to update, you should call the repaint() method that is provided by JPanel. This will implicitly call the paintComponent() method of your extension of JPanel.

  For more information on swing, see the Creating a GUI with JFC/Swing train.

Java Hints

• Java Tutorial
• Java API Documentation