****************************************************************************
8/30/1994                PVM++ package RELEASE 0.3
		         -------------------------

	         Daniel COHEN-LAROQUE
	         Graduate Fellow in Communication Sciences
	         Swiss Federal Institute of Technology

	         voice: (+33) 50.43.71.67 (France)
		 e-mail: cohen_la@di.epfl.ch or
		         cohen@eurecom.fr (till 12/94)

****************************************************************************
Abstract: 
          C++ library for Parallel Virtual Machine (PVM) environment.
          Uses inheritance, templates and overloading C++ features.
****************************************************************************

1) The aim of PVM++ library.
2) What you need to compile PVM++.
3) The philosophy of PVM++.
4) Some explanations about the client-server example provided.
5) Files name.
6) Bibliography.
                          ***********
7) SERIOUSLY! Applying for a position. (Read this even if you hate C++ !)

                       -----------------

1) The aim of PVM++ library:
----------------------------

   Using the convenient PVM environment for studying protocols on heterogenous
   clusters, I found that PVM was suffering of some serious drawbacks. First 
   of all, the code of a program becomes quickly unreadable, specially when
   one focuses on the messages that are passed, even if one makes use of
   procedures. Another drawback is that very often, the same code appears
   in pvm programs: e.g. a process must kill all its children before exiting 
   PVM...

   To my opinion, encapsulating with C++ code doesn't mean re-implementing
   each standard function, just in order to use overloaded methods with
   different names, with default parameters. Thoses classes are too often
   encountered with encapsulated Motif GUI libraries for example.
   
   But PVM++ provides very usefull features that make a code very easy to 
   implement, because you know at anytime what you are dealing with, just
   by giving a look at it.(i.e. broadcasting a matrix to different clusters 
   and receiving it in a asynchronous way in 2 lines!)

   REMEMBER that the aim of this library is not to forget the pvm standard
   functions. The utility of those methods are very clear when understood.


2) What you need to compile PVM++:
----------------------------------

   The library make use of templates[1] that are very new in ANSI C++.
   It has been implemented on a Linux box (Unix Posix for [34]86 chips)
   with GCC 2.6.0, libg++2.5.8. and pvm3.3.3.(previous pvm3 release
   should be OK, however).

   Version lower than 2.6.0 won't successfully compile the code without 
   major changes because of the external template implementation.

   Many other compilers support external template, and it's the reason why
   I have prefered this language improvement instead of portability.

   [1] template c++ classes are very usefull, there are independent of 
       the type of variable. e.g. only one vector class is enough to 
       support int, float, matrix, or any type of vectors!
    
   NOTE: I consider that version number shouldn't appear in the header
         and library space name. So, I renamed pvm3.h as pvm.h and 
         libpvm3.h as libpvm.h Make a symbolic name, if you prefer!
 

3) The philosophy of PVM++:
---------------------------
   
   This version is a beta release implemented in my SPARE TIME and I would
   like any comments to improve it.
   Therefore, the following way of seeing PVM architecture is subject 
   to changes. I hope however that some 'PVM hackers' will appreciate it, 
   and use it!

   The two main classes are called PVM_Task and PDU(for packet data unit):

   A PVM_Task object registers pvm daemon when it is called and is usually
   declared at the begining of a pvm program.(however, it can be usefull
   to declare more than one PVM_Task object in a single code, the two objects
   will only have in common their tid and ptid numbers) 
   This class is very linked to the PDU one, because many PVM_Task methods
   take a PDU object as parameter.

   Then, every time you want to declare a kind of message to send/receive, 
   you derive the PDU class, and specify how to pack/unpack (in fact, the 
   derived class components). See the provided example, to realize how 
   obvious it is. 

   Every time you want to send/receive one message, you call a 
   PVM_Task method (send, broadcast, receive), which will automatically 
   calls the (un)packing methods that you've specified (virtual calls). 
   You could imagine a client-server model by deriving 2 kinds of PDUs;
   the request and answer PDUs.
   
   At this point, it already exists one built-in function to pack-unpack
   vector<of any type>, and you can very easily expand the PDU class to 
   your needs.(Of course, the standard pvm (un)packing functions are still
   usefull as they stand for the basis functions to (un)pack the basis types)

   Remember that using PVM++ only means building the derived PDU classes 
   and linking your code with libpvm++.a (and libpvm.a as usual)


