Homework 3
	      	    (Deadline:  due Sun., Mar. 9)
	      	    (EXTENDED:  due Wed., Mar. 12)

CONTENTS
  INTRODUCTION
  UNPACKING TOP-C
  TRYING OUT TOP-C
  ASSIGNMENT
  WHAT TO HAND IN

INTRODUCTION:
For this homework, you will extend the capabilities of the software,
TOP-C (Task Oriented Parallel C/C++).  All of the information you need
is contained in this document and the TOP-C source code.  However, if
you want to know more about TOP-C, you can read more at:
	      http://www.ccs.neu.edu/home/gene/topc.html
The course web page also offers you some resources about
threads programming.  For the most part, a passive understanding of
threads will suffice, although in some cases you may need to modify
the threads logic.

The purpose of this assignment is to learn more about the server
architecture -- especially threads programming for multiple CPUs.
Servers are often built either as a cluster of CPUs (distributed
memory) or as a shared memory multiprocessor architecture.  TOP-C
reflects both modes.  A server accepts external requests, and then
hands out corresponding tasks to other CPUs.  Similarly in TOP-C, a
master process/thread hands out tasks to a slave process/thread, which
returns its value to the master.

The assignment can initially be tested on any computer, and requires
only a single CPU.  In the last week, I will make available a guest
account on a 4-way SMP Linux computer that is administered out of the
ECE department at Northeastern U.  You will then verify that your
program also works on a shared memory computer.

======================================================================
UNPACKING TOP-C:
  In the instructor's directory, /course/com3200,
you will find a copy of TOP-C:  topc-2.4.1-beta.tar.gz
To unpack it, copy topc-2.4.1-beta.tar.gz to wherever you plan to
install it.  After unpacking, TOP-C will take up about 3 MB of disk
space.  If you delete the two directories:
  rm -rf topc/doc topc/.future
you will need only about 2 MB of disk space.  The documentation is
available from the TOP-C home page:
  http://www.ccs.neu.edu/home/gene/topc.html
Next, unpack it:

gzip -dc topc-2.4.1-beta.tar.gz | tar xvf -
cd topc
./configure
make

======================================================================
TRYING OUT TOP-C:
  cd topc/bin
  ./topcc --help
  ./topcc --pthread ../examples/parfactor.c
  ./a.out --TOPC-help
  ./a.out
  ./a.out 1234567
  ./a.out --TOPC-submit-ahead=1    [This fails.  You need to extend TOP-C.]
  ./a.out --TOPC-submit-ahead=4    [This fails.  You need to extend TOP-C.]
  # Read Makefile  to see what examples can be built.
  make parfactor-pthread
  ./a.out --TOPC-submit-ahead=4    [This fails.  You need to extend TOP-C.]
  make parfactor-seq
  ./a.out --TOPC-submit-ahead=4    [This fails.  You need to extend TOP-C.]
  make parfactor                   [ Equiv. to --mpi, distributed memory. ]
  ./a.out --TOPC-submit-ahead=4    [This fails.  You need to extend TOP-C.]

======================================================================
ASSIGNMENT:
  TOP-C works with the option --TOPC-submit-ahead=0  (the default).
Your job is to make it work with --TOPC-submit-ahead=XXX for XXX any
positive integer.  You need to implement this for each of three modes:
  ./topcc --seq ...         [Sequential process, no threads, one slave]
  ./topcc --mpi ...         [Distributed memory]
  ./topcc --pthread ...     [Shared memory]

You will need to modify each of:
  topc/src/comm-seq.c
  topc/src/comm-mpi.c
  topc/src/comm-pthread.c
For each of those files, you need to modify two functions:
  COMM_receive_msg()
  COMM_send_msg()
In the case of topc/src/comm-mpi.c, you will also need to modify
  cache_msg() and possibly cache_messages_init().
Depending on your logic, you may or may not need to modify some
  auxiliary functions or global variables.

After modifying some of the TOP-C files, you can re-make the TOP-C
system by typing: `make' in any of the directories:
  topc, topc/src, topc/bin

Note that the global variable, TOPC_OPT_submit_ahead, contains the
integer value, XXX, for the command line option
--TOPC-submit-ahead=XXX Currently, TOP-C provides one "mailbox" per
slave process/thread with which to store messages from the master.
Your job is to provide multiple "mailboxes".  If TOPC_OPT_submit_ahead
has the value XXX, then you will need to implement at least XXX+1
mailboxes (the current task, plus XXX waiting tasks).

Note that for --mpi mode, each slave process has a distinct "receive
thread" whose job is solely to receive messages from the master
process and store them until the "compute thread" is ready to read
them.  Hence, the "receive thread" can receive a new message
simultaneously with the "compute thread" carrying on its computation.
When you create extra mailboxes, you must also modify the
synchronization logic between the two threads.

If you run into any problems, please send e-mail to:  com3200@ccs.neu.edu
If you see a problem from a classmate and know the answer, please
reply to com3200.  We will use com3200 to extend the class discussion
to this mailing list.  In particular, your classmates may see the
message and reply with assistance before I even login to a computer.

======================================================================
WHAT TO HAND IN:
On the 4-way SMP machine, do:  cd topc; make test
When it passes that test suite, you have succeeded.
If it doesn't pass the test suite, include in README.txt an
explanation of which tests did not succeed.  You will still receive
generous partial credit if you diagnose what didn't work, and what you
would have to do to fix it, if there were more time.

Note that:  make test
will run the test suite with the parameter:  --TOPC-submit-ahead=4

You should then "hand in" your assignment both on-line and in hard copy.
Your homework must include the files:
  README.txt  (a _text_ file describing your modifications)
  comm-seq.c      (your modified version)
  comm-mpi.c      (your modified version)
  comm-pthread.c  (your modified version)
  TEST.out        (Generate it by:  cd topc; make test >& TEST.out
If for some reason you had to make changes to other TOP-C files,
please also include those files.

Place all of the above files in a directory by themselves.
Then do:
  tar cvf hw3.tar *
  gzip hw3.tar
  [ Next, copy your file, hw3.tar.gz, to any CCS computer.]
  /course/com3200/submit-3200-hw3 hw3.tar.gz