/********************************************************************************/

 Traveling Salesman Problem
 Main file  : tsp.c
 
 Test application for distributed shared memory system for MP3 in CPSC 662.  

 Usage: tsp [-M] [-f <size> ] -i <nodeid> -n <numprocs> 
                -P <pagemanager> -B <barriermanager> -L <lockmanager>

 -M    Specifies that this program is run as a master process.  It then
       "spawns" slave processes by running copies of this program without
       the -M option.  
 -f <size> Specifies the size of the TSP to solve. Various TSP descriptions
       can be found in the ./tspfiles directory.
 -i <nodeid> Specifies the identifier of the process.  This is needed
       to split up the work that is performed.  If the process is a 
       master, this option is ignored, and the nodeid is set to 1.
 -n <numprocs>  Specifies the number of processes (including the master)
       participating in the computation.
 -P <pagemanager>  Specifies the name of the host on which the 
       page manager runs. 
 -B <barriermanager> Specifies the name of the host on which the 
       barrier manager runs.
 -L <lockmanager> Specifies the name of the host on which the 
       lock manager runs.

 The names of participating hosts is specified in the file
 'dsmtesthosts'.

 Example:  If the page manager is on merlot, the barrier manager is
           on cranberry and the lock manager is on alice, the master 
           for a computation on 4 processors is started as follows:

              tsp -M -n 4 -P merlot -B cranberry -L alice
 
           The master process then looks up the 'dsmtesthosts' file and
           starts three processes by invoking commands of the type:
 
               rsh -n vanilla    tsp -i 2 -n 4 -P merlot -B cranberry -L alice &
               rsh -n almond     tsp -i 3 -n 4 -P merlot -B cranberry -L alice &
               rsh -n strawberry tsp -i 4 -n 4 -P merlot -B cranberry -L alice &



 Notes from the TA:

 This application solves TSP in a recursive manner. The default input is the 
 8-node problem. However you can test your library with TSPs of other sizes.
 The ./tspfiles directory contains the required input files.

 The Makefile contains all the details about how to compile the code. Feel free 
 to modify it to suit your implementation.

 The test application WILL NOT compile without your library. Please read the handout 
 for details on what should be present in the library. 

 You need to add a 'dsmtesthosts' file that contains the names of different hosts.
 If you have trouble finding so many hosts, I'll probably upload a hosts file here
 (check back in a couple of days for that). 
 
 During the demo, we'll need at least 8 processes performing the computation.

 The test application is just that. I'd strongly suggest you do not spend 
 too much time trying to understand how it does the computation. The handout is
 much more informative than the test app, for this project.

 Barriers and Locks are used by the test application for synchronization. They 
 have little to do with the memory management part of your library. Think of them
 as checkpoints setup in the application, which need to be implemented 
 by a central barrier manager and lock manager, respectively.

 The difference between Barriers and Locks...

 Barrier makes every process (that reaches a barrier) wait until all the processes 
 reach the barrier.

 Lock is granted to each process that requests for it, provided the lock is
 available. If the lock is not available, the process will have to wait until  
 the lock-holder releases the lock. There could be multiple lock requests, 
 you should service them in order -- otherwise, a deadlock could occur.

 Although the test application uses only a few lock ids, you should implement a 
 generic lock manager that can service any number of lock ids. Same with barriers.
               
/********************************************************************************/