CS140 Problem Set 0: Synchronization

Note: this problem set should be done individually, not in teams. The teams will apply to the four Pintos projects. For this problem set it is OK to discuss general strategy with other people, and it's OK to give and receive help tracking down problems, but you must write your own code.

Problem 1: CalTrain Automation

CalTrain has decided to improve its efficiency by automating not just its trains but also its passengers. From now on, passengers will be robots. Each robot and each train is controlled by a thread. You have been hired to write synchronization functions that will guarantee orderly loading of trains. You must define a structure struct station, plus several functions described below.

When a train arrives in the station and has opened its doors, it invokes the function

station_load_train(struct station *station, int count)

where count indicates how many seats are available on the train. The function must not return until the train is satisfactorily loaded (all passengers are in their seats, and either the train is full or all waiting passengers have boarded).

When a passenger robot arrives in a station, it first invokes the function

station_wait_for_train(struct station *station)

This function must not return until a train is in the station (i.e., a call to station_load_train is in progress) and there are enough free seats on the train for this passenger to sit down. Once this function returns, the passenger robot will move the passenger on board the train and into a seat (you do not need to worry about how this mechanism works). Once the passenger is seated, it will call the function

station_on_board(struct station *station)

to let the train know that it's on board.

Create a file caltrain.c that contains a declaration for struct station and defines the three functions above, plus the function station_init, which will be invoked to initialize the station object when CalTrain boots. In addition:

You must write your solution in C using the Pintos functions for locks and condition variables:

lock_init (struct lock *lock)
lock_acquire(struct lock *lock)
lock_release(struct lock *lock)
cond_init(struct condition *cond)
cond_wait(struct condition *cond, struct lock *lock)
cond_signal(struct condition *cond, struct lock *lock)
cond_broadcast(struct condition *cond, struct lock *lock)

Use only these functions (e.g., no semaphores or other synchronization primitives).

You may not use more than a single lock in each struct station.
You may assume that there is never more than one train in the station at once, and that all trains (and all passengers) are going to the same destination (i.e. any passenger can board any train).
Your code must allow multiple passengers to board simultaneously (it must be possible for several passengers to have called station_wait_for_train, and for that function to have returned for each of the passengers, before any of the passengers calls station_on_board).
Your code must not result in busy-waiting.

Problem 2: Chemical Reaction

You have been hired by Mother Nature to help her out with the chemical reaction to form water, which she doesn't seem to be able to get right due to synchronization problems. The trick is to get two H atoms and one O atom together at the same time. Each atom is represented by a thread. Each H atom invokes the function

void reaction_h(struct reaction *r)

when it is ready to react, and each O atom invokes the function

void reaction_o(struct reaction *r)

You must write the code for these two functions. The functions must delay until there are at least two H atoms and one O atom present, and then exactly one of the functions must call the procedure make_water (which you needn't write; Mother Nature's already gotten this part figured out). After each make_water call two instances of reaction_h and one instance of reaction_o should return.

Create a file reaction.c that contains the functions reaction_h and reaction_o, along with a declaration for struct reaction (which contains all the variables needed to synchronize properly). In addition:

Write the function
```
reaction_init(struct reaction *r)
```
which will be invoked to initialize the reaction object.
Your code must invoke make_water exactly once for every two H and one O atoms that call reaction_h reaction_o, and only when these calls are active (i.e. the functions have been invoked but have not yet returned).
Write your solution in C using the Pintos functions for locks and condition variables listed in Problem 1 above.
You may not use more than a single lock in each struct reaction.
Your code must not result in busy-waiting.

Problem 3: Honor Code

This problem tests your understanding of the Honor Code as it relates two this class. Before answering this question, read the "Honor Code" section of the course information page. Then, create a file honor.txt that answers the following question. Which of the following scenarios are Honor Code violations?

(a)	Before starting work on a project, you get together with your teammates and the members of another team to discuss different possible approaches for implementing the project.
(b)	You discover a complete solution for the Pintos assignments on the Web. You look over one of those solutions, then put it aside and don't look at it again as you write your solution.
(c)	A friend (not in your team) is having trouble getting started on one of the projects, so they ask if they can look at your solution for general ideas. You give them a paper copy of your code, which they refer to as they type in their solution. In the end, their solution doesn't look at all like yours.
(d)	You started taking CS 140 last year and implemented Project 1, but then you dropped the class. This year, you reuse the code that you wrote for the course last year.
(e)	You started taking CS 140 last year, but dropped the class after your team completed Project 2. This year, you reuse code written by your teammates for Project 2 last year.
(f)	You find a page on Wikipedia that compares several different approaches to demand paging. After reading this page, you choose to use one of these algorithms in your implementation of Project 3.

Testing Your Code

We have created a test framework that you can use to test your code on Unix-like systems such as the myth cluster and Mac OS X. To use the framework, download the file cs140-ps0.tar. Then extract its contents with the command

tar xf cs140-ps0.tar

This will create a directory cs140-ps0. Read the README file in that directory for instructions on how to use the testing framework.

Complexity Penalty

Synchronization code is hard to get right, so it's important that it be clean, simple, and obvious. Unfortunately, solutions to this problem set often end up long and complicated; such solutions rarely work, and in real life they would be brittle and hard to maintain. If the CAs judge your code to be unnecessarily long and complicated, they will deduct up to 30% of the total score for this. Our solution for caltrain.c has 51 lines and our solution for reaction.c has 36 lines (not including comments). Note: your goal should be simplicity, not just line count; simple programs are usually shorter than complex ones, but the shortest program isn't always the simplest.

Submitting this Problem Set

To submit your solutions, cd to your directory containing caltrain.c, reaction.c, and honor.txt, then type the following commands:

make clean
/usr/class/cs140/bin/submit 0