CMPSCI 377: Operating Systems
Lab 2: Threads and Synchronization
OFFICIAL VERSION

Due: October 23, 2002 23:59


Updates

October 22: We talked in class today about the confusion between the row/col and the X/Y coordinate systems. The robot and goal positions are specified in row/column format. In the code that we have supplied, the implicit assumption that we made is that X==row and Y==col. Yes, it is confusing. Rather than make changes to the base code at this late hour (as I suggested that I might do in class), I think it is best that we do not do this at the risk of introducing other bugs. Please adjust your code accordingly. Sorry for the confusion.

Purpose of Assignment

This assignment will give you experience in the creation and management of multiple, interacting threads.

Grading

This lab project will count for 30% of your lab grade (so 11.7% of your final grade).

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 the net.

Where to do your work

For this lab, place your final submission in the following directory:

~/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

For this lab, we are solving a problem involving multiple, coordinated robots. As you have already discovered in lab 1, an input file specifies a map, some set of robots of various colors (red, green, and blue), and some set of goals (red, green, blue, and black). The robots and goals "live" on a discrete grid of a specific size (think graph paper). Some grid squares are occupied by obstacles. The task is for the individual robots to move around on the grid and "eat" goals without running into each other or any obstacles.

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 (100 ms) intervals. 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. Once all goals are consumed, the program must detect this and prepare the program to be shut down.

  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 or by another robot.

  5. Robots may occupy the same grid square of a non-matching goal. However, the goal is not "eaten", and will remain in place after the robot leaves the grid square.

  6. 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).

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. In particular, this abstract class provides:

    1. A private 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 that 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. Each thread should call this method before each step is taken by the corresponding robot. It is your responsibility to decide the direction of movement of the robot based on this information.

  4. 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).

What to Hand In

Place in your Hand-In directory the following:

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

Checking Your Results

We will use output log file to partially check the correctness of your program. So - it is essential that your log file be in the appropriate format. This format is as follows:

<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:

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. The script terminates with an "ALL OK" if these two conditions are met.

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:

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

Some Comments/Hints

Java Hints


This page is online at http://www-all.cs.umass.edu/~fagg/classes/377/labs/lab2/index.html
Andrew H. Fagg