GOAL:

The goal of this assignment is to introduce the concept of threads. You will be required to show your understanding of threads by writing a simple program in C that uses the GNU Portable Threads package. This package is installed in /usr/local/public on both Linux and  Solaris machines in the College of Computing so you can use either one for the project. A manual is available here.

You will be writing a C program that contains thread communication and synchronization.  The program implements a mailbox-style of communication  between threads. In addition, you will implement various message passing semantics such as one-to-many  communcations and timer-limited persistent data.
You will define generic send() and recv() functions. These functions should operate as follows.  Each thread will have a "mailbox" into which other threads can deposit messages. Messages can be arbitrarily sized data. Mailboxes are essentialy data buffers that are allocated to hold arbitrary data. The API (i.e. mbox.h) is as follows.

init_mbox ( unsigned int NUM_MBOXES);

This call sets up any data structures that you might need for your mailbox implementation.

mbox_send( (char *) DEST,  unsigned TIMEOUT, (void *) MESG, unsigned mesg_length);

This sends a "message" from the current thread to DEST.  DEST must be the name of a valid thread or the asterisk symbol (i.e. "*") . The asterisk is a "don't care" pattern match indicating that any other thread can receive this message. Otherwise only the thread named by DEST can receive the message. Additionaly, the user can specify a question mark (i.e. "?") to indicate that only one other thread should receive this message but the user doesn't care which one. The actual message is referenced by MESG and is stored elsewhere until a corresponding mbox_recv() is called.  The TIMEOUT parameter is used to select certain semantics of the send as follows: 0 for normal send semantics, non-zero to indicate the number of milliseconds that the message is to persist in the mailbox. If an mbox_recv() call is executed during the duration of the time specified then this message will be returned. This simulates a "time-to-live" message. Note that no return value is specified for this. You are allowed to define any one you like that helps your implementation.

int mbox_recv( (char *) SRC, (void *) *raw_data, unsigned *len);

This recives a message from the mailbox system addressed to the current thread  and sent from the thread referred to by SRC. SRC must be a valid thread or the asterisk symbol (i.e. *). The asterisk is a "don't care" pattern match indicating that you can receive a message sent from any other thread. The actual message received is stored in raw_data. The return value is a status value with 0 indicating failure to receive a message and 1 indicating a valid message receipt.

You should do your best to strictly adhere to the API presented above. If you do find it necessary to change the API for some reason, you must write it up very well in your README file that you submit. As long as it has a reasonable technical rationale for the change, I'll probably accept it.
 

With the above API you should be able to have the following semantics on sending information between threads:

• peer-to-peer: a thread sends a message to exactly one other thread and knows exactly who will receive it. Each thread will have a unique name that is set by the programmer.
• one-to-many: a thread sends a message marked for receipt for N other threads. Each other thread receives exactly one copy of the message to be sent. Once N other unique threads have received the mesg, the message is removed from teh system. The "N" other threads is not explicitly listed in the api and instead should be determiend internally by the mailbox implementation.
• one-to-someone: a thread sends a message to exactly one other thread but doesn't know who will receive it.
• timed: a thread sends a message to either a specifc thread or N other threads with a time-to-live associated with the message. Within the time quantum specified in the send call, if an appropriate thread does a receive of a message from that particular thread as the source, they will get the data from this call. When the timer expires, the message is removed from the system and can no longer be received..

You will submit the following for the assignment:

A mbox.h file that is the prototype for the mailbox system. This is pretty much a given from the above information.

An mbox.c file which implements the mailbox system.

A test_mbox.c which uses your mailbox implementation to thoroughly test the four messaging semantics mentioned above.

A README.project1 file that explains how you designed your mailbox system. If you are having any difficulties or there are any unusual problems with your assignment, you should list them here to assist the TA in grading your project. If you fail to turn in a README file for this project, you will be penalized 10 points.

Due date is Due: 11:59 p.m., Sept. 10, 1999.

This is one minute prior to midnight on friday night. No late assignments will be excepted unless prior arrangements have been made. Instructions on turning the assignment have been posted to the newsgroup. They are also here for convenience.

Assignments will be submitted by e-mailing a shar archive of your work to the account cs6210@cc.gatech.edu. Do NOT email them to my personal account. Instructions for creating a shar file are as follows:

Login to a unix machine. (I am using "elvis.cc.gatech.edu" as the example here.) Type
 
shar files > sharfilename

where "files" is the list of the files that you are going to submit and "sharfilename" is the name of the shar file you are going to create. You will need to submit at least the files mbox.h mbox.c test_mbox.c and README.project1. So your command line should look like:

shar mbox.h mbox.c test_mbox.c README.project1 > project1.shar

If you used anything other than the standard setup as described above then you will need to make sure to include all the extra files necessary to grade your assignement such as Makefiles and extra test programs. MAke sure to mention how to deal with these files in your README file.

Make sure that you do NOT include any binaries in your shar files. I am going to compile your programs from scratch. If you have any special commands needed to compile your code then mention them in your README file.

You can email a shar file to the cs6210 account by doing:

mail cs6210@cc.gatech.edu < project1.shar

Assignments will not be accepted late without a very good sob story and the proper papers filled out in triplicate :)