4) Some explanations about the client-server example provided:
--------------------------------------------------------------
  
   This is a simple example which shows all the PVM++ features.
   A master task spawns some slaves, requested to test the precision
   of random numbers generator.(the one provided with libg++)

   The request pdu contains the mean, variance, length of test, and 
   slave tids vector. The slaves verify their tid in the ones received, 
   generates random numbers, send back the effective mean with their 
   index number(pdu answer). Then, they are ready to accept a retransmission if
   requested by the master. The function FlipCoin simulates lost pdu answer(the
   communication channel).

   After sending the answer PDU, the slaves send a user signal which
   alerts the master to handle the interrupt by reading the pdu answer, then
   to kill the slave. This asynchronous way of receiving allows the master 
   to manage a timeout in order to ask another retransmission when it expires. The 
   timeout is first fixed with respect to the unacknowledged pdu answer number.

   A nice thing to do is to monitor the processes with XPVM (utilization
   vs. time) and realize the efficiency!

   Note: Signals can be employed with pvm, but sometimes, when lots of 
         PDUs arrived to the receiver in a short period of time, some 
         of them are lost. 


4) Files name:
--------------

   PVM++-0.3/README .......................... This file

   PVM++-0.3/c++.classes/include
         defs.h .................................. templates definitions
         vector.h ................................ vector class definitions
         pvm++.h ................................. PVM_Task class definitions
         pdu.h ................................... PDU class definitions
                                                     (packing-unpacking)

   PVM++-0.3/lib ............................. directory to store libs
   PVM++-0.3/src/pvm++ 
         pvm++.cxx ............................... PVM_Task implementation
         pdu.cxx ................................. PDU implementation
                                                   (built in [un]packing fct)

         instantiation.cxx ....................... instantiate template vector
         Makefile ................................ [change it to your needs]

   PVM++-0.3/template/vector.cxx ............. vector implementation

***********
NOTE: files above this line do not need any change for all PVM++ applications!

   PVM++-0.3/Master-Slave
         Makefile ................................ [change it to your needs]
         master.cxx .............................. master implementation
         slave.cxx ............................... slave implementation
         pdu_random.[h + cxx] .................... PDUs derivations

   PVM++-0.3/TokenRing
         Makefile ................................ [change it to your needs]
         main.cxx ................................ token ring implementation
         token.h ................................. PDUs derivations
         ringview.ps ............................. colour postscript analyse (XPVM)

WARNING: The Makefile copies the slave executable in the PVM executable path.
         Adapt it to yours.

HOW TO COMPILE: go to the desired example directory, and type:
                make dep
                make all
                rehash  /* if you have set your PATH variable */
                command-name is 'master -w nb_workers' or 
                                'tokenring NbTurn  NbMembers'

6) Bibliography:
----------------
  For those who want to make the most of C++, I highly recommend:
 
    - The annotated C++ reference manual, ELLIS & STROUSTRUP, Edison Westley
      ISBN 0-201-51459-1

    - C++ inside & out (?!), ECKEL, Mc Graw Hill, ISBN 0-07-881809-5



7) SERIOUSLY: Applying for a position:
------------------------------------

 I'm looking for a laboratory of a university who could host me
 for 16 months:

 I'm finishing an engineer degree in Communication Sciences.
 Every year, the French government allows a few students to accomplish 
 their military service in a foreign country, under a civil form. 
 I will begin mine by the begining of january 1995.

 Should you be interested, please contact me as soon as possible. Thanks.

         voice: (+33) 50.43.71.67 (France)
	 e-mail: cohen_la@di.epfl.ch or
	         cohen@eurecom.fr (till 12/94)


 
