Phase 1: Build a thread system

Stock Nachos has an incomplete thread system. In this assignment, your job is to complete it, and then use it to solve several synchronization problems.

The first step is to read and understand the partial thread system we have written for you. This thread system implements thread fork, thread completion, and semaphores for synchronization. It also provides locks and condition variables built on top of semaphores.

After installing the Nachos distribution, run the program nachos (in the proj1 subdirectory) for a simple test of our code. This causes the methods of nachos.threads.ThreadedKernel to be called in the order listed in threads/ThreadedKernel.java:

The ThreadedKernel constructor is invoked to create the Nachos kernel.
This kernel is initialized with initialize().
This kernel is tested with selfTest().
This kernel is finally "run" with run(). For now, run() does nothing, since our kernel is not yet able to run user programs.

Trace the execution path (by hand) for the simple test cases we provide. When you trace the execution path, it is helpful to keep track of the state of each thread and which procedures are on each thread's execution stack. You will notice that when one thread calls TCB.contextSwitch(), that thread stops executing, and another thread starts running. The first thing the new thread does is to return from TCB.contextSwitch(). We realize this comment will seem cryptic to you at this point, but you will understand threads once you understand why the TCB.contextSwitch() that gets called is different from the TCB.contextSwitch() that returns.

Properly synchronized code should work no matter what order the scheduler chooses to run the threads on the ready list. In other words, we should be able to put a call to KThread.yield() (causing the scheduler to choose another thread to run) anywhere in your code where interrupts are enabled, and your code should still be correct. You will be asked to write properly synchronized code as part of the later assignments, so understanding how to do this is crucial to being able to do the project.

To aid you in this, code linked in with Nachos will cause KThread.yield() to be called on your behalf in a repeatable (but sometimes unpredictable) way. Nachos code is repeatable in that if you call it repeatedly with the same arguments, it will do exactly the same thing each time. However, if you invoke "nachos -s <some-long-value>", with a different number each time, calls to KThread.yield() will be inserted at different places in the code.

You are encouraged to add new classes to your solution as you see fit; the code we provide you is not a complete skeleton for the project. Also, there should be no busy-waiting in any of your solutions to this assignment.

Your project code will be automatically graded. We are in the process of setting up an autograder. In order for you to verify that your code is compatible with the autograder, there are some simple compatibility tests you can run before you submit.

Since your submissions will be processed by a program, there are some very important things you must do, as well as things you must not do.

For all of the projects in this class...

Do not modify Makefile, except to add source files. You will not be submitting this file (javac automatically finds source files to compile, so we don't need you to submit Makefile).
Only modify nachos.conf according to the project specifications. You will not be submitting this file either. Do not rely on any additional keys being in this file.
Do not modify any classes in the nachos.machine package, the nachos.ag package, or the nachos.security package. You will not be submitting any of these classes.
Do not add any new packages to your project. All the classes you submit must reside in the packages we provide.
Do not modify the API for methods that the autograder uses. This is enforced every time you run Nachos by Machine.checkUserClasses(). If an assertion fails there, you'll know you've modified an interface that needs to stay the way it was given to you.
Do not directly use Java threads (the java.lang.Thread class). The Nachos security manager will not permit it. All the threads you use should be managed by TCB objects (see the documentation for nachos.machine.TCB).
Do not use the synchronized keyword in any of your code. We will grep for it and reject any submission that contains it.
Do not directly use Java File objects (in the java.io package). In later projects, when we start dealing with files, you will use a Nachos file system layer.

When you want to add source files to your project, simply add entries to your Makefile.

In this project,

The only package you will submit is nachos.threads, so don't add any source files to any other package.
The autograder will not call ThreadedKernel.selfTest() or ThreadedKernel.run(). If there is any kernel initialization you need to do, you should finish it before ThreadedKernel.initialize() returns.
There are some mandatory autograder calls in the KThread code. Leave them as they are.
Tasks:
1. Nachos implements kernel threads via the class KThread in the file threads/KThread.java. Implement KThread.join(). Suppose that thisThread is a thread object. Then, thisThread->join() should cause the caller to wait until the thread "represented" by thisThread finishes. If thisThread was already finished at the time of the call, then the call should return right away. Note that another thread does not have to call join(), but if it is called, it must be called only once. The result of calling join() a second time on the same thread is undefined. A thread must finish executing normally whether or not it is joined.
2. Implement condition variables directly, by using interrupt enable and disable to provide atomicity. We have provided a sample implementation that uses semaphores; your job is to provide an equivalent implementation without directly using semaphores (you may of course still use locks, even though they indirectly use semaphores). Once you are done, you will have two alternative implementations that provide the exact same functionality. Your second implementation of condition variables must reside in class nachos.threads.Condition2 (that is, in the file threads/Condition2.java).
3. Complete the implementation of the Alarm class (threads/Alarm.java), by implementing the waitUntil(int x) method. This class uses the hardware timer interrupt to provide two services: (a) preemption for preemptive CPU scheduling via the timerInterrupt() method , and (b) to allow a thread to suspend its own execution until time has advanced to at least now + x via the waitUntil(int x)method. This is useful for threads that operate in real-time, for example, for blinking the cursor once per second. Currently, waitUntil(int x) is implemented using busy waiting. Your task is to change the implementation of waitUntil(int x) so that the calling thread blocks. You will need to modify timerInterrupt() as well to wake up sleeping threads when it is time. There is no requirement that threads start running immediately after waking up; just put them on the ready queue in the timer interrupt handler after they have waited for at least the right amount of time. Do not fork any additional threads to implement waitUntil(); you need only modify waitUntil() and the timerInterrupt(). waitUntil is not limited to one thread; any number of threads may call it and be suspended at any one time.
4. Implement synchronous send and receive of one word messages (also known as Ada-style rendezvous), using condition variables (don't use semaphores!). Implement the Communicator class (file threads/Communicator.java) with operations, void speak(int word) and int listen().
  speak() atomically waits until listen() is called on the same Communicator object, and then transfers the word over to listen(). Once the transfer is made, both can return. Similarly, listen() waits until speak() is called, at which point the transfer is made, and both can return (listen() returns the word). Your solution should work even if there are multiple speakers and listeners for the same Communicator (note: this is equivalent to a zero-length bounded buffer; since the buffer has no room, the producer and consumer must interact directly, requiring that they wait for one another). Each communicator should only use exactly one lock. If you're using more than one lock, you're making things too complicated.
5. Now that you have all of these synchronization devices, use them to solve this problem. You will find condition variables to be the most useful synchronization method for this problem.
  You've just 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 all together at the same time. The atoms are threads. Each H atom invokes a procedure hReady when it's ready to react, and each O atom invokes a procedure oReady when it's ready. For this problem, you are to write the code for hReady and oReady. The procedures must delay until there are at least two H atoms and one O atom present, and then one of the procedures must call the procedure makeWater (which just prints out a debug message that water was made). After the makeWater call, two instances of hReady and one instance of oReady should return. Write the code for hReady and oReady using either semaphores or locks and condition variables for synchronization. Your solution must avoid starvation and busy-waiting. The class file that you should edit is here (ReactWater.java). Please add this file to nachos/threads. The Autograder will create one ReactWater object and a bunch of threads. Each thread will invoke either the hReady or oReady routine. Your task is only to write the ReactWater class correctly.
  What the Design Document Should Look Like
  
  For each part above, you should:
  1. Identify all Nachos classes that you will modify (and where you plan to do you modifications),
  2. Identify all classes that you plan to implement and give the API for each class,
  3. Provide high-level pseudocode for each method,
  4. For each class, provide a logical argument why the pseudocode you have provided for the methods work together to solve the posed problem. For example, for number 4, you need to explain what happens when multiple senders and listeners are using the same Communicator object.
  5. Test cases that you plan to use.
  Basically, your design document should convince us (and you) that you have looked through the Nachos code, understand what's going on, and has a valid plan for writing and testing necessary code in a relatively short amount of time. So, it should include any information that is important towards this purpose. The above list is just a short "guide" and may not be all inclusive.
  
  Submission:
  
  You are required to submit a README file and TESTCASES along with the your code.
  The README file should have names of your group memebers on the top. This document should explain how to get your assignment to run. You should also explain any quirks with your program, such as known show-stopper bugs, weird dependencies in your constants, and so on. Also, please include in your README a concise and obvious description of any features you added that you feel merit extra credit.
  
  The TESTCASE file should contain all the information about how you tested your programs. This file should contain the output from all the tests you have applied, with any explanations needed to reproduce the output (arguments to the program, turning features on the program on or off, and so on).
  
  Open an ssh connection to nachos.cs.laurentian.ca and login using your Novell username and password.
  
  Now, in the directory containing README, run
```
3407submit -r 
```
  For submitting TESTCASES run
```
3407submit -t
```
  This will ask you for the name and path of your document. After entering the name and path of your document hit enter. This will copy your documents for marking. To submit the code run
```
3407submit -c
```
  The path for the code should be /home/UserName/group0x/nachos/threads
  
  You can resubmit your document if need be but this should always be done by the same person in your group. The file and directory permissions are such that a member of group can not overwrite the file from another member.
  
  If there are any problems email detailed output to aaron@cs.laurentian.ca
```
Example outputs:

             README

             /home/UserName$ 3407submit -r
             Submitting README for group09.
             Enter the path and filename of your README document:
             group09/README1
             Copying group09/README1
             /home/UserName$
						 
             TESTCASES
						 
             /home/UserName$ 3407submit -t
             Submitting testcases for group09.
             Enter the path and filename of your testcase document:
             group09/testproj1
             Copying group09/testproj1
             /home/UserName$
						 
             Code
						 
             /home/UserName$ 3407submit -c
             Submitting nachos code for group09.
             Enter the path to your nachos code: (eg. /home/UserName/group0x/nachos/threads)
             group09/nachos/threads
             Copying group09/nachos/threads
             /home/UserName$
```

Phase 1: Build a thread system

Tasks:

What the Design Document Should Look Like

Submission: