Mini-Programming Project

Due on Friday, December 11, 2009 @ 11pm

100 points

Acknowledgment

Software developed for this mini-project, namely mtuThread, was sponsored by National Science Foundation. Click here to learn more about this project. Major developers include Xianlong Huang, Ping Chen, Budirijanto Purnomo, J. R. Lewis III, and Tin-Tin Yu. Of course, not all of their works appeared in this scaled-down and simplified version.

Build a User-Level Multithread System

In this programming project, you are to put all you have learned in this class together and complete the design and implementation of a user-level multithreaded system. You do not start from scratch, however. In fact, you are provided with (1) a working system in object format, (2) a portion of the working system in source format for you to complete, and (3) several working examples in source format. Your job consists of (1) reading the incomplete system and understanding its mechanism, (2) implementing the missing parts, and (3) testing your version. Note that you should not use ThreadMentor in this project. You are to create your own!

The language of choice is ANSI C.

You must ssh to the Linux system on dummy1.csl.mtu.edu to do this mini-project, because this package DOES NOT work on any other lab machines!

Your implementation is system dependent and all system dependent components are in mtuThreadCore.c which does not require any modification.

You may use Windows or Sun Solaris to do and test your work; but, our grader will use the indicated machine for grading.

System Description 1: User Callable Functions

This part consists of the following functions, each of which has a direct counterpart in ThreadMentor threads:

Function for creating a thread:
```
THREAD_t  THREAD_CREATE(void (*)(), int, int, int, char **);
```
The first argument is a function to be run as a thread. The second argument is the size of the stack for running this thread. You may always use the default value THREAD_SIZE for this project. The third argument is either THREAD_NORMAL or THREAD_SUSPENDED. THREAD_NORMAL means that the created thread will start running once it is created, while THREAD_SUSPENDED means the created thread will be suspended until it is resumed by another thread. The fourth and fifth arguments are equivalent to argc and argv, respectively, used in a main program. When a thread is run, it should take the same action as in a main program for retrieving the number of arguments argc and each of the arguments in the argument list argv. However, since all programs for this project are easy, we only use argc, the fourth argument, for passing an integer to a thread. See sample programs for the details. This function returns a structure of type THREAD_t that contains vital information of the created thread. Otherwise, it returns mtu_ERROR.
Function for terminating the running thread:
```
int  THREAD_EXIT(void);
```
Function for yielding the control of CPU:
```
void  THREAD_YIELD(void);
```
Since this system uses a non-preemptive scheduling policy, THREAD_YIELD() is needed to ensure a fair use of the CPU.
Function for returning the thread structure of the running thread:
```
THREAD_t  THREAD_SELF(void);
```
Function that forces the running thread to join with another thread:
```
int  THREAD_JOIN(THREAD_t ID);
```
The only argument of this function is a variable of type THREAD_t indicating the thread to be joined.
Function that suspends the indicated thread:
```
int  THREAD_SUSPEND(THREAD_t ID);
```
The only argument of this function is a variable of type THREAD_t indicating the thread to be suspended. The thread to be suspended should not be a suspended one; otherwise, mtu_ERROR will be returned. If successful, this function returns mtu_NORMAL.
Function that resumes the execution of the indicated thread:
```
int  THREAD_RESUME(THREAD_t ID);
```
The only argument of this function is a variable of type THREAD_t indicating the thread to be resumed. The thread to be resumed must be a suspended one; otherwise, mtu_ERROR will be returned. If successful, this function returns mtu_NORMAL.

All functions are in file new_mtuThreadTop.c. Note that implementing functions THREAD_JOIN(), THREAD_SUSPEND() and THREAD_RESUME() is your job. As a result, only dummy templates are provided in file new_mtuThreadTop.c.

System Description 2: Synchronization Primitives

This part consists of the following synchronization primitives for mutex locks, semaphores and channels. You have learned all of them in this course.

Mutex Locks

There are four functions for mutex locks:

Create a mutex lock:
```
MUTEX_t MUTEX_INIT(void);
```
If a mutex lock is created successfully, this lock is returned as a function value of type MUTEX_t; otherwise, this function returns mtu_ERROR.
Destroy a mutex lock:
```
int   MUTEX_DESTROY(MUTEX_t Lock);
```
If mutex lock Lock is destroyed successfully, this function returns mtu_NORMAL; otherwise, this function returns mtu_ERROR.
Lock a mutex lock:
```
int MUTEX_LOCK(MUTEX_t Lock);
```
If mutex lock Lock is locked successfully, this function returns mtu_NORMAL; otherwise, this function returns mtu_ERROR.
Unlock a mutex lock:
```
int MUTEX_UNLOCK(MUTEX_t Lock);
```
If mutex lock Lock is unlocked successfully, this function returns mtu_NORMAL; otherwise, this function returns mtu_ERROR. Note that only the owner of a lock (i.e., the thread that locked the lock previously) can unlock a lock.

Full implementations of these four functions are in file mtuThreadMUTEX.c. Read the code carefully because you will need it for implementing semaphores.

Counting Semaphores

There are four functions for counting semaphores:

Create and initialize a semaphore:
```
SEM_t SEMAPHORE_INIT(int count);
```
If a semaphore with initial value count is created successfully, this semaphore is returned as a function value of type SEM_t; otherwise, this function returns mtu_ERROR.
Destroy a semaphore:
```
int   SEMAPHORE_DESTROY(SEM_t Semaphore);
```
If semaphore Semaphore is destroyed successfully, this function returns mtu_NORMAL; otherwise, this function returns mtu_ERROR.
Signal a semaphore:
```
int SEMAPHORE_SIGNAL(SEM_t Semaphore);
```
If semaphore Semaphore is signaled successfully, this function returns mtu_NORMAL; otherwise, this function returns mtu_ERROR.
Wait on a semaphore:
```
int SEMAPHORE_WAIT(SEM_t Semaphore);
```
If waiting on semaphore Semaphore is successful, this function returns mtu_NORMAL; otherwise, this function returns mtu_ERROR.

Only dummy templates of these four functions are in file new_mtuThreadSEM.c, because it is your job to implement semaphores. Note that type SEM_t is defined as a pointer to a structure SEMAPHORE. A possible data structure is provided to you in file mtuThread.h. Feel free to modify it for your implementation.

Channels

There are four functions for channels. This is a simplified and scaled-down version of ThreadMentor.

Create a channel:
```
CHANNEL_t CHAN_INIT(const char *name, int type, int mode)
```
If a channel is created successfully, it is returned as a function value of type CHANNEL_t; otherwise, this function returns mtu_ERROR. The first argument name provides a name to the channel, the second argument type should be ASYNCHRONOUS, and the third argument mode should be MANYTOMANY. Therefore, channels in this project are many-to-many asynchronous channels with infinite capacity. Here, MANYTOMANY means every thread can send messages to and receive messages from the same channel (i.e., non-blocking send and blocking receive), and the sender may receive the message it just sent!
Destroy a channel:
```
CHAN_DESTROY(CHANNEL_t channel);
```
If channel channel is destroyed successfully, this function returns mtu_NORMAL; otherwise, this function returns mtu_ERROR.
Send a message to a channel:
```
int CHAN_SEND(CHANNEL_t Channel, void *stuff, int size)
```
The data pointed at by stuff of size size is sent to channel Channel. If this send is successful, this function returns mtu_NORMAL; otherwise, this function returns mtu_ERROR.
Receive a message from a channel:
```
int CHAN_RECV(CHANNEL_t Channel, void **output, int *size)
```
If a message is received from channel Channel successfully, it is stored into *output and this function returns mtu_NORMAL. Otherwise, this function returns mtu_ERROR. The size of the received message is returned in size.

Only four dummy templates of these four functions are provided to you in file new_mtuThreadCHAN.c, because it is your job to implement channels. Note that type CHANNEL_t is defined as a pointer to a structure CHANNEL. A possible data structure is provided to you in file mtuThread.h. Feel free to modify it for your implementation.

More importantly, channel should use non-bloking send and blocking receive. You may arrange the messages in the FIFO order.

How to Use this System

To use this system, you need to know the seven functions listed at the beginning of this page. All seven functions start with THREAD_, since they are for controlling the execution of threads.

The most important function is THREAD_CREATE() for creating threads. Function THREAD_CREATE() has the following prototype:

THREAD_t  THREAD_CREATE(
               void (*Entry)(),    /* function to be run as a thread*/
               int Size,           /* stack size for this thread    */
               int status,         /* running or suspended?         */
               int Argc,           /* # of arguments to be passed   */
               char **Argv);       /* argument list                 */

The first argument is a pointer to a function that will run as a thread. In fact, when you call THREAD_CREATE(), the first argument is simply the function name. Note that this function has a return type of void, which means it does not return anything. When this function runs as a thread, the size of the stack space assigned to it is specified by the second argument. You may use THREAD_SIZE, which is defined in mtuThread.h, for this project. The third argument specifies if the created thread should be suspended. If it should be suspended, use THREAD_SUSPENDED; otherwise, use THREAD_NORMAL. The last two arguments, Argc and Argv, are exactly the same as they do in a main program (i.e., retrieving arguments from a command line). More precisely, you should collect the arguments to be passed to a thread into an argument list and passed as Argv. The number of arguments, which is an integer, is passed as Argc. In this project, since we only pass a single integer to a thread, we shall ignore Argv and only use Argc for passing an integer. Therefore, Argc does not have the same meaning as mentioned above.

The following is an example in file pingpong.c. It has two threads, Ping() and Pong().

#include  <stdio.h>
#include  <stdlib.h>

#include  "mtuThread.h"

void  Ping(int);                        /* thread prototypes        */
void  Pong(int);

SEM_t StopPing, StopPong;
int   Count;

void  Ping(int  ID)
{
     while (1) {                        /* loop forever             */
          SEMAPHORE_WAIT(StopPing);     /* stop until released      */
               printf("Ping-");         /* print Ping-              */
          SEMAPHORE_SIGNAL(StopPong);   /* release Pong             */
     }
     THREAD_EXIT();
}

void  Pong(int  ID)
{
     do {                               /* loop for 'Count' times   */
          SEMAPHORE_WAIT(StopPong);     /* stop until released      */
               printf("Pong\n");        /* append Pong to Ping-     */
          SEMAPHORE_SIGNAL(StopPing);   /* release Ping             */
          Count--;
     } while (Count > 0);               /* done if Count = 0        */
     THREAD_EXIT();
}

int  main(int argc, char *argv[])
{
     THREAD_t  THREAD_Ping, THREAD_Pong;

     Count = 10;
     if (argc != 2) {
          printf("Use %s #-of-iterations\n", argv[0]);
          printf("No. of iterations is set to %d\n", Count);
     }
     else 
          Count = abs(atoi(argv[1]));

     StopPing = SEMAPHORE_INIT(1);      /* Ping goes first          */
     StopPong = SEMAPHORE_INIT(0);      /* Pong stops until informed*/

     THREAD_Ping = THREAD_CREATE(Ping, THREAD_SIZE, THREAD_NORMAL, 
                                 1, (char **) 0);
     THREAD_Pong = THREAD_CREATE(Pong, THREAD_SIZE, THREAD_NORMAL, 
                                 2, (char **) 0);

     THREAD_JOIN(THREAD_Pong);          /* can only join Pong()     */

     return 0;
}

This example first creates two semaphores StopPing and StopPong. Then, two threads are created running functions Ping() and Pong(). Note that (1) we use default stack size THREAD_SIZE; (2) both threads will run once they are created since THREAD_NORMAL is used; (3) the fourth argument is 1 (resp., 2) for the thread running Ping() (i.e., Pong()); (4) the fifth argument is (char **) 0 since no argument list is passed to the created threads; and (5) function THREAD_CREATE() returns the information structure of the created thread into a variable of type THREAD_t, which is used for calling THREAD_JOIN(). The remaining of this program is clear since we have encountered it a number of times in class. Note that threads Pong() terminates itself after Count iterations; however, Ping() loops forever. This may cause a problem. After Pong() is done, Ping() might not be able to run further because the thread that can signal it (i.e., thread Pong()) has terminated. This system will detect that no thread is in the ready queue and yet the system is still running! Hence, it might tell you that a deadlock is likely to occur, although you know this is not the case. The scheduler written in this way is to show you that a scheduler indeed can warn you for possible deadlocks.

Please refer to philosophers (philo.c) , philosophers with four seats (philo-4.c), and philosophers with a righty (philo-w.c) for further examples that use mutex locks and semaphores.

The next example shows the use of channels to solve the producer and consumer problem. See buffer.c for the details.

#include  <stdio.h>
#include  <stdlib.h>
#include  "mtuThread.h"

void  Producer(int);
void  Consumer(int);

CHANNEL_t Chan;

void  Producer(int  ID)
{
     int  i, data;

     for (i = 0; ; i++) {
          data = ID*1000 + i;
          CHAN_SEND(Chan, &data, sizeof(int));
          printf("Producer %d has sent data %d\n", ID, data);
          THREAD_YIELD();
     }

     THREAD_EXIT();
}

void  Consumer(int ID)
{
     int *data, size;

     while (1) {
          CHAN_RECV(Chan, (void**) &data, &size);
          printf("     Consumer %d received %d\n", ID, *data);
          THREAD_YIELD();
     }

     THREAD_EXIT();
}

int  main(int argc, char *argv[])
{
     THREAD_t   Producer1, Producer2, Consumer1, Consumer2;
     int        i;
     char       ch;

     printf("Use Ctrl-C to kill this program\n");
     printf("Hit any key to continue... ");
     ch = getchar();
     printf("\n");

     Chan = CHAN_INIT("Channel", ASYNCHRONOUS, MANYTOMANY);

     Producer1 = THREAD_CREATE(Producer, THREAD_SIZE, THREAD_NORMAL, 
                      1, (char **) 0);
     Producer2 = THREAD_CREATE(Producer, THREAD_SIZE, THREAD_NORMAL, 
                      2, (char **) 0);
     Consumer1 = THREAD_CREATE(Consumer, THREAD_SIZE, THREAD_NORMAL, 
                      1, (char **) 0);
     Consumer2 = THREAD_CREATE(Consumer, THREAD_SIZE, THREAD_NORMAL, 
                      2, (char **) 0);

     THREAD_JOIN(Producer1);

     return 0;
}

This program creates two producers and two consumers. The producers keep sending integer messages to channel Chan, while consumers keep receiving integer mail messages from channel Chan. Note the use of THREAD_YIELD().

Program psort.c shows a very interesting way of using channels. This program uses multiple threads to sort non-negative integers. Refer to the program file for the details. In this program, 10 threads (the sorters), S₁, S₂, ..., S₁₀ are created. Each of these threads, say S_i, has a channel inChan shared with its predecessor S_i-1, and a channel outChan shared with its successor S_i+1. There is a generator G and a terminator T. The generator has a channel shared with S₁ and the terminator T has a channel shared with S₁₀.

The generator G sends ten random non-negative integers into the channel shared with S₁. After that, G sends an end message END, indicating that there is no more data so that the job ends.

For each sorter, say S_i, it first receives a number from its predecessor via its inChan and memorizes it. Then, S_i receives a new number via inChan. If this new number is an END, there is no more incoming numbers and the number memorized by S_i is printed. Then, S_i prints its number, passes END to its neighbor, and exits. If the new number is not an END, we have two cases to consider:

If the new number is larger than or equal to the number that S_i memorized, the number is sent to S_i+1 via S_i's outChan. After this, S_i waits for a new incoming message via its inChan.
If the new number is less than the number that S_i memorized, S_i memorizes the new number and sends the old one to S_i+1 via its outChan. After this, S_i waits for a new incoming message via its inChan.

The job for terminator T is simple. It could only receive the END message. (Why?) Once T receives the END message, it exits the whole program. Convince yourself that the output from sorters is in increasing order.

Your Job

After reading mtuThread.h, mtuThread*.c and all examples, you will know the merit of this multithreading package. You should also find several places marked with "Your Job" in various files. These are the places where you have to fill in with your implementation. You can modify the definition file and the implementation file. However, you have to make sure that all sample programs will run correctly without any modifications. Also, make sure that you do not use busy waiting. If you have one busy waiting in the system, you will receive no credit no matter how good the other parts are.

The following lists the places where your work is required.

Implement thread functions THREAD_JOIN(), THREAD_SUSPEND() and THREAD_RESUME(). These three functions are in file new_mtuThreadTop.c.
Implement semaphore functions SEMAPHORE_INIT(), SEMAPHORE_DESTROY(), SEMAPHORE_SIGNAL() and SEMAPHORE_WAIT(). These four functions are in file new_mtuThreadSEM.c, and type SEM_t is defined in file mtuThread.h.
Implement channel functions CHAN_INIT(), CHAN_DESTROY(), CHAN_SEND() and CHAN_RECEIVE(). These four functions are in file new_mtuThreadCHAN.c, and type CHANNEL_t is defined in file mtuThread.h.

As you can see from the filenames, all programs are written in C. Consequently, you should use ANSI C rather than C++ for this mini-project. Without observing this requirement, it is likely we may not be able to compile and test your programs successfully, and you may not receive proper credit for your work.

Testing Your Implementation

Your system must run all eight sample programs, alter1.c, alter2.c, pingpong.c, philo.c, philo-4.c, philo-w.c, buffer.c and psort.c, without any modifications. In addition to these eight sample programs, design and submit the following for testing.

Consider a system of three cigarette smoker threads and one agent thread. Each smoker continuously makes a cigarette and then smokes it. Three ingredients are required to make and smoke a cigarette: paper, tobacco and matches. One of the smokers has paper, another tobacco and the third matches. The agent and smokers have an infinite supply of all three ingredients. The agent places two randomly selected ingredients on a table, signals the smoker who needs that two ingredients, and waits for the table to be cleared. Then, the agent goes back and puts two other randomly selected ingredients on the table. On the other hand, a signalled smoker takes the ingredients from the table, signals the agent to clear the table, makes a cigarette, and starts smoking. Then, he goes back and waits for his ingredients again.
Write a program smokers-sem.c that only uses semaphores to solve the smokers problem. When the agent has supplied ingredients n times, the system should stop running, where n should be taken from the command line. Your program should not have race conditions, busy waiting, and deadlock.
Study psort.c before you do this problem. Suppose a global integer array of 10 elements is available. There are five threads, P₀, P₁, P₂, P₃ and P₄. At the beginning, thread P_i takes the 2i-th and (2i+1)-th integers from the array. Then, each P_i iterates 5 times. P_i will do the following in each of these five iterations:
- Compare the two numbers in hand.
- Send the smaller one to P_i-1 and the larger one to P_i+1
- Wait for a number p_i-1 from P_i-1 and a number p_i+1 from P_i+1.
- If p_i-1 is larger than P_i's smaller number, then use p_i-1 to replace its smaller number.
- If p_i+1 is smaller than P_i's larger number, then use p_i+1 to replace its larger number.
After 5 iterations, P_i should put its numbers back to the global array and terminate. More precisely, the smaller (resp., larger) one of P_i goes into position 2i (resp., 2i+1) of the global array. After all five threads are done, the content in the global array is sorted in increasing order.
Write a program exchange.c that only uses channel for communication. Your main program should generate and display ten random numbers and put them into the global array. Finally, you have to find some way to display the sorted result.
Do the leader election problem in a ring network using channels. Refer to here for the problem description. Name this program ring-leader.c.

How Will We Test Your Implementation

We will use the following to test each of the six sample programs, your smokers-sem.c, exchange.c and ring-leader.c, and some other programs we will be writing for testing purposes. Hence, make sure you will have more comprehensive tests with a few more test cases.

gcc  xyz.c mtuThread.c -o xyz
xyz

where xyz is a program name (e.g., exchange). Note that since we will use our original version of alter1.c, alter2.c, pingpong.c, philo.c, philo-4.c, philo-w.c, buffer.c and psort.c to test your implementation, any changes you made to these programs will have no effect. Therefore, you should not make any change to these sample programs. We will also run your smokers-sem.c, exchange.c and ring-leader.c under our correct implementation to see if you have submitted correct solutions.

Two correct implementations of this system are provided in binary files mtuThread-Linux.o and mtuThread-Solaris.o, you may copy any of these to mtuThread.o in order to check your implementation with the following:

gcc  xyz.c mtuThread.o -o xyz
xyz

Note that the -D compiler command line switch can be used to select a version to compile your program on Fedora Linux or on Solaris. The default (i.e., no -D compiler switch used) is Fedora Linux. Read the source files to figure it out how to compile on Solaris.

By the way, we expect you to use the gcc compiler.

Click here to see the grading sheet.

How Will We Grade Your Implementation

We shall evaluate your implementation based on the following criteria:

The correctness of implementing thread functions THREAD_JOIN(), THREAD_SUSPEND() and THREAD_RESUME().
The correctness of implementing semaphore functions SEMAPHORE_INIT(), SEMAPHORE_DESTROY(), SEMAPHORE_SIGNAL() and SEMAPHORE_WAIT().
The correctness of implementing channel functions CHAN_INIT(), CHAN_DESTROY(), CHAN_SEND() and CHAN_RECV().
The correctness of smokers-sem.c, exchange.c and ring-leader.c.
Your program documentation
The readability and completeness of your README file (see Submission Guidelines below).
The readability and completeness of your JOURNAL file

In addition to running test programs above, we will also use other programs. The correctness of your implementation will be evaluated with all test programs.

Downloadable Material

Click here to download file proj.tar.gz. Then, move this file to your working directory and use the following commands to uncompress and untar:

gzip -d proj.tar.gz
tar xvf proj.tar

You will see the following files in your directory:

mtuThread-*.o: our correct implementation (in object format) for your reference and testing purposes
mtuThread*.h: the header files for our correct implementation
mtuThread*.c: the implementation files of our correct implementation. However, three files are missing: mtuThreadTop.c, mtuThreadSEM.c and mtuThreadCHAN.c. They are supposed to be replaced by your version of new_mtuThreadTop.c, new_mtuThreadSEM.c and new_mtuThreadCHAN.c, which are included in this package (i.e., proj.tar.gz).
Sample programs: alter1.c, alter2.c, pingpong.c, philo.c, philo-4.c, philo-w.c, buffer.c and psort.c.

After receiving these files, you should copy one of the correct implementation file to mtuThread.o, and immediately rename new_mtuThreadTop.c, new_mtuThreadSEM.c and new_mtuThreadCHAN.c to mtuThreadTop.c, mtuThreadSEM.c and mtuThreadCHAN.c, respectively. Then, you should use these files for your work. Do not submit new_mtuThreadTop.c, new_mtuThreadSEM.c and new_mtuThreadCHAN.c, since we will not read and use them.

Submission Guidelines

For detailed programming and submission guidelines, refer to previous programming assignments. Before start working on this project, rename new_mtuThreadTop.c, new_mtuThreadSEM.c and new_mtuThreadCHAN.c to mtuThreadTop.c, mtuThreadSEM.c and mtuThreadCHAN.c, respectively. Do not change the file names in the #include directives. Submit the following files only:

All mtuThread*.c and mtuThread*.h. Even though you did not modify some of them, you still have to submit the unmodified files.
Your testing programs smokers-sem.c, exchange.c and ring-leader.c. Each program should be in a single file.
README: this file must address the following questions. You should organize your README file into sections with the questions as section titles. Without doing so, your README file is considered poorly written and you will risk lower grade. Write your README file to the point and concisely. You can use no more than two printed pages with the following print command:
```
enscript -2r -G README
```
The length of your writing is not proportional to the number of points you will receive.
- Explain how each thread obtains its stack space.
  Function THREAD_INIT() has terse comments. You should provide a step-by-step explanation. Yes, explain both the Solaris and Linux versions. Translating the instructions to English sentences or copying down the program comments are not counted as explanations. A good explanation should elaborate why the instructions/statements work by providing an in-depth discussion. You must address the issues of changing stack pointer and so on.
- Why is the call to function THREAD_WRAP() necessary?
- How does this system perform context switching?
  Elaborate your findings.
- Why is this system using a non-preemptive scheduling policy? Suggest a way of using a preemptive scheduling policy.
  Elaborate your findings. Note that you should not just say the use of a timer does it. You have to provide a design, data structures, algorithms, and a convincing argument.
- A detailed description of your implementation of THREAD_JOIN()
  Discuss the data structures and algorithms used. Show why it works.
- A detailed description of your implementation of THREAD_SUSPEND()
  Discuss the data structures and algorithms used. Show why it works.
- A detailed description of your implementation of THREAD_RESUME()
  Discuss the data structures and logic used. Show why it works.
- A detailed description of your implementation of smokers-sem.c
  Discuss the logic and the use of mutex locks or semaphores. Show why it works.
- A detailed description of your implementation of exchange.c
  Discuss the logic and the use of channels. Show why it works.
- A detailed description of your implementation of ring-leader.c
  Discuss the logic and the use of channels. Show why it works.
JOURNAL: this is the journal of your software design process. You should keep a design journal in which all important events, including new design ideas, bugs, bug fixes, and so on, are recorded. Design/implementation events should be documented in chronicle or problem oriented order and should contain the following information:
- Date: The date this event occurs
- Problem: What was the problem? How did you discover this problem?
- Impact: What was the impact of this problem to your design and implementation
- Solution: What was your solution?
A poorly written journal and/or a journal without observing the above guidelines will not be graded and as a result you will receive zero point for this part.
Click here to see how your mini-project will be graded.

Note that your readme and journal files must have file names README and JOURNAL rather than readme and journal.

You should enclose any place where you made a change and/or addition with #ifdef-#endif as follows:

#ifdef CHANGED
     put your changes/modifications/additions here
#endif

In this way, any modification/addition to the original files can be found easily. When you submit your program, don't forget to define CHANGED at the very beginning of mtuThread.h. However, if you only modify new_mtuThread*.c, this mechanism is not required